深入解析了 nanobot 这一超轻量级 AI Agent 框架的原理与架构。nanobot 仅用约 4000 行 Python 代码实现了多平台接入、多 LLM 支持及记忆工具系统。文章详细阐述了其分层架构（Channels、MessageBus、Agent Core 等）、基于 ReAct 循环的核心原理、两层记忆系统及技能工具扩展机制。通过与 OpenClaw 的对比，突出了其在代码量、启动速度和可读性上的优势。最后提供了个人助手、运维员工、监控助手及多模型混合等应用场景案例，以及快速部署指南，适合作为学习 Agent 架构的教材级项目参考。
nanobot 是一个超轻量级 AI Agent（智能体）框架：用约 4000 行 Python 代码，实现了一个能接入多平台聊天软件、支持多 LLM、带记忆和工具系统的'个人 AI 助手'，代码量只有同类项目 Clawdbot / OpenClaw 的 1% 左右。
先看一张整体架构示意图：
外部世界 -> LLM Providers -> Agent Core 核心引擎 -> MessageBus -> Channels 通道层 -> 用户侧
Channel 把平台消息转成统一的内部消息格式，推送到 MessageBus。asyncio.Queue，负责接收所有通道的入站消息，按顺序交给 AgentLoop 处理。AgentLoop：主循环，负责从消息总线取消息、调用 LLM、执行工具、控制最大迭代次数（防止死循环）。ContextBuilder：组装系统提示词，包括身份信息、记忆、技能摘要、历史对话等。MemoryStore：管理长期记忆（MEMORY.md）和每日笔记（memory/YYYY-MM-DD.md）。SkillsLoader：加载'技能'（SKILL.md），让 Agent 动态获得新能力。ToolRegistry：注册文件操作、Shell 执行、Web 搜索等工具。
nanobot 的核心是一个典型的 ReAct（Reasoning + Acting）循环： 用户输入 → 构建上下文 → LLM 推理 → 决定调用工具 / 直接回答 → 执行工具 → 把结果当作新观察 → 再次推理，直到任务完成。
简化版逻辑（概念性伪代码）：
class AgentLoop:
def run(self, user_input: str) -> str:
# 1. 构建上下文：系统提示 + 记忆 + 历史
context = self.context_builder.build(user_input)
# 2. LLM 决策
response = self.llm.complete(context)
# 3. 如果要调用工具
if response.has_tool_call:
result = self.tool_executor.execute(response.tool_call)
# 把工具执行结果当作'观察'，再次进入循环
return self.run(f"Observation: {result}")
else:
# 直接回答用户
return response.content
关键点：
restrictToWorkspace: true，限制只能在工作目录内操作。ContextBuilder 负责把多块信息拼成最终发给 LLM 的 messages：
AGENTS.md、SOUL.md、USER.md、TOOLS.md、IDENTITY.md 等，用户可自定义。MEMORY.md 和最近若干天的日记文件中读取。这样设计的好处是：所有'人格''记忆''技能'都是可读的 Markdown 文件，调试和定制非常直观。
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，后续对话随时引用。
SKILL.md 文件描述一个能力，如天气查询、GitHub 操作、tmux 终端管理等。always: true/false，决定是'始终加载'还是'按需加载'。read_file、write_file、edit_file、list_dir、shell、brave_search、fetch_url、message、spawn、cron 等。ToolRegistry 注册，Agent 根据工具描述和参数 schema 自动调用。nanobot 的代码结构非常清晰，核心目录大致如下：
nanobot/
├── agent/
│ ├── loop.py # Agent 主循环：思考 - 行动 - 观察
│ ├── context.py # Prompt 构建
│ ├── memory.py # 持久记忆
│ ├── skills.py # 技能加载器
│ ├── subagent.py # 后台子代理
│ └── tools/ # 内置工具集
│ ├── filesystem.py
│ ├── shell.py
│ ├── web.py
│ ├── message.py
│ └── ...
├── skills/ # 内置技能（GitHub、天气、tmux 等）
├── channels/ # 各聊天平台适配
├── bus/ # 消息总线
├── providers/ # LLM 提供商封装
├── session/ # 会话管理
├── config/ # 配置加载
└── cli/ # 命令行入口
核心特点：
下面是几个比较典型的应用方向，你可以结合自己公司的场景改写。
场景：你每天在 Telegram / 飞书里跟 nanobot 对话，让它帮你：
MEMORY.md。实现要点：
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-..."
}
}
}
场景：在飞书群里，@nanobot 发送：
查日志 xxx重启服务 yyy查最近 1 小时的异常nanobot 调用后端 API / 日志平台，把结果回填到群里。
实现要点：
SKILL.md 中描述'运维技能'，让 Agent 知道何时调用。在 nanobot 中配置 feishu 通道：
"channels": {
"feishu": {
"enabled": true,
"appId": "...",
"appSecret": "...",
"allowFrom": []
}
}
场景：
实现要点：
cron 工具，定时执行脚本检查监控指标。message 工具，向指定群 / 用户发送告警。使用 nanobot 的 Telegram / Discord 通道：
nanobot telegram # 或 nanobot discord
场景：
实现要点：
providers 中配置多个 LLM 后端。AGENTS.md 中写：
从公开数据对比一下：
| 指标 | OpenClaw（Clawdbot） | nanobot |
|---|---|---|
| 核心代码量 | 430,000+ 行 | ~4,000 行 |
| 启动时间 | 数十秒到分钟级 | < 1 秒 |
| 部署复杂度 | 较高，依赖多 | pip install 即可 |
| 可读性 | 认知负荷大 | 一天可通读核心模块 |
| 浏览器自动化等 | 支持 | 不支持 |
| 平台集成数量 | 50+ 平台 | 8–10 个主流平台 |
nanobot 的取舍是：砍掉 20% 的'高级功能'，换取 99% 的代码减少和更高的可维护性。对于个人开发者、小团队、研究者来说，这是一个非常'舒服'的平衡。
简要步骤（你可以整理成'部署实战'章节）：
nanobot agentnanobot telegramnanobot gateway~/.nanobot/config.json，按官方文档填写 Telegram / 飞书 / Discord 的凭证。初始化配置
nanobot onboard
按提示填写 API Key 和默认模型。
安装（任选其一）
pip install nanobot-ai # 或 uv tool install nanobot-ai # 或从源码
git clone https://github.com/HKUDS/nanobot.git
cd nanobot && pip install -e .
nanobot 并不是要取代所有大型 Agent 框架，而是用 极简架构 + 清晰代码 证明了一件事：
一个功能完整的 AI Agent，不需要几十万行代码，也不需要复杂的'平台化'设计。对于想学习 Agent 原理、搭建个人/团队 AI 助手的开发者来说，nanobot 是一个非常好的'教材级项目'。你可以：通读源码，理解 ReAct 循环、记忆管理、工具调用；在它的基础上，增加你自己的工具和平台适配；把它当作企业内部'虚拟员工'的原型，快速验证想法。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online