Skip to content
/ nanoclaw-py Public

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

5 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

ApeCodeAI/nanoclaw-py

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
assets
assets
 
 
src/nanoclaw
src/nanoclaw
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
.python-version
.python-version
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 
uv.lock
uv.lock
 
 

Repository files navigation

NanoClaw

nanoclaw-py

Build Your Personal AI Agent in ~500 Lines of Python

Python Claude Code SDK Telegram Bot API License: MIT GitHub stars

Quick Start • Features • Architecture • Configuration • FAQ • 中文

What is this?

nanoclaw-py is a personal AI Agent powered by the Claude Code 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 its Python rewrite with Telegram as the messaging channel (instead of WhatsApp) and 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

Architecture Diagram

✨ Features

Capability Description
Natural Language Powered by Claude Code 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

🚀 Quick Start

Prerequisites

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=sk-ant-api03-...      # Your Anthropic API Key

Need an Anthropic API Key? You can get one at moacode.org, which provides Anthropic API access with a friendly interface.

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 Code 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.

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

快速开始

前置条件

安装步骤

# 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
# 需要 Anthropic API Key？可以在 https://moacode.org/register?ref=bbruceyu 获取

# 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 执行权限，开放给公众会有安全风险。

安全提醒

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

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

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

Built with ❤️ by ApeCode.ai

About

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

Topics

clawdbot moltbot openclaw apecode miniclaw tinyclaw

Resources

Readme
Activity
Custom properties

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages