🐈 nanobot 是一个受 OpenClaw 启发 的超轻量级 (ultra-lightweight) 个人 AI 助手。
📖 这份代码是 nanobot 的 v0.1.3.post7 版本,主要用于源码阅读。此版本的代码量比最新版本要少不少,约六千多行 Python。
⚡️ 核心 agent 功能仅需约 4,000 行代码 — 比 Clawdbot 的 430k+ 行少 99%。
📏 实时代码行数:3,582 行(运行 bash core_agent_lines.sh 随时验证)。
- 2026-02-12 🧠 重新设计的记忆系统 (memory system) — 更少的代码,更高的可靠性。参与讨论!
- 2026-02-10 🎉 发布 v0.1.3.post6,各项改进!查看更新说明和我们的路线图。
- 2026-02-09 💬 新增 Slack、Email 和 QQ 支持 — nanobot 现已支持多个聊天平台!
- 2026-02-08 🔧 重构 Provider — 现在只需 2 个简单步骤即可添加新的 LLM provider!查看此处。
- 2026-02-07 🚀 发布 v0.1.3.post5,支持 Qwen 及多项关键改进!查看详情。
- 2026-02-06 ✨ 新增 Moonshot/Kimi provider、Discord 集成和安全加固!
- 2026-02-05 ✨ 新增飞书 (Feishu) 频道、DeepSeek provider 和增强的定时任务支持!
- 2026-02-04 🚀 发布 v0.1.3.post4,支持多 provider 和 Docker!查看详情。
- 2026-02-03 ⚡ 集成 vLLM,支持本地 LLM 和改进的自然语言任务调度!
- 2026-02-02 🎉 nanobot 正式发布!欢迎体验 🐈 nanobot!
🪶 超轻量级 (Ultra-Lightweight):仅约 4,000 行核心 agent 代码 — 比 Clawdbot 小 99%。
🔬 适合研究 (Research-Ready):代码清晰易读,易于理解、修改和扩展,用于研究目的。
⚡️ 闪电般快速 (Lightning Fast):最小化的占用空间意味着更快的启动、更低的资源消耗和更快的迭代。
💎 易于使用 (Easy-to-Use):一键部署,即可使用。
📈 24/7 实时市场分析 (Real-Time Market Analysis) |
🚀 全栈软件工程师 (Full-Stack Software Engineer) |
📅 智能日程管理 (Smart Daily Routine Manager) |
📚 个人知识助手 (Personal Knowledge Assistant) |
|---|---|---|---|
| 发现 • 洞察 • 趋势 (Discovery • Insights • Trends) | 开发 • 部署 • 扩展 (Develop • Deploy • Scale) | 调度 • 自动化 • 整理 (Schedule • Automate • Organize) | 学习 • 记忆 • 推理 (Learn • Memory • Reasoning) |
从源码安装 (latest features, recommended for development)
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .使用 uv 安装 (stable, fast)
uv tool install nanobot-ai从 PyPI 安装 (stable)
pip install nanobot-aiTip
在 ~/.nanobot/config.json 中设置你的 API key。
获取 API keys: OpenRouter (全球) · Brave Search (可选,用于网络搜索)
1. 初始化 (Initialize)
nanobot onboard2. 配置 (Configure) (~/.nanobot/config.json)
对于 OpenRouter - 推荐全球用户使用:
{
"providers": {
"openrouter": {
"apiKey": "sk-or-v1-xxx"
}
},
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-5"
}
}
}3. 聊天 (Chat)
nanobot agent -m "What is 2+2?"就这样!你可以在 2 分钟内拥有一个可用的 AI 助手。
使用 vLLM 或任何 OpenAI 兼容服务器运行带有你自己的本地模型的 nanobot。
1. 启动你的 vLLM 服务器 (Start your vLLM server)
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 80002. 配置 (Configure) (~/.nanobot/config.json)
{
"providers": {
"vllm": {
"apiKey": "dummy",
"apiBase": "http://localhost:8000/v1"
}
},
"agents": {
"defaults": {
"model": "meta-llama/Llama-3.1-8B-Instruct"
}
}
}3. 聊天 (Chat)
nanobot agent -m "Hello from my local LLM!"Tip
对于不需要认证的本地服务器,apiKey 可以是任何非空字符串。
通过 Telegram、Discord、WhatsApp、飞书 (Feishu)、Mochat、钉钉 (DingTalk)、Slack、Email 或 QQ 与你的 nanobot 交谈 — 随时随地。
| 渠道 (Channel) | 设置难度 (Setup) |
|---|---|
| Telegram | 简单 (Easy) (只需一个 token) |
| Discord | 简单 (Easy) (bot token + intents) |
| 中等 (Medium) (扫描 QR) | |
| 飞书 (Feishu) | 中等 (Medium) (app credentials) |
| Mochat | 中等 (Medium) (claw token + websocket) |
| 钉钉 (DingTalk) | 中等 (Medium) (app credentials) |
| Slack | 中等 (Medium) (bot + app tokens) |
| 中等 (Medium) (IMAP/SMTP credentials) | |
| 简单 (Easy) (app credentials) |
Telegram (推荐 / Recommended)
1. 创建一个 bot (Create a bot)
- 打开 Telegram,搜索
@BotFather - 发送
/newbot,按照提示操作 - 复制 token
2. 配置 (Configure)
{
"channels": {
"telegram": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allowFrom": ["YOUR_USER_ID"]
}
}
}你可以在 Telegram 设置中找到你的 User ID。显示为
@yourUserId。 去掉@符号后复制此值,粘贴到配置文件中。
3. 运行 (Run)
nanobot gatewayMochat (Claw IM)
默认使用 Socket.IO WebSocket,并有 HTTP polling 作为后备。
1. 让 nanobot 为你设置 Mochat
只需发送此消息给 nanobot(将 xxx@xxx 替换为你的真实邮箱):
Read https://raw.githubusercontent.com/HKUDS/MoChat/refs/heads/main/skills/nanobot/skill.md and register on MoChat. My Email account is xxx@xxx Bind me as your owner and DM me on MoChat.
nanobot 将自动注册、配置 ~/.nanobot/config.json 并连接到 Mochat。
2. 重启 gateway (Restart gateway)
nanobot gateway就这样 — nanobot 会处理其余一切!
手动配置 (advanced)
如果你更喜欢手动配置,将以下内容添加到 ~/.nanobot/config.json:
保持
claw_token私密。它只应在你向 Mochat API 端点发送的X-Claw-Tokenheader 中使用。
{
"channels": {
"mochat": {
"enabled": true,
"base_url": "https://mochat.io",
"socket_url": "https://mochat.io",
"socket_path": "/socket.io",
"claw_token": "claw_xxx",
"agent_user_id": "6982abcdef",
"sessions": ["*"],
"panels": ["*"],
"reply_delay_mode": "non-mention",
"reply_delay_ms": 120000
}
}
}Discord
1. 创建一个 bot (Create a bot)
- 前往 https://discord.com/developers/applications
- 创建应用程序 → Bot → 添加 Bot
- 复制 bot token
2. 启用 intents (Enable intents)
- 在 Bot 设置中,启用 MESSAGE CONTENT INTENT
- (可选)如果你计划使用基于成员数据的允许列表,启用 SERVER MEMBERS INTENT
3. 获取你的 User ID (Get your User ID)
- Discord 设置 → 高级 → 启用 开发者模式 (Developer Mode)
- 右键点击你的头像 → 复制用户 ID (Copy User ID)
4. 配置 (Configure)
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allowFrom": ["YOUR_USER_ID"]
}
}
}5. 邀请 bot (Invite the bot)
- OAuth2 → URL Generator
- Scopes:
bot - Bot Permissions:
Send Messages,Read Message History - 打开生成的邀请 URL,将 bot 添加到你的服务器
6. 运行 (Run)
nanobot gateway需要 Node.js ≥18。
1. 关联设备 (Link device)
nanobot channels login
# 用 WhatsApp → 设置 → 已关联的设备 扫描 QR2. 配置 (Configure)
{
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["+1234567890"]
}
}
}3. 运行 (Run) (两个终端 / two terminals)
# Terminal 1
nanobot channels login
# Terminal 2
nanobot gateway飞书 (Feishu)
使用 WebSocket 长连接 — 无需公网 IP。
1. 创建一个飞书 bot (Create a Feishu bot)
- 访问 飞书开放平台 (Feishu Open Platform)
- 创建新应用 → 启用 Bot 能力
- 权限 (Permissions):添加
im:message(发送消息) - 事件 (Events):添加
im.message.receive_v1(接收消息)- 选择长连接 (Long Connection) 模式(需要先运行 nanobot 以建立连接)
- 从"凭证与基础信息"获取 App ID 和 App Secret
- 发布应用
2. 配置 (Configure)
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxx",
"appSecret": "xxx",
"encryptKey": "",
"verificationToken": "",
"allowFrom": []
}
}
}长连接模式下
encryptKey和verificationToken是可选的。allowFrom:留空允许所有用户,或添加["ou_xxx"]限制访问。
3. 运行 (Run)
nanobot gateway[!TIP] 飞书使用 WebSocket 接收消息 — 无需 webhook 或公网 IP!
QQ (QQ单聊)
使用 botpy SDK 配合 WebSocket — 无需公网 IP。目前仅支持私聊 (private messages)。
1. 注册并创建 bot (Register & create bot)
- 访问 QQ 开放平台 (QQ Open Platform) → 注册为开发者(个人或企业)
- 创建新的 bot 应用
- 进入开发设置 (Developer Settings) → 复制 AppID 和 AppSecret
2. 设置沙箱进行测试 (Set up sandbox for testing)
- 在 bot 管理控制台中找到沙箱配置 (Sandbox Config)
- 在消息列表配置下,点击添加成员并添加你自己的 QQ 号
- 添加后,用手机 QQ 扫描 bot 的 QR 码 → 打开 bot 个人资料 → 点击"发消息"开始聊天
3. 配置 (Configure)
allowFrom:留空公开访问,或添加用户 openid 限制访问。你可以在 nanobot 日志中找到 openid,当用户向 bot 发消息时。- 对于生产环境:在 bot 控制台提交审核并发布。查看 QQ Bot 文档 了解完整的发布流程。
{
"channels": {
"qq": {
"enabled": true,
"appId": "YOUR_APP_ID",
"secret": "YOUR_APP_SECRET",
"allowFrom": []
}
}
}4. 运行 (Run)
nanobot gateway现在从 QQ 向 bot 发送消息 — 它应该会回复!
钉钉 (DingTalk)
使用流模式 (Stream Mode) — 无需公网 IP。
1. 创建一个钉钉 bot (Create a DingTalk bot)
- 访问 钉钉开放平台 (DingTalk Open Platform)
- 创建新应用 -> 添加 Robot 能力
- 配置 (Configuration):
- 开启流模式 (Stream Mode)
- 权限 (Permissions):添加发送消息所需的权限
- 从"凭证"获取 AppKey(Client ID)和 AppSecret(Client Secret)
- 发布应用
2. 配置 (Configure)
{
"channels": {
"dingtalk": {
"enabled": true,
"clientId": "YOUR_APP_KEY",
"clientSecret": "YOUR_APP_SECRET",
"allowFrom": []
}
}
}
allowFrom:留空允许所有用户,或添加["staffId"]限制访问。
3. 运行 (Run)
nanobot gatewaySlack
使用套接字模式 (Socket Mode) — 无需公共 URL。
1. 创建一个 Slack 应用 (Create a Slack app)
- 前往 Slack API → 创建新应用 (Create New App) → "从零开始 (From scratch)"
- 选择名称并选择你的工作区
2. 配置应用 (Configure the app)
- Socket Mode:开启 → 生成具有
connections:write作用域的应用级令牌 (App-Level Token) → 复制(xapp-...) - OAuth & Permissions:添加 bot scopes:
chat:write、reactions:write、app_mentions:read - Event Subscriptions:开启 → 订阅 bot 事件:
message.im、message.channels、app_mention→ 保存更改 - App Home:滚动到显示标签页 (Show Tabs) → 启用消息标签页 (Messages Tab) → 勾选**"允许用户从消息标签页发送斜杠命令和消息"**
- 安装应用 (Install App):点击安装到工作区 (Install to Workspace) → 授权 → 复制 Bot Token(
xoxb-...)
3. 配置 nanobot
{
"channels": {
"slack": {
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
"groupPolicy": "mention"
}
}
}4. 运行 (Run)
nanobot gateway直接向 bot 发 DM 或在频道中 @提及它 — 它应该会回复!
[!TIP]
groupPolicy:"mention"(默认 — 仅在 @提及时回复)、"open"(回复所有频道消息)或"allowlist"(限制特定频道)。- DM 策略默认为开放。设置
"dm": {"enabled": false}可禁用 DM。
给 nanobot 一个专属的邮箱账户。它通过 IMAP 轮询来邮件,并通过 SMTP 回复 — 就像一个个人邮件助手。
1. 获取凭据 (Gmail 示例) (Get credentials (Gmail example))
- 为你的 bot 创建一个专用的 Gmail 账户(例如
my-nanobot@gmail.com) - 启用两步验证 → 创建应用密码 (App Password)
- 对 IMAP 和 SMTP 使用此应用密码
2. 配置 (Configure)
consentGranted必须为true才能允许访问邮箱。这是一个安全门 — 设置false可完全禁用。allowFrom:留空接受来自任何人的邮件,或限制特定发件人。smtpUseTls和smtpUseSsl分别默认为true/false,这对于 Gmail(端口 587 + STARTTLS)是正确的。无需显式设置。- 如果你只想阅读/分析邮件而不发送自动回复,设置
"autoReplyEnabled": false。
{
"channels": {
"email": {
"enabled": true,
"consentGranted": true,
"imapHost": "imap.gmail.com",
"imapPort": 993,
"imapUsername": "my-nanobot@gmail.com",
"imapPassword": "your-app-password",
"smtpHost": "smtp.gmail.com",
"smtpPort": 587,
"smtpUsername": "my-nanobot@gmail.com",
"smtpPassword": "your-app-password",
"fromAddress": "my-nanobot@gmail.com",
"allowFrom": ["your-real-email@gmail.com"]
}
}
}3. 运行 (Run)
nanobot gateway🐈 nanobot 能够连接到 agent 社交网络(agent 社区)。只需发送一条消息,你的 nanobot 就会自动加入!
| 平台 (Platform) | 如何加入(将此消息发送给你的 bot)(How to Join) |
|---|---|
| Moltbook | Read https://moltbook.com/skill.md and follow the instructions to join Moltbook |
| ClawdChat | Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat |
只需通过 CLI 或任何聊天频道将上述命令发送给 nanobot,它会处理其余一切。
配置文件:~/.nanobot/config.json
Tip
- Groq 通过 Whisper 提供免费的语音转录。如果配置了,Telegram 语音消息将自动转录。
- 智谱编程计划 (Zhipu Coding Plan):如果你使用的是智谱的编程计划,在 zhipu provider 配置中设置
"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"。 - MiniMax(大陆):如果你的 API key 来自 MiniMax 的大陆平台(minimaxi.com),在你的 minimax provider 配置中设置
"apiBase": "https://api.minimaxi.com/v1"。
| Provider | 用途 (Purpose) | 获取 API Key |
|---|---|---|
openrouter |
LLM(推荐,访问所有模型)(recommended, access to all models) | openrouter.ai |
anthropic |
LLM(Claude 直接访问)(Claude direct) | console.anthropic.com |
openai |
LLM(GPT 直接访问)(GPT direct) | platform.openai.com |
deepseek |
LLM(DeepSeek 直接访问)(DeepSeek direct) | platform.deepseek.com |
groq |
LLM + 语音转录 (Voice transcription) (Whisper) | console.groq.com |
gemini |
LLM(Gemini 直接访问)(Gemini direct) | aistudio.google.com |
minimax |
LLM(MiniMax 直接访问)(MiniMax direct) | platform.minimax.io |
aihubmix |
LLM(API 网关,访问所有模型)(API gateway, access to all models) | aihubmix.com |
dashscope |
LLM(Qwen) | dashscope.console.aliyun.com |
moonshot |
LLM(Moonshot/Kimi) | platform.moonshot.cn |
zhipu |
LLM(智谱 GLM)(Zhipu GLM) | open.bigmodel.cn |
vllm |
LLM(本地,任何 OpenAI 兼容服务器)(local, any OpenAI-compatible server) | — |
添加新的 Provider(开发者指南)(Adding a New Provider)
nanobot 使用Provider 注册表 (nanobot/providers/registry.py) 作为唯一事实来源。
添加一个新的 provider 只需2 个步骤 — 无需修改 if-elif 链。
步骤 1。 在 nanobot/providers/registry.py 的 PROVIDERS 中添加 ProviderSpec 条目:
ProviderSpec(
name="myprovider", # 配置字段名 (config field name)
keywords=("myprovider", "mymodel"), # 用于自动匹配的模型名关键词 (model-name keywords for auto-matching)
env_key="MYPROVIDER_API_KEY", # LiteLLM 的环境变量 (env var for LiteLLM)
display_name="My Provider", # 在 `nanobot status` 中显示 (shown in `nanobot status`)
litellm_prefix="myprovider", # 自动前缀:模型 → myprovider/model
skip_prefixes=("myprovider/",), # 不要双重前缀 (don't double-prefix)
)步骤 2。 在 nanobot/config/schema.py 的 ProvidersConfig 中添加字段:
class ProvidersConfig(BaseModel):
...
myprovider: ProviderConfig = ProviderConfig()就这样!环境变量、模型前缀、配置匹配和 nanobot status 显示都会自动工作。
常用的 ProviderSpec 选项:
| 字段 (Field) | 描述 (Description) | 示例 (Example) |
|---|---|---|
litellm_prefix |
为 LiteLLM 自动添加模型名前缀 | "dashscope" → dashscope/qwen-max |
skip_prefixes |
如果模型已以这些开头则不添加前缀 | ("dashscope/", "openrouter/") |
env_extras |
要设置的其他环境变量 | (("ZHIPUAI_API_KEY", "{api_key}"),) |
model_overrides |
按模型覆盖参数 | (("kimi-k2.5", {"temperature": 1.0}),) |
is_gateway |
可以路由任何模型(如 OpenRouter) | True |
detect_by_key_prefix |
通过 API key 前缀检测网关 | "sk-or-" |
detect_by_base_keyword |
通过 API 基础 URL 检测网关 | "openrouter" |
strip_model_prefix |
在重新前缀之前去除现有前缀 | True(用于 AiHubMix) |
对于生产部署,在配置中设置
"restrictToWorkspace": true以沙箱化 agent。
| 选项 (Option) | 默认 (Default) | 描述 (Description) |
|---|---|---|
tools.restrictToWorkspace |
false |
当为 true 时,将所有 agent 工具(shell、文件读/写/编辑、列表)限制在工作区目录内。防止路径遍历和越界访问。 |
channels.*.allowFrom |
[](允许所有人)(allow all) |
用户 ID 白名单。空 = 允许所有人;非空 = 仅列出的用户可以交互。 |
| 命令 (Command) | 描述 (Description) |
|---|---|
nanobot onboard |
初始化配置和工作区 (Initialize config & workspace) |
nanobot agent -m "..." |
与 agent 聊天 (Chat with the agent) |
nanobot agent |
交互式聊天模式 (Interactive chat mode) |
nanobot agent --no-markdown |
显示纯文本回复 (Show plain-text replies) |
nanobot agent --logs |
在聊天期间显示运行时日志 (Show runtime logs during chat) |
nanobot gateway |
启动 gateway |
nanobot status |
显示状态 (Show status) |
nanobot channels login |
关联 WhatsApp(扫描 QR)(Link WhatsApp) |
nanobot channels status |
显示渠道状态 (Show channel status) |
交互模式退出命令:exit、quit、/exit、/quit、:q 或 Ctrl+D。
定时任务 (Scheduled Tasks) (Cron)
# 添加任务 (Add a job)
nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
nanobot cron add --name "hourly" --message "Check status" --every 3600
# 列出任务 (List jobs)
nanobot cron list
# 删除任务 (Remove a job)
nanobot cron remove <job_id>Tip
-v ~/.nanobot:/root/.nanobot 标志将你的本地配置目录挂载到容器中,这样你的配置和工作区在容器重启后就会保留。
在容器中构建和运行 nanobot:
# 构建镜像 (Build the image)
docker build -t nanobot .
# 初始化配置(仅首次)(Initialize config (first time only))
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard
# 在主机上编辑配置以添加 API keys
vim ~/.nanobot/config.json
# 运行 gateway(连接到已启用的渠道,例如 Telegram/Discord/Mochat)
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway
# 或者运行单个命令
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot statusnanobot/
├── agent/ # 🧠 核心 agent 逻辑 (Core agent logic)
│ ├── loop.py # Agent 循环 (Agent loop)(LLM ↔ 工具执行 (tool execution))
│ ├── context.py # Prompt 构建器 (Prompt builder)
│ ├── memory.py # 持久化记忆 (Persistent memory)
│ ├── skills.py # 技能加载器 (Skills loader)
│ ├── subagent.py # 后台任务执行 (Background task execution)
│ └── tools/ # 内置工具 (Built-in tools)(包括 spawn)
├── skills/ # 🎯 捆绑技能 (Bundled skills)(github, weather, tmux...)
├── channels/ # 📱 聊天渠道集成 (Chat channel integrations)
├── bus/ # 🚌 消息路由 (Message routing)
├── cron/ # ⏰ 定时任务 (Scheduled tasks)
├── heartbeat/ # 💓 主动唤醒 (Proactive wake-up)
├── providers/ # 🤖 LLM providers(OpenRouter 等)
├── session/ # 💬 对话会话 (Conversation sessions)
├── config/ # ⚙️ 配置 (Configuration)
└── cli/ # 🖥️ 命令 (Commands)
欢迎提交 PR!代码库特意保持小而可读。🤗
路线图 (Roadmap) — 选择一个项目提交 PR!
- 语音转录 (Voice Transcription) — 支持 Groq Whisper(问题 #13)
- 多模态 (Multi-modal) — 看和听(图像、语音、视频)
- 长期记忆 (Long-term memory) — 永不忘记重要的上下文
- 更好的推理 (Better reasoning) — 多步骤规划和反思
- 更多集成 (More integrations) — 日历等
- 自我改进 (Self-improvement) — 从反馈和错误中学习
nanobot 仅用于教育、研究和技术交流目的





