nanoclaw-py

Build Your Personal AI Agent in ~500 Lines of Python

Quick Start • 7-Day Course • Features • Architecture • Configuration • FAQ • Sponsor • 中文

What is this?

nanoclaw-py is a personal AI Agent powered by the Claude Agent SDK, communicating with you via Telegram. It can read/write files, execute commands, search the web, and schedule tasks — all in ~500 lines of Python.

nanoclaw-py is a Python reinterpretation of the original NanoClaw idea, using Telegram as the messaging channel (instead of WhatsApp) with a focus on simplicity. This project is part of the ApeCode.ai learning series.

This project is heavily inspired by nanoclaw — a brilliant, minimal Claude agent by @gavrielc.

You: @Ape Write a Python script to scrape Hacker News headlines
Ape: Sure, let me create that script...
     ✅ Created workspace/hn_scraper.py

You: @Ape Run it every day at 9am and send me the results
Ape: ✅ Scheduled task created (cron: 0 9 * * *)
     I'll run the script and send you results daily at 9:00

Data Flow

✨ Features

Capability	Description
Natural Language	Powered by Claude Agent SDK, understands complex instructions
File Operations	Read, write, and edit files in the workspace
Command Execution	Run Bash commands and Python scripts
Web Search	Built-in WebSearch / WebFetch tools
Task Scheduling	Cron / interval / one-time tasks with proactive notifications
Long-term Memory	CLAUDE.md persists user preferences across sessions
Conversation History	Daily archives in `conversations/` folder, searchable by Agent
Session Continuity	Auto-restore conversation context after restart

📚 7-Day Course

Want to understand how the complete Agent is built? The episodes/ directory contains seven self-contained, progressively enhanced versions that take you from a Telegram echo bot to the full ~500-line Agent.

Day	Code	What You Build
1	`ep01_echo_bot.py`	Telegram echo bot
2	`ep02_claude_bot.py`	Claude-powered chatbot
3	`ep03_tools_bot.py`	MCP tools and file operations
4	`ep04_bash_bot.py`	Bash execution and web access
5	`ep05_session_bot.py`	Persistent sessions
6	`ep06_memory_bot.py`	Long-term memory and archives
7	`ep07_full_agent.py`	Scheduling and the complete Agent

See the course guide for lesson notes and per-episode instructions.

🚀 Quick Start

Prerequisites

Python 3.12+
uv package manager
Claude Code CLI installed
Telegram Bot Token (from @BotFather)
Anthropic API Key

1. Clone the repo

git clone https://github.com/ApeCodeAI/nanoclaw-py.git
cd nanoclaw-py

2. Install dependencies

uv sync

3. Configure environment

cp .env.example .env

Edit .env with your credentials:

TELEGRAM_BOT_TOKEN=your_bot_token      # From @BotFather
OWNER_ID=your_telegram_user_id          # From @userinfobot
ANTHROPIC_API_KEY=your_anthropic_api_key

💙 Sponsored by BytePass — one API key for Claude, GPT, Gemini, and 50+ models. To use its Anthropic-compatible endpoint, set ANTHROPIC_BASE_URL=https://api.bytepass.ai and use your BytePass API key. BytePass is optional; the official Anthropic API and other compatible endpoints also work.

4. Run

uv run python -m nanoclaw

Open Telegram, send a message to your bot, and start chatting!

🏗 Architecture

src/nanoclaw/           533 lines of code (9 files)
├── __main__.py          52 lines  ← Entry point
├── config.py            50 lines  ← Environment variables & paths
├── db.py               114 lines  ← SQLite async operations (tasks only)
├── memory.py            44 lines  ← CLAUDE.md long-term memory
├── agent.py            210 lines  ← Claude Agent SDK + 6 MCP tools
├── scheduler.py         75 lines  ← APScheduler task execution
├── bot.py               69 lines  ← Telegram Bot handlers
└── conversations.py     69 lines  ← Daily conversation archiving

MCP Tools

The Agent interacts with Telegram and the scheduler through these MCP tools:

Tool	Purpose
`send_message`	Proactively send messages (during tasks/long operations)
`schedule_task`	Create scheduled tasks (cron/interval/once)
`list_tasks`	List all scheduled tasks
`pause_task`	Pause a task
`resume_task`	Resume a paused task
`cancel_task`	Delete a task

⚙️ Configuration

