nanoclaw-py

KO | EN

gitlite — search

#javascript #php #swift #nodejs #python #css #haskell #android #react #api #example #scala

★ 189 Open GitHub ↗

Yet another nano alternative to OpenClaw. It can read/write files, execute commands, search the web, and schedule tasks — all in ~500 lines of Python.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# nanoclaw-py

**Build Your Personal AI Agent in ~500 Lines of Python**

[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Claude Agent SDK](https://img.shields.io/badge/Claude_Agent_SDK-Anthropic-cc785c?style=flat-square&logo=anthropic&logoColor=white)](https://code.claude.com/docs/en/agent-sdk/overview)
[![Telegram Bot API](https://img.shields.io/badge/Telegram_Bot_API-v22-26A5E4?style=flat-square&logo=telegram&logoColor=white)](https://python-telegram-bot.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://raw.githubusercontent.com/ApeCodeAI/nanoclaw-py/master/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ApeCodeAI/nanoclaw-py?style=flat-square&logo=github)](https://github.com/ApeCodeAI/nanoclaw-py/stargazers)
[![ApeCode.ai](https://img.shields.io/badge/🦧_ApeCode.ai-AI_Tools-orange?style=flat-square)](https://apecode.ai)
[![Sponsored by BytePass](https://img.shields.io/badge/Sponsored%20by-BytePass-2563EB?style=flat-square)](https://bytepass.ai)

<p>
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-7-day-course">7-Day Course</a> •
  <a href="#-features">Features</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#%EF%B8%8F-configuration">Configuration</a> •
  <a href="#-faq">FAQ</a> •
  <a href="#-sponsor">Sponsor</a> •
  <a href="#-中文文档">中文</a>
</p>

</div>

---

## 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](https://apecode.ai) learning series.
> This project is heavily inspired by [**nanoclaw**](https://github.com/gavrielc/nanoclaw) — a brilliant, minimal Claude agent by [@gavrielc](https://github.com/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/`](./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`](./episodes/ep01_echo_bot.py) | Telegram echo bot |
| 2 | [`ep02_claude_bot.py`](./episodes/ep02_claude_bot.py) | Claude-powered chatbot |
| 3 | [`ep03_tools_bot.py`](./episodes/ep03_tools_bot.py) | MCP tools and file operations |
| 4 | [`ep04_bash_bot.py`](./episodes/ep04_bash_bot.py) | Bash execution and web access |
| 5 | [`ep05_session_bot.py`](./episodes/ep05_session_bot.py) | Persistent sessions |
| 6 | [`ep06_memory_bot.py`](./episodes/ep06_memory_bot.py) | Long-term memory and archives |
| 7 | [`ep07_full_agent.py`](./episodes/ep07_full_agent.py) | Scheduling and the complete Agent |

See the [course guide](./episodes/README.md) for lesson notes and per-episode instructions.

## 🚀 Quick Start

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
- Telegram Bot Token (from [@BotFather](https://t.me/BotFather))
- Anthropic API Key

### 1. Clone the repo

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

### 2. Install dependencies

```bash
uv sync
```

### 3. Configure environment

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```bash
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](https://bytepass.ai)** — 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

```bash
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

<details>
<summary><b>How do I get my Telegram user ID?</b></summary>

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

</details>

<details>
<summary><b>Why single-user only?</b></summary>

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.

</details>

<details>
<summary><b>Does the session persist after restart?</b></summary>

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.

</details>

<details>
<summary><b>Do scheduled tasks survive restart?</b></summary>

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

</details>

<details>
<summary><b>Can I use a proxy or custom API endpoint?</b></summary>

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

</details>

## 💙 Sponsor

Thanks to [**BytePass**](https://bytepass.ai) 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](https://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](LICENSE)

---

# 🇨🇳 中文文档

## 这是什么？

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

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

本项目是 [ApeCode.ai](https://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/`](./episodes/) 目录提供了 7 份可以独立运行、逐日增强的代码，从 Telegram Echo Bot 一直构建到约 500 行的完整 Agent。

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

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

## 快速开始

### 前置条件

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) 包管理器
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 已安装
- Telegram Bot Token（[@BotFather](https://t.me/BotFather) 获取）
- Anthropic API Key

### 安装步骤

```bash
# 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`，发送任意消息即可获取。

## 常见问题

<details>
<summary><b>可以用国内 API 代理吗？</b></summary>

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

</details>

<details>
<summary><b>重启后会话还在吗？</b></summary>

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

</details>

<details>
<summary><b>为什么只支持单用户？</b></summary>

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

</details>

## 💙 赞助商

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

- 网站：[bytepass.ai](https://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](https://apecode.ai) · Sponsored by [BytePass](https://bytepass.ai)

</div>

nanoclaw-py

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README