nanobot 核心分析报告

📋 项目概述

nanobot 是香港大学数据科学实验室 (HKUDS) 开发的超轻量级个人 AI 助手框架，灵感来自 OpenClaw/Clawdbot。

核心卖点：用约 4,000 行 Python 代码实现了 Clawdbot 430K+ 行代码的核心功能 —— 99% 的体积缩减，保留了完整的 Agent 循环能力。

            解决的问题：Clawdbot 功能强大但代码量庞大，不利于研究者理解、修改和实验。
            nanobot 提供了一个可读、可改、可研究的精简替代方案 —— 一个「教科书级的 Agent 框架实现」。
        

~4K

行 Python 代码

99%

体积缩减（vs Clawdbot）

内置工具

LLM 提供者

🏗️ 核心架构

nanobot/ ├── agent/ # 核心：Agent 循环 + 上下文 + 记忆 + 工具 │ ├── loop.py # Agent Loop（LLM ↔ 工具执行的主循环） │ ├── context.py # System Prompt 构建器 │ ├── memory.py # 持久化记忆（日记 + 长期记忆） │ ├── skills.py # 技能加载器 │ ├── subagent.py # 子 Agent 后台任务 │ └── tools/ # 内置工具集 ├── providers/ # LLM 提供者抽象层（LiteLLM） ├── bus/ # 消息总线（事件路由） ├── channels/ # 通信渠道（Telegram / WhatsApp） ├── session/ # 会话管理 ├── cron/ # 定时任务 ├── heartbeat/ # 心跳唤醒 └── cli/ # CLI 入口

核心执行流程（ReAct 模式）

1
消息总线
接收消息

→

2
ContextBuilder
组装 System Prompt

→

3
LLM 调用
推理生成

→

4
工具执行
解析 tool_calls

→

5
循环判断
最多 20 轮

→

6
最终响应
返回结果

✨ 关键特性

🔌 多 LLM 支持

通过 LiteLLM 统一抽象层，支持 OpenRouter / Anthropic / OpenAI / Groq / Gemini，也支持本地 vLLM 部署。切换模型零成本。

🛠️ 内置工具集

文件读写编辑、Shell 命令执行、Web 搜索与内容抓取、消息发送、子 Agent 生成 —— 覆盖 Agent 核心操作。

📡 通信渠道

Telegram（推荐，原生 Python 实现）+ WhatsApp（通过 Node.js bridge）。

🧠 记忆系统

日记文件（YYYY-MM-DD.md）+ 长期记忆（MEMORY.md），自动注入上下文。沿用 Clawdbot 的 AGENTS.md / SOUL.md 约定。

📦 技能系统

模块化技能目录，支持 always-on 全量注入和按需懒加载，有效节省 Token 消耗。

🔄 子 Agent & 定时任务

SpawnTool 支持后台任务分发，内置 cron 定时执行和心跳唤醒机制。

💡 创新点

极致精简 — ~4000 行代码实现完整 Agent 框架，每个模块职责清晰
Clawdbot 兼容设计 — 沿用 AGENTS.md/SOUL.md/MEMORY.md 等约定，迁移成本低
渐进式技能加载 — always-on 技能全量注入，其他技能只展示摘要，按需加载，节省 Token

⚙️ 技术栈

语言Python ≥ 3.11

LLM 调用LiteLLM

数据模型Pydantic v2

CLI 框架Typer

HTTP 客户端httpx

日志loguru

网页提取readability-lxml

终端 UIRich

定时调度croniter

Telegrampython-telegram-bot

WhatsAppNode.js Bridge

构建工具Hatchling

代码格式化Ruff

📊 同类项目对比

维度	nanobot	Clawdbot (OpenClaw)	AutoGPT	Claude Code
代码量	~4K 行	~430K 行	~100K+ 行	闭源
定位	研究 / 学习 / 轻量部署	生产级全功能	通用自主 Agent	官方 CLI
内置工具	~8 个	数十个	数十个	数十个
通信渠道	Telegram / WhatsApp	多渠道	Web UI	终端
本地模型	✅	✅	✅	❌
可读性	★★★★★	★★★★★	★★★★★	N/A
生产就绪	❌ Alpha	✅	部分	✅

⚖️ 优缺点评估

✅ 优点

代码极简可读 — 非常适合学习 Agent 架构，每个模块职责清晰
开箱即用 — pip install + 配一个 API key 即可运行
灵活 LLM 支持 — LiteLLM 统一层，切换模型零成本
沿用成熟约定 — AGENTS.md 等文件约定久经验证
MIT 开源 — 无商业限制

❌ 缺点

功能有限 — 无浏览器控制、多模态处理、高级推理
记忆系统原始 — 纯文件读写，无向量检索或语义搜索
无安全模型 — 工具执行无沙箱、无审批流程
会话管理简单 — 无多轮上下文窗口管理、无 Token 裁剪
Alpha 阶段 — API 可能频繁变动，缺少测试覆盖
WhatsApp 依赖 Node.js — 增加部署复杂度

🎯 适用场景

场景	推荐度	说明
学习 AI Agent 架构原理	★★★★★	最佳用途 — 代码可读性极高，适合教学
研究实验（改造/对照）	★★★★★	精简基座，方便快速修改和实验
个人轻量 AI 助手	★★★★★	日常轻度使用足够
快速原型验证	★★★★★	快速搭建 Agent 原型的理想起点
生产环境部署	★★★★★	Alpha 阶段，缺少安全和稳定性保障
企业级应用	★★★★★	不建议 — 功能和安全模型不足

📝 总结

nanobot 的核心价值是「教科书级的 Agent 框架实现」。它不是要替代 Clawdbot，而是为研究者和学习者提供一个可以快速理解、修改、实验的精简基座。

如果你想搞清楚一个 AI Agent 到底是怎么工作的，读 nanobot 的 4,000 行代码比读 Clawdbot 的 430,000 行高效得多。对于 HKUDS 这样的学术团队来说，这是一个非常聪明的定位 —— 不做大而全，做小而精。

仓库地址：github.com/HKUDS/nanobot

🤖 nanobot