一、nanobot 是什么?一句话概括
nanobot 是一个超轻量级 AI Agent(智能体)框架:用约 4000 行 Python 代码,实现了一个能接入多平台聊天软件、支持多 LLM、带记忆和工具系统的'个人 AI 助手',代码量只有同类项目 Clawdbot / OpenClaw 的 1% 左右。

二、整体架构:从聊天窗口到 LLM 的'神经中枢'
先看一张整体架构示意图:
外部世界 -> LLM Providers -> Agent Core 核心引擎 -> MessageBus -> Channels 通道层 -> 用户侧
- Channels 通道层:Telegram, Feishu, Discord, WhatsApp, CLI 命令行
- MessageBus:asyncio.Queue
- AgentLoop:决策循环
- ContextBuilder:上下文构建
- MemoryStore:记忆系统
- SkillsLoader:技能系统
- ToolRegistry:工具注册
- LLM Providers:OpenRouter, Anthropic Claude, OpenAI GPT, DeepSeek, 本地 vLLM
- 外部世界:文件系统, Shell 命令, Web 搜索/抓取, 定时任务 Cron
2.1 分层职责(从下往上理解)
- Channels 通道层
- 封装了各聊天平台的差异:Telegram、飞书、Discord、WhatsApp 等。
- 每个
Channel 把平台消息转成统一的内部消息格式,推送到 MessageBus。
- 出站时,把统一消息格式再转回各平台的 API 调用。
- MessageBus(消息总线)
- 一个
asyncio.Queue,负责接收所有通道的入站消息,按顺序交给 AgentLoop 处理。
- 解耦'平台接入'和'Agent 决策逻辑'。
- Agent Core(核心引擎)
AgentLoop:主循环,负责从消息总线取消息、调用 LLM、执行工具、控制最大迭代次数(防止死循环)。
ContextBuilder:组装系统提示词,包括身份信息、记忆、技能摘要、历史对话等。
MemoryStore:管理长期记忆(MEMORY.md)和每日笔记(memory/YYYY-MM-DD.md)。
SkillsLoader:加载'技能'(SKILL.md),让 Agent 动态获得新能力。
ToolRegistry:注册文件操作、Shell 执行、Web 搜索等工具。
- LLM Providers
- 通过 LiteLLM 统一封装 OpenRouter、Anthropic、OpenAI、DeepSeek、Gemini、vLLM 等多种后端。
- 配置好 API Key / apiBase,Agent 就能透明切换模型。
- 外部世界
- 文件系统、Shell 命令、Web 搜索、定时任务等,通过工具系统与 Agent 交互。