Variable	Required	Default	Description
`TELEGRAM_BOT_TOKEN`	✅	—	Telegram Bot Token
`OWNER_ID`	✅	—	Your Telegram user ID
`ANTHROPIC_API_KEY`	✅	—	Anthropic API Key
`ANTHROPIC_BASE_URL`	—	Official	Custom API endpoint (proxy/gateway)
`ASSISTANT_NAME`	—	`Ape`	Assistant's name
`SCHEDULER_INTERVAL`	—	`60`	Task check interval (seconds)

Custom API Endpoint: Set ANTHROPIC_BASE_URL to route requests through LiteLLM proxy, enterprise gateway, or any Anthropic Messages API compatible endpoint.

📂 Data Directories

Directory	Purpose	Persistent
`workspace/`	Agent's working directory for file operations	✅
`workspace/CLAUDE.md`	Long-term memory (preferences, facts)	✅
`workspace/conversations/`	Daily chat archives (YYYY-MM-DD.md)	✅
`store/nanoclaw.db`	SQLite database (scheduled tasks only)	✅
`data/state.json`	Session ID for conversation continuity	✅

🤖 Bot Commands

Command	Description
`/start`	Show welcome message
`/clear`	Clear current session, start fresh
Any text	Chat with the AI

❓ FAQ

How do I get my Telegram user ID?

Search for @userinfobot on Telegram and send any message. It will reply with your user ID.

Why single-user only?

This is an educational project. The OWNER_ID restriction ensures only you can use it. The Agent has Bash execution privileges — exposing it publicly would be a security risk.

Does the session persist after restart?

Yes. Session is persisted via session_id in data/state.json and auto-restored on restart. Long-term memory in workspace/CLAUDE.md survives even /clear commands.

Do scheduled tasks survive restart?

Yes. Tasks are stored in SQLite and the scheduler automatically picks up due tasks after restart.

Can I use a proxy or custom API endpoint?

Yes. Set ANTHROPIC_BASE_URL to your proxy address. It must be compatible with the Anthropic Messages API format.

💙 Sponsor

Thanks to BytePass for sponsoring nanoclaw-py. BytePass provides pay-as-you-go access to Claude, GPT, Gemini, and more through one API key, including an Anthropic-compatible endpoint for Claude Code and this project.

Website: bytepass.ai
API endpoint: https://api.bytepass.ai

🔒 Security Notice

This project is for personal learning and private deployment only. The Agent can execute arbitrary commands (bypassPermissions mode). Do NOT deploy publicly or share access with others.

📄 License

MIT

🇨🇳 中文文档

这是什么？

nanoclaw-py 是一个个人 AI Agent，基于 Claude Agent SDK，通过 Telegram 与你对话。它能读写文件、执行命令、搜索网页、调度定时任务——所有这些，仅用 ~500 行 Python。

本项目高度参考了 nanoclaw——由 @gavrielc 开发的极简 Claude Agent 项目。nanoclaw-py 是其 Python 重写版本，使用 Telegram 作为消息通道（而非 WhatsApp），更注重简洁性。

本项目是 ApeCode.ai 学习系列的一部分。

你: @Ape 帮我写一个 Python 脚本，爬取 Hacker News 首页标题
Ape: 好的，我来创建这个脚本...
     ✅ 已创建 workspace/hn_scraper.py

你: @Ape 每天早上 9 点运行一次，把结果发给我
Ape: ✅ 已创建定时任务 (cron: 0 9 * * *)
     每天 9:00 我会运行脚本并把结果发到这里

功能特性

能力	描述
自然语言对话	基于 Claude Agent SDK，理解复杂指令
文件操作	在 workspace 中读写、编辑文件
命令执行	运行 Bash 命令、Python 脚本
网络搜索	内置 WebSearch / WebFetch 工具
定时任务	Cron / 间隔 / 一次性任务调度，主动推送结果
长期记忆	CLAUDE.md 持久化用户偏好，跨会话保留
对话历史	每日归档到 `conversations/` 文件夹，Agent 可搜索
会话连续	Session 自动恢复，重启不丢上下文

📚 7 天渐进课程

想从零理解完整 Agent 是如何搭建出来的？episodes/ 目录提供了 7 份可以独立运行、逐日增强的代码，从 Telegram Echo Bot 一直构建到约 500 行的完整 Agent。

