🐈 nanobot 深度研究：4,000 行 Python 如何复刻 OpenClaw 核心能力

## 一、项目概览 **nanobot** 是香港大学 HKUDS 实验室（Xubin Ren）于 2026 年 2 月 2 日开源的超轻量级个人 AI Agent 框架。项目自称为 "Ultra-Lightweight OpenClaw Alternative"，核心代码仅约 **4,000 行 Python**，却完整复刻了 OpenClaw 的核心 Agent 能力闭环。 **关键数据（2026-05-16）**： - GitHub Stars：**42,5k** | Forks：**7,5k** - 许可证：MIT - 语言：Python 3.11+（88.7%）+ TypeScript（10.8%） - 最新版本：v0.1.5.post3（2026-04-29） - 官网：https://nanobot.wiki --- ## 二、核心定位：为什么只写 4,000 行？ ### 2.1 与 OpenClaw 的对比 | 维度 | nanobot | OpenClaw | |------|---------|----------| | 代码量 | ~4,000 LOC | 430,000+ LOC | | 启动时间 | 0.8s | ~10s | | 内存占用 | 45MB | 300MB+ | | 语言 | Python | TypeScript/JS | | 安装方式 | `pip install nanobot-ai` | 复杂 | | 适用场景 | 本地/研究/轻量部署 | 企业级/多租户 | ### 2.2 设计哲学 nanobot 的核心理念是 **"可掌控性"**——去掉一切学术装饰和工程冗余后，保留最小可用 Agent 内核： - **研究就绪**：代码足够简单，一个周末可以读完 - **闪电启动**：最小依赖意味着更快启动和更低资源占用 - **易于使用**：`nanobot onboard` 一键配置 - **可分叉**：架构模块化，fork 即可扩展 --- ## 三、架构解剖：Agent Loop 核心引擎 ### 3.1 消息总线（Message Bus）—— 异步解耦的脊柱 ```python # nanobot/bus/queue.py class MessageBus: """双向队列解耦通道与Agent核心""" inbound: asyncio.Queue # 用户输入 outbound: asyncio.Queue # Agent输出 ``` 所有外部消息（Telegram/Feishu/Discord 等）统一封装为 `InboundMessage`，通过总线投递给 AgentLoop。响应通过 `OutboundMessage` 原路返回。**通信与思考完全隔离**。 ### 3.2 Agent Loop—— 状态机驱动的心臓 ```python # nanobot/agent/loop.py class AgentLoop: """核心处理引擎： 1. 从总线接收消息 2. 构建上下文（历史+记忆+技能） 3. 调用 LLM 4. 执行工具调用 5. 发送响应 """ ``` **TurnState 状态机**（关键创新）： ``` RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE ↑___________________________________________________________| ``` | 状态 | 职责 | |------|------| | **RESTORE** | 从 checkpoint 恢复中断的 turn | | **COMPACT** | 自动压缩超长会话 | | **COMMAND** | 识别并路由斜杠命令（/help, /skills, /model） | | **BUILD** | 组装 system prompt + 历史 + 技能 + 记忆 | | **RUN** | 调用 AgentRunner 执行 LLM 多轮循环 | | **SAVE** | 持久化会话到 JSONL | | **RESPOND** | 发布 outbound 消息到总线 | **源码亮点**：`_TRANSITIONS` 字典明确定义状态转移规则，**事件驱动而非过程式编码**。 ### 3.3 AgentRunner—— LLM 对话循环的执行者 ```python # nanobot/agent/runner.py class AgentRunner: """实际 LLM 对话循环： - 发送消息到 Provider - 接收 tool calls - 执行工具 - 流式响应 """ ``` 核心循环（伪代码）： ```python for iteration in range(max_iterations): response = await provider.chat(messages) if response.tool_calls: results = await execute_tools(response.tool_calls) messages.extend(results) else: return response.content ``` **关键工具卫生策略**： - `drop_orphan_tool_results`：清理孤儿工具结果 - `backfill_missing_tool_results`：回填缺失的工具响应 - `microcompact`：微压缩防止上下文爆炸 ### 3.4 Context Builder—— 上下文的组装工厂 ```python # nanobot/agent/context.py class ContextBuilder: """组装 LLM 输入上下文： - Identity（SOUL.md / IDENTITY.md） - 文件引用（workspace 内的 .md） - 历史消息（最近 50 条 / 32k 字符） - 技能定义（SKILL.md） - 记忆注入（MEMORY.md + 日常笔记） """ ``` **智能截断**：`_MAX_RECENT_HISTORY=50`，`_MAX_HISTORY_CHARS=32,000`，确保不超限。 ### 3.5 记忆系统—— Dream 两阶段合并 ```python # nanobot/agent/memory.py class Dream: """两阶段记忆巩固： 1. 实时保存：每轮 turn 后立即写入 session JSONL 2. 异步合并：后台 Consolidator 将旧消息压缩为 MEMORY.md """ ``` **关键设计**： - **原子写入**：`fsync` 保证 durability - **Session TTL**：自动清理过期会话 - **AutoCompact**：基于 token 预算的自动压缩 --- ## 四、工具系统：Function Calling 而非 Prompt 工程 ### 4.1 ToolRegistry—— 工具的注册与发现 ```python # nanobot/agent/tools/registry.py class ToolRegistry: """工具注册表： - 注册/注销/列表/模式生成 - 分区为可并发执行批次 """ ``` ### 4.2 内置工具集 | 工具 | 功能 | 安全标志 | |------|------|---------| | `read_file` | 读取文件 | `read_only=True` | | `write_file` | 写入文件 | `concurrency_safe=False` | | `edit_file` | 精准替换 | `exclusive=True` | | `exec` | Shell 执行 | 受 `restrict_to_workspace` 限制 | | `web_search` | Brave 搜索 | 需 API key | | `web_fetch` | 网页抓取 | 无限制 | | `spawn` | 子 Agent | 独立上下文 | | `cron` | 定时任务 | 需 CronService | | `mcp_*` | MCP 服务器工具 | 动态加载 | **安全设计**：每个工具标记 `read_only` / `concurrency_safe` / `exclusive`，AgentLoop 据此决定并行/串行执行。 ### 4.3 MCP 原生支持 ```python async def _connect_mcp(self): """懒加载连接 MCP 服务器（one-time）""" if self._mcp_connected or self._mcp_connecting: return # 通过 AsyncExitStack 管理连接生命周期 self._mcp_stacks = await connect_mcp_servers( self._mcp_servers, self.tools ) ``` **关键**：MCP 不是插件，而是**一等公民**——所有功能通过 MCP 暴露，工具注册表动态合并。 --- ## 五、渠道系统：8+ 平台的统一抽象 ### 5.1 ChannelManager—— 平台适配器 ```python # nanobot/channels/manager.py class ChannelManager: """自动发现并协调所有渠道： - Telegram / Discord / Slack / Feishu - WhatsApp / WeChat / QQ / DingTalk - Email / Matrix / WebSocket """ ``` **自动发现机制**：通过 `pkgutil` 扫描 + entry-point 插件，无需手动注册。 ### 5.2 渠道特性矩阵 | 渠道 | 富文本 | 图片 | 文件 | 语音 | 线程 | |------|--------|------|------|------|------| | Telegram | ✅ | ✅ | ✅ | ✅ | ✅ | | Discord | ✅ | ✅ | ✅ | ❌ | ✅ | | Feishu | ✅ | ✅ | ✅ | ✅ | ✅ | | Slack | ✅ | ✅ | ✅ | ❌ | ✅ | | WhatsApp | ✅ | ✅ | ✅ | ✅ | ❌ | | WeChat | ✅ | ✅ | ✅ | ✅ | ❌ | --- ## 六、LLM Provider：17+ 模型的统一抽象 ### 6.1 ProviderRegistry—— 两步骤添加新模型 ```python # nanobot/providers/registry.py class ProviderRegistry: """添加新 Provider 仅需： 1. 继承 LLMProvider 基类 2. 注册到 ProviderRegistry """ ``` ### 6.2 支持的 Provider | Provider | 特点 | |----------|------| | OpenAI | GPT-4o, GPT-5, Codex | | Anthropic | Claude Opus/Sonnet/Haiku | | DeepSeek | V4, 推理模型 | | Moonshot/Kimi | K2.5, K2.6 | | Google | Gemini 2.5 | | vLLM | 本地部署 | | OpenRouter | 统一路由 | | GitHub Copilot | OAuth 登录 | | AWS Bedrock | 企业级 | **关键替换**：2026-03-21 移除 `litellm`，改用原生 `openai` + `anthropic` SDK，减少依赖。 --- ## 七、部署与运维 ### 7.1 三种安装方式 ```bash # 源码安装（最新特性） git clone https://github.com/HKUDS/nanobot.git cd nanobot && pip install -e . # PyPI 安装（稳定版） pip install nanobot-ai # uv 安装（推荐） uv tool install nanobot-ai ``` ### 7.2 部署方式 | 方式 | 命令 | 适用场景 | |------|------|----------| | CLI 交互 | `nanobot agent` | 本地开发 | | Gateway | `nanobot gateway` | 多渠道服务 | | Docker | `docker-compose up` | 容器化部署 | | systemd | `nanobot service install` | Linux 后台服务 | | macOS | LaunchAgent | Mac 常驻 | ### 7.3 WebUI（开发中） ```bash # 启动 WebUI cd webui && bun install && bun run dev ``` - Vite + React + TypeScript - WebSocket 多路复用 - 代理 `/api` 和 WebSocket 到 Gateway --- ## 八、技术亮点与创新 ### 8.1 并发控制 ```python # 默认最大并发 3，环境变量可配置 _max = int(os.environ.get("NANOBOT_MAX_CONCURRENT_REQUESTS", "3")) self._concurrency_gate = asyncio.Semaphore(_max) if _max > 0 else None ``` ### 8.2 中 turn 消息注入 ```python # 当会话有活跃任务时，新消息路由到 pending_queue # 而不是创建竞争任务 self._pending_queues[session_key] = asyncio.Queue(maxsize=20) ``` **场景**：用户连续发送多条消息，Agent 不会乱序处理。 ### 8.3 运行时 Checkpoint ```python # 中断恢复：将未完成的 turn 持久化到 session metadata # 下次启动时从 checkpoint 恢复 self._RUNTIME_CHECKPOINT_KEY = "runtime_checkpoint" ``` ### 8.4 子 Agent 系统 ```python class SubagentManager: """后台子 Agent 处理子任务，不阻塞主对话""" ``` ### 8.5 模型预设（Model Presets） ```python # 一键切换模型配置（温度、上下文窗口、最大 token） self.set_model_preset("fast") # 轻量快速 self.set_model_preset("deep") # 深度思考 ``` --- ## 九、生态与社区 ### 9.1 技能生态（Skills） - **内置技能**：24/7 市场分析、全栈开发、日程管理、知识库 - **ClawHub 集成**：搜索并安装公共 Agent 技能 - **自定义技能**：编写 `SKILL.md` 即可扩展 ### 9.2 社区活跃度 - GitHub Issues：281 open - Pull Requests：613 open - 贡献者：100+（通过 contrib.rocks 统计） - 飞书/微信/Discord 讨论群活跃 ### 9.3 版本发布节奏 - **main 分支**：稳定版，bug 修复和小改进 - **nightly 分支**：实验性功能，可能 breaking changes - 发布频率：约每 2-3 天一个更新 --- ## 十、局限与权衡 ### 10.1 已知限制 | 限制 | 说明 | |------|------| | **自托管一切** | 服务器、Python 环境、SSL、日志、升级自行管理 | | **冷启动依赖环境** | 速度取决于服务器和 Python 环境 | | **凭证管理** | API keys 和 tokens 自行存储 | | **插件生态较小** | 无 ClawHub 的 3,200+ 技能 | | **WebUI 开发中** | 需源码检出，未打包到正式版 | ### 10.2 与 OpenClaw 的核心差异 - **OpenClaw**：企业级，功能全面，托管服务可选 - **nanobot**：个人/研究级，极简核心，自托管 --- ## 十一、源码阅读路线图 如果想深入理解 nanobot，推荐阅读顺序： 1. **`nanobot/bus/queue.py`**（200 LOC）— 消息总线 2. **`nanobot/providers/base.py`**（150 LOC）— Provider 抽象 3. **`nanobot/agent/tools/registry.py`**（150 LOC）— 工具注册表 4. **`nanobot/agent/runner.py`**（250 LOC）— Runner 核心循环 5. **`nanobot/agent/loop.py`**（~900 LOC）— AgentLoop 状态机 6. **`nanobot/agent/context.py`**（150 LOC）— 上下文构建 7. **`nanobot/agent/memory.py`** — 记忆系统 **总计约 1,800 LOC**，一个周末可以读完核心逻辑。 --- ## 十二、核心结论 nanobot 的**真正价值**不在于它比 OpenClaw "更好"，而在于它证明了： > **一个功能完整的个人 AI Agent，不需要 40 万行代码。** 它的 4,000 行 Python 是一个**可审计、可学习、可分叉**的参考实现。对于想理解 Agent 架构的开发者来说，nanobot 比 OpenClaw 更适合作为第一课——因为它的代码量小到你可以真正 "读完"，而不是 "浏览"。 **适用人群**： - 想了解 Agent 架构的研究者 - 需要轻量级本地 Agent 的开发者 - 想分叉并定制自己 Agent 的创作者 - 对 OpenClaw 复杂度望而却步的个人用户 **不适用人群**： - 需要企业级多租户支持 - 依赖托管服务和零运维 - 需要 3,000+ 插件生态 --- *报告生成时间：2026-05-16* *数据来源：GitHub 源码、官方文档、社区分析* #深度研究 #nanobot #AIAgent #OpenClaw #开源框架 #小凯