三、核心原理:ReAct 循环 + 极简工程实现
3.1 Agent Loop:思考—行动—观察的闭环
nanobot 的核心是一个典型的 ReAct(Reasoning + Acting)循环:
用户输入 → 构建上下文 → LLM 推理 → 决定调用工具 / 直接回答 → 执行工具 → 把结果当作新观察 → 再次推理,直到任务完成。
简化版逻辑(概念性伪代码):
class AgentLoop:
def run(self, user_input: str) -> str:
context = self.context_builder.build(user_input)
response = self.llm.complete(context)
if response.has_tool_call:
result = self.tool_executor.execute(response.tool_call)
return self.run(f"Observation: {result}")
else:
return response.content
关键点:
- 最大迭代次数:默认上限约 20 轮,防止工具调用死循环。
- 工具执行沙箱:生产环境建议配置
restrictToWorkspace: true,限制只能在工作目录内操作。
3.2 ContextBuilder:系统提示词是如何'拼出来'的
ContextBuilder 负责把多块信息拼成最终发给 LLM 的 messages:
- 核心身份:当前时间、运行环境、工作目录等。
- Bootstrap 文件:
AGENTS.md、SOUL.md、USER.md、TOOLS.md、IDENTITY.md 等,用户可自定义。
- 记忆上下文:从
MEMORY.md 和最近若干天的日记文件中读取。
- 技能摘要:列出可用技能及其描述。
- 历史对话:当前会话的聊天历史。
- 当前用户消息:支持多模态(如图片)。
这样设计的好处是:所有'人格''记忆''技能'都是可读的 Markdown 文件,调试和定制非常直观。
3.3 Memory:两层记忆系统
nanobot 的记忆系统非常'工程化'又易于理解:
MEMORY.md:长期记忆,存放重要事实、用户偏好、项目背景等。
memory/YYYY-MM-DD.md:每日笔记,自动按日期组织。
MemoryStore 提供:
get_memory_context():返回长期记忆 + 最近 N 天的笔记作为上下文。
append_today():追加到今天的日记。
read_long_term() / write_long_term():读写长期记忆。
效果是:你告诉 nanobot '我的项目代号是 X',它可以在合适的时候自动写入 MEMORY.md,后续对话随时引用。
3.4 Skills & Tools:用 Markdown + Python 插件扩展能力
- 技能(Skills)
- 每个
SKILL.md 文件描述一个能力,如天气查询、GitHub 操作、tmux 终端管理等。
- 头部 YAML 配置
always: true/false,决定是'始终加载'还是'按需加载'。
- 工具(Tools)
- 内置工具包括:
read_file、write_file、edit_file、list_dir、shell、brave_search、fetch_url、message、spawn、cron 等。
- 每个工具都是一个 Python 类,通过
ToolRegistry 注册,Agent 根据工具描述和参数 schema 自动调用。
四、从代码视角看架构:为什么说它是'教学级'项目?
nanobot 的代码结构非常清晰,核心目录大致如下:
nanobot/
├── agent/
│ ├── loop.py
│ ├── context.py
│ ├── memory.py
│ ├── skills.py
│ ├── subagent.py
│ └── tools/
│ ├── filesystem.py
│ ├── shell.py
│ ├── web.py
│ ├── message.py
│ └── ...
├── skills/
├── channels/
├── bus/
├── providers/
├── session/
├── config/
└── cli/
核心特点:
- 约 4000 行核心代码,对比 OpenClaw 的 43 万行,体量小两个数量级。
- 单文件可理解:每个核心模块基本可以在一屏内看完。
- 显式优于隐式:没有'魔法基类'和复杂的元编程,适合学习 Agent 架构。
五、应用案例:从'个人助手'到'团队虚拟员工'
下面是几个比较典型的应用方向,你可以结合自己公司的场景改写。
案例 1:个人知识助手 + 日程管理
场景:你每天在 Telegram / 飞书里跟 nanobot 对话,让它帮你:
- 整理会议纪要、项目文档。
- 记录'项目背景''关键决策'到
MEMORY.md。
- 设置定时提醒:每天早上 9 点自动推送'今日待办'。
实现要点:
- 在工作目录写
AGENTS.md / USER.md,定义你的'人格':
- 你是某产品的负责人;
- 你关心哪些指标;
- 你希望如何被称呼等。
- 使用内置工具:
write_file/edit_file:自动更新项目文档。
cron 工具:添加定时任务,例如每天早上提醒你查看某个看板。
在 ~/.nanobot/config.json 中配置一个默认 Agent 和 LLM 提供商:
{
"agents": {
"defaults": {
"model": "anthropic/claude-sonnet-4-20250514",
"maxTokens": 8192,
"temperature": 0.7
}
},
"providers": {
"openrouter": {
"apiKey": "sk-or-v1-..."
}
}
}
案例 2:飞书群里的'虚拟运维员工'
场景:在飞书群里,@nanobot 发送:
查日志 xxx
重启服务 yyy
查最近 1 小时的异常
nanobot 调用后端 API / 日志平台,把结果回填到群里。
实现要点:
- 在飞书开放平台创建企业自建应用,获取 App ID / App Secret,开通机器人能力和相应权限。
- 编写自定义工具或技能:
- 封装公司内部的日志查询 / 发布部署接口。
- 在
SKILL.md 中描述'运维技能',让 Agent 知道何时调用。
- 在飞书群里 @机器人,即可触发运维操作,无需额外开发 UI。
在 nanobot 中配置 feishu 通道:
"channels": {
"feishu": {
"enabled": true,
"appId": "...",
"appSecret": "...",
"allowFrom": []
}
}
案例 3:Telegram / Discord 的 7×24 小时监控助手
场景:
- 服务器有监控告警(Prometheus / 自定义脚本);
- 你希望异常发生时,nanobot 能自动在 Telegram / Discord 里发消息,甚至尝试自愈。
实现要点:
- 配置
cron 工具,定时执行脚本检查监控指标。
- 当脚本发现异常时,调用 nanobot 的
message 工具,向指定群 / 用户发送告警。
- 可进一步让 nanobot 执行'自愈脚本'(如重启服务、清理磁盘),实现自动修复。
使用 nanobot 的 Telegram / Discord 通道:
nanobot telegram
案例 4:多模型'混合大脑'助手
场景:
- 常规对话用便宜模型;
- 复杂推理 / 代码任务用更强的模型。
实现要点:
- 在
providers 中配置多个 LLM 后端。
- 在
AGENTS.md 中写:
- 对于简单聊天,使用模型 A;
- 对于代码、数据分析,调用模型 B。
- 通过工具 / 技能封装'切换模型'的能力,让 Agent 根据任务类型自动选择模型。
六、与 OpenClaw / Clawdbot 的对比:极简主义的代价
从公开数据对比一下:
| 指标 | OpenClaw(Clawdbot) | nanobot |
|---|
| 核心代码量 | 430,000+ 行 | ~4,000 行 |
| 启动时间 | 数十秒到分钟级 | < 1 秒 |
| 部署复杂度 | 较高,依赖多 | pip install 即可 |
| 可读性 | 认知负荷大 | 一天可通读核心模块 |
| 浏览器自动化等 | 支持 | 不支持 |
| 平台集成数量 | 50+ 平台 | 8–10 个主流平台 |
nanobot 的取舍是:砍掉 20% 的'高级功能',换取 99% 的代码减少和更高的可维护性。对于个人开发者、小团队、研究者来说,这是一个非常'舒服'的平衡。
七、如何在一台服务器上快速部署 nanobot?
简要步骤(你可以整理成'部署实战'章节):
- 启动
- 命令行对话:
nanobot agent
- 启动 Telegram Bot:
nanobot telegram
- 启动飞书等通道:
nanobot gateway
- 配置通道
编辑
~/.nanobot/config.json,按官方文档填写 Telegram / 飞书 / Discord 的凭证。
初始化配置
nanobot onboard
按提示填写 API Key 和默认模型。
安装(任选其一)
pip install nanobot-ai
git clone https://github.com/HKUDS/nanobot.git
cd nanobot && pip install -e .
八、小结:nanobot 的意义
nanobot 并不是要取代所有大型 Agent 框架,而是用 极简架构 + 清晰代码 证明了一件事:
一个功能完整的 AI Agent,不需要几十万行代码,也不需要复杂的'平台化'设计。对于想学习 Agent 原理、搭建个人/团队 AI 助手的开发者来说,nanobot 是一个非常好的'教材级项目'。你可以:通读源码,理解 ReAct 循环、记忆管理、工具调用;在它的基础上,增加你自己的工具和平台适配;把它当作企业内部'虚拟员工'的原型,快速验证想法。