天数	代码	本日目标
Day 1	`ep01_echo_bot.py`	Telegram Echo Bot
Day 2	`ep02_claude_bot.py`	接入 Claude
Day 3	`ep03_tools_bot.py`	MCP 工具和文件操作
Day 4	`ep04_bash_bot.py`	Bash 执行和网络访问
Day 5	`ep05_session_bot.py`	会话持久化
Day 6	`ep06_memory_bot.py`	长期记忆和对话归档
Day 7	`ep07_full_agent.py`	定时任务和完整 Agent

课程讲解、配置方式和每日学习要点见 episodes/README.md。

快速开始

前置条件

Python 3.12+
uv 包管理器
Claude Code CLI 已安装
Telegram Bot Token（@BotFather 获取）
Anthropic API Key

安装步骤

# 1. 克隆项目
git clone https://github.com/ApeCodeAI/nanoclaw-py.git
cd nanoclaw-py

# 2. 安装依赖
uv sync

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的 Token 和 API Key

# 可选：使用 BytePass 等兼容 Anthropic API 的服务
# ANTHROPIC_BASE_URL=https://api.bytepass.ai

# 4. 启动
uv run python -m nanoclaw

打开 Telegram，给你的 Bot 发送消息，开始对话！

配置说明

变量	必填	默认值	说明
`TELEGRAM_BOT_TOKEN`	✅	—	Telegram Bot Token
`OWNER_ID`	✅	—	你的 Telegram 用户 ID
`ANTHROPIC_API_KEY`	✅	—	Anthropic API Key
`ANTHROPIC_BASE_URL`	—	官方	自定义 API 端点（代理/网关）
`ASSISTANT_NAME`	—	`Ape`	助手名称

获取用户 ID：在 Telegram 搜索 @userinfobot，发送任意消息即可获取。

常见问题

可以用国内 API 代理吗？

可以。设置 ANTHROPIC_BASE_URL 为你的代理地址即可，需兼容 Anthropic Messages API 格式。

重启后会话还在吗？

会话通过 session_id 持久化到 data/state.json，重启后自动恢复。长期记忆保存在 workspace/CLAUDE.md，即使 /clear 重置会话也不会丢失。

为什么只支持单用户？

这是一个教学项目，通过 OWNER_ID 限制只有你自己可以使用。Agent 拥有 Bash 执行权限，开放给公众会有安全风险。

💙 赞助商

感谢 BytePass 对 nanoclaw-py 的赞助。BytePass 使用一个 API Key 提供 Claude、GPT、Gemini 等 50+ 模型的按量访问，并提供兼容 Anthropic API 的 endpoint，可用于 Claude Code 和本项目。

网站：bytepass.ai
API endpoint：https://api.bytepass.ai
BytePass 为可选服务；本项目同样支持 Anthropic 官方 API 及其他兼容 endpoint。

安全提醒

本项目仅供个人学习和私有部署使用。 Agent 具有执行任意命令的能力，切勿部署到公网或开放给他人使用。

If you find this useful, please give it a ⭐!

觉得有用？请给个 ⭐ 支持一下！

Built with ❤️ by ApeCode.ai · Sponsored by BytePass

Name		Name	Last commit message	Last commit date
assets		assets
episodes		episodes
src/nanoclaw		src/nanoclaw
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Uh oh!

Repository files navigation

nanoclaw-py

What is this?

Data Flow

✨ Features

📚 7-Day Course

🚀 Quick Start

Prerequisites

1. Clone the repo

2. Install dependencies

3. Configure environment

4. Run

🏗 Architecture

MCP Tools

⚙️ Configuration

📂 Data Directories

🤖 Bot Commands

❓ FAQ

💙 Sponsor

🔒 Security Notice

📄 License

🇨🇳 中文文档

这是什么？

功能特性

📚 7 天渐进课程

快速开始

前置条件

安装步骤

配置说明

常见问题

💙 赞助商

安全提醒

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

nanoclaw-py

What is this?

Data Flow

✨ Features

📚 7-Day Course

🚀 Quick Start

Prerequisites

1. Clone the repo

2. Install dependencies

3. Configure environment

4. Run

🏗 Architecture

MCP Tools

⚙️ Configuration

📂 Data Directories

🤖 Bot Commands

❓ FAQ

💙 Sponsor

🔒 Security Notice

📄 License

🇨🇳 中文文档

这是什么？

功能特性

📚 7 天渐进课程

快速开始

前置条件

安装步骤

配置说明

常见问题

💙 赞助商

安全提醒

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages