【nanobot】 实战与二次开发：4000 行代码，一套完整的 【AI Agent】 框架

🐈 nanobot 实战与二次开发：4000 行代码，一套完整的 AI Agent 框架

🤵‍♂️ 个人主页：小李同学_LSH的主页
✍🏻 作者简介：LLM学习者
🐋 希望大家多多支持，我们一起进步！😄
如果文章对你有帮助的话，
欢迎评论 💬点赞👍🏻 收藏 📂加关注+

写在前面：2026 年初，香港大学数据智能实验室（HKUDS）开源了 nanobot——用约 4000 行代码实现了一套功能完整的个人 AI Agent 框架，是 OpenClaw 代码量的 1%。上线 24 小时 1300+ Star，现已超过23k Star。这篇文章从安装到架构拆解，再到自定义 Skill 和接入 MCP，带你把 nanobot 真正用起来。

📌当前版本：v0.1.5.post2（2026年4月21日发布，Windows + Python 3.14 支持，WebUI 上线）
📌GitHub：github.com/HKUDS/nanobot（MIT 协议）

📖 为什么是 nanobot？

2026 年 AI Agent 框架已经很多了——LangGraph、AutoGen、CrewAI、DeerFlow……它们各有优势，但普遍有一个共同问题：代码量大，依赖重，想改一行逻辑要先搞懂几十个抽象层。

nanobot 的出发点完全不同：

“如果一个 Agent 框架的核心逻辑能被一个开发者完全读懂，那它就是可控的、可改的、可信赖的。”

核心数据对比：

对于想学习 Agent 原理、搭建个人助手、或在企业内部快速部署 AI 工具的开发者，nanobot 是 2026 年最值得掌握的开源项目之一。

🏗️ 第一部分：架构全景

在动手之前，先把 nanobot 的整体架构搞清楚。

nanobot/ ├── agent/ # 🧠 核心：Agent 大脑 │ ├── loop.py # ReAct 主循环（引擎心脏） │ ├── context.py # 上下文组装（Prompt 构建器） │ ├── memory.py # 记忆系统（三层存储） │ ├── skills.py # 技能加载器 │ ├── subagent.py # 子代理（后台长任务） │ └── tools/ # 内置工具（Shell/文件/Web/消息） │ ├── channels/ # 📱 接入层：多平台渠道 │ ├── telegram.py # Telegram Bot │ ├── feishu.py # 飞书机器人 │ ├── discord.py # Discord Bot │ ├── slack.py # Slack Bot │ └── ... # 钉钉/QQ/WhatsApp/Email/微信 │ ├── providers/ # 🤖 模型层：LLM 接入 │ ├── openai.py # OpenAI / DeepSeek / MiniMax 等 │ ├── anthropic.py# Claude 系列 │ └── ... # Gemini / Moonshot / 智谱 / 本地 vLLM │ ├── bus/ # 🚌 消息总线：渠道解耦 ├── cron/ # ⏰ 定时任务 ├── session/ # 💬 会话持久化（JSONL） ├── config/ # ⚙️ Pydantic 配置管理 └── cli/ # 🖥️ 命令行入口

核心数据流：

用户消息（Telegram/飞书/CLI） ↓ Channel → MessageBus（异步队列） ↓ AgentLoop._process_message() ↓ [组装上下文] ContextBuilder（系统提示 + 记忆 + 技能 + 历史） ↓ [LLM 推理] LLM Provider → tool_calls / 直接回答 ↓ [工具执行] Tools（Shell / 文件 / 搜索 / MCP） ↓ [循环直到完成] MessageBus → Channel → 用户

nanobot 的 Agent Loop 是标准的ReAct（Reasoning + Acting）循环：

# 简化版核心逻辑（agent/loop.py）asyncdef_process_message(self,msg:InboundMessage):# 1. 加载会话历史history=awaitself.session.load(msg.session_id)# 2. 组装完整上下文context=self.context_builder.build(user_input=msg.content,memory=awaitself.memory.load(),# 持久化记忆skills=self.skills.get_context(),# 可用技能history=history,# 对话历史)# 3. ReAct 循环for_inrange(self.config.max_iterations):response=awaitself.provider.complete(context)ifresponse.tool_calls:# 执行工具，把结果作为新观察追加到 contextforcallinresponse.tool_calls:result=awaitself.tools.execute(call)context.append_observation(call,result)else:# 任务完成，返回最终答案returnresponse.content

"虚拟工具"技巧：nanobot 用 Function Calling 而不是 Prompt 指令来控制结构化输出，避免 LLM "自作聪明"在 JSON 前后加 Markdown，这是框架里一个值得学习的工程设计。

🚀 第二部分：从零安装到跑通

安装（三选一）

# 方式 1：推荐，用 uv（最快）uv toolinstallnanobot-ai# 方式 2：pippipinstallnanobot-ai# 方式 3：源码开发（二次开发必用）gitclone https://github.com/HKUDS/nanobotcdnanobot pipinstall-e.# 可编辑安装，改代码立即生效

交互式初始化

nanobot onboard

这会启动一个向导，引导你选择 LLM 提供商、填写 API Key、配置渠道。配置文件保存在~/.nanobot/config.json。

最简 config.json

{"agents":{"defaults":{"model":"claude-opus-4-7","max_tokens":8192,"max_iterations":10,"timezone":"Asia/Shanghai"}},"providers":{"anthropic":{"api_key":"sk-ant-你的KEY"}}}

三种使用方式

# 1. 命令行单次对话（最简单）nanobot agent-m"帮我总结今天的 AI 新闻"# 2. 多轮交互 CLInanobot agent# 3. 启动 Gateway（接入 Telegram/飞书等渠道，后台持续运行）nanobot gateway

v0.1.5.post2 新增 WebUI：

nanobot webui# 打开浏览器 http://localhost:7860

⚙️ 第三部分：深入配置

完整 config.json 结构

{"agents":{"defaults":{"model":"claude-opus-4-7","provider":"anthropic","max_tokens":8192,"temperature":0.3,"max_iterations":15,"memory_window":30,"timezone":"Asia/Shanghai","workspace":"/home/user/nanobot-workspace"}},"providers":{"anthropic":{"api_key":"sk-ant-..."},"openai":{"api_key":"sk-..."},"deepseek":{"api_key":"...","base_url":"https://api.deepseek.com/v1"},"openrouter":{"api_key":"sk-or-..."}},"channels":{"telegram":{"token":"你的 Bot Token","allowed_users":["你的用户名"]},"feishu":{"app_id":"...","app_secret":"...","allowed_open_ids":["ou_..."]}},"tools":{"web_search":{"provider":"brave","api_key":"..."},"shell":{"timeout":30,"sandbox":true},"workspace":"/home/user/nanobot-workspace"},"gateway":{"host":"0.0.0.0","port":8765,"heartbeat_interval":300},"dream":{"enabled":true,"interval_hours":2,"batch_size":20}}

Dream：双阶段记忆系统（v0.1.5 核心新功能）

Dream 是 nanobot 最有特色的功能之一——让 Agent 每隔一段时间自动"整理记忆"：

Dream 两阶段执行流程： Phase 1（纯 LLM）： 读取最近 20 条历史记录摘要 LLM 分析并产出整合结果 → 提炼出关键事实、用户偏好、待跟进事项 Phase 2（工具执行）： 启动一个只有 read_file / write_file 权限的子 Agent 把分析结果写入： MEMORY.md → 结构化事实（"用户喜欢简洁回答"） SOUL.md → Agent 个性沉淀 USER.md → 用户画像 完成后自动 git commit

效果：随着使用时间增加，nanobot 会越来越"了解你"——记住你的工作习惯、偏好、正在进行的项目——不需要每次都重新解释背景。

🔧 第四部分：二次开发——写一个自定义 Skill

这是本文最核心的部分。nanobot 的 Skill 系统非常优雅：用文件系统而不是代码注册，把技能的"说明书"（给 LLM 看的）和"实现"（Python 脚本）分开。

Skill 目录结构

workspace/skills/ └── my_skill/ ├── SKILL.md # 技能说明（LLM 读这个来学习如何使用） ├── scripts/ │ └── main.py # 技能实现（Agent 真正执行的代码） └── resources/ # 可选：静态资源文件

实战：开发一个「每日 AI 新闻摘要」Skill

Step 1：创建目录

mkdir-p~/.nanobot/skills/ai_news_digest/scripts

Step 2：写 SKILL.md（这是给 LLM 看的说明书）

# ai_news_digest — 每日 AI 新闻摘要技能 ## 描述 抓取今日 AI 领域最新新闻，生成结构化摘要报告。 ## 何时使用 - 用户询问"今天 AI 有什么新闻" - 用户要求"帮我整理一下今天的 AI 动态" - 定时任务触发的日报生成 ## 使用方法 调用 `ai_news_digest` 技能即可。可选参数： - `topics`: 关注的主题列表（默认：["大模型", "Agent", "开源"]） - `max_items`: 最多返回条数（默认：10） ## 输出格式 返回 Markdown 格式的摘要报告，包含标题、来源、一句话摘要。

Step 3：写实现脚本

# workspace/skills/ai_news_digest/scripts/main.pyimportsysimportjsonimporthttpxfromdatetimeimportdatedeffetch_news(topics:list[str],max_items:int=10)->list[dict]:""" 实际场景中接入真实 API，这里用 Hacker News 演示 生产中可接 NewsAPI、Brave Search、RSS 等 """results=[]# 示例：用 Brave Search API 搜索# （实际使用时从 config 读取 API Key）api_key=sys.argv[1]iflen(sys.argv)>1else""fortopicintopics:try:resp=httpx.get("https://api.search.brave.com/res/v1/news/search",params={"q":f"{topic}AI 2026","count":3,"freshness":"pd"},headers={"X-Subscription-Token":api_key},timeout=10,)ifresp.status_code==200:foriteminresp.json().get("results",[]):results.append({"title":item.get("title",""),"url":item.get("url",""),"snippet":item.get("description",""),"topic":topic,})exceptExceptionase:results.append({"error":str(e),"topic":topic})returnresults[:max_items]defformat_report(news:list[dict],today:str)->str:"""生成 Markdown 格式报告"""lines=[f"# 📰 AI 新闻日报{today}\n"]fori,iteminenumerate(news,1):if"error"initem:lines.append(f"{i}. ⚠️ [{item['topic']}] 获取失败:{item['error']}\n")continuelines.append(f"{i}. **{item['title']}**\n"f" - 话题：{item['topic']}\n"f" - 摘要：{item['snippet'][:100]}...\n"f" - 来源：{item['url']}\n")return"\n".join(lines)if__name__=="__main__":# nanobot 通过 stdin 传入参数（JSON 格式）params={}ifnotsys.stdin.isatty():try:params=json.loads(sys.stdin.read())exceptException:passtopics=params.get("topics",["大模型发布","AI Agent","开源模型"])max_items=params.get("max_items",10)news=fetch_news(topics,max_items)report=format_report(news,str(date.today()))# 输出结果，nanobot 会把这个作为工具返回值传给 LLMprint(report)

Step 4：测试技能

# 手动测试脚本echo'{"topics": ["GPT", "Claude"], "max_items": 5}'|python main.py# 让 nanobot 使用这个技能nanobot agent-m"帮我整理今天的 AI 新闻"# nanobot 会自动识别 ai_news_digest 技能并调用

🔌 第五部分：接入 MCP 工具服务器

nanobot v0.1.4 起原生支持 MCP 协议，配置格式与 Claude Desktop / Cursor 完全兼容。

在 config.json 里配置 MCP

{"tools":{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/user/docs"]},"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_..."}},"memory":{"command":"npx","args":["-y","@modelcontextprotocol/server-memory"]}}}}

配置好后，MCP 服务器提供的工具会自动注册为 nanobot 的原生工具——Agent 调用它们和调用内置的 Shell 工具没有区别。

自定义 MCP Server 接入

如果你已经写了一个 MCP Server（比如连接公司内部数据库），直接按格式配置即可：

{"tools":{"mcpServers":{"company_db":{"command":"python","args":["/path/to/your_mcp_server.py"],"env":{"DB_URL":"postgresql://..."}}}}}

📱 第六部分：接入飞书/Telegram，让 Agent 成为团队机器人

Telegram Bot

{"channels":{"telegram":{"token":"你的 BotFather Token","allowed_users":["your_username"],"allowed_group_ids":[-100123456789]}}}

nanobot gateway# 启动后台网关

之后在 Telegram 里给 Bot 发消息，就直接和 nanobot 对话了。

飞书机器人（适合企业内部部署）

{"channels":{"feishu":{"app_id":"cli_...","app_secret":"...","allowed_open_ids":["ou_..."],"verification_token":"..."}}}

飞书渠道使用 WebSocket 长连接模式（v0.1.4 后稳定），不需要公网 IP，内网环境也能用。

⏰ 第七部分：定时任务——让 Agent 主动工作

# 每天早上 8 点发送 AI 新闻摘要nanobotcronadd"0 8 * * *""帮我整理今天的 AI 新闻，发到 Telegram"# 每 4 小时检查一次 GitHub 新 Issuenanobotcronadd"0 */4 * * *""检查我关注的 GitHub 仓库有没有新 issue"# 查看已有定时任务nanobotcronlist# 删除任务nanobotcronremove<job_id>

也可以在config.json里配置：

{"cron":{"jobs":[{"id":"daily_news","schedule":"0 8 * * *","message":"帮我整理今天的 AI 新闻摘要","channel":"telegram"},{"id":"weekly_review","schedule":"0 20 * * 5","message":"总结本周的工作进展，提醒我周报要写的内容","channel":"feishu"}]}}

🛠️ 第八部分：二次开发进阶——添加自定义 LLM Provider

nanobot v0.1.4.post6 移除了 LiteLLM 依赖，改用原生的 openai + anthropic SDK，新增 Provider只需改两个文件：

# providers/my_provider.pyfromanthropicimportBaseModelfromnanobot.providers.baseimportBaseProvider,CompletionResponseclassMyProvider(BaseProvider):"""接入任何兼容 OpenAI 接口的模型"""def__init__(self,config):fromopenaiimportAsyncOpenAI self.client=AsyncOpenAI(api_key=config.api_key,base_url=config.base_url,# 例如 "https://api.deepseek.com/v1")self.model=config.modelasyncdefcomplete(self,messages:list,tools:list=None,**kwargs)->CompletionResponse:response=awaitself.client.chat.completions.create(model=self.model,messages=messages,tools=toolsor[],**kwargs,)msg=response.choices[0].messagereturnCompletionResponse(content=msg.contentor"",tool_calls=[{"name":tc.function.name,"arguments":tc.function.arguments}fortcin(msg.tool_callsor[])],usage={"total_tokens":response.usage.total_tokens},)

# config/schema.py（添加枚举值）classProviderType(str,Enum):OPENAI="openai"ANTHROPIC="anthropic"DEEPSEEK="deepseek"MY_MODEL="my_model"# 添加这行

然后在config.json里配置：

{"agents":{"defaults":{"provider":"my_model","model":"my-custom-model"}},"providers":{"my_model":{"api_key":"...","base_url":"https://your-api.example.com/v1"}}}

🆚 横评：nanobot 在 Agent 框架里的位置

适合用 nanobot 的场景：个人 AI 助手、小团队内部工具、学习 Agent 原理、快速原型验证。

不适合的场景：复杂多 Agent 协作、需要严格工作流编排、生产级高可靠系统（这些场景用 LangGraph 更合适）。

🎁 总结速查

📣 最后

如果这篇帮你把 nanobot 真正用起来了：

• 👍点赞让更多想做 AI Agent 的同学看到
• ⭐收藏配置和代码随时查阅
• 💬评论参与投票，或者分享你用 nanobot 做了什么
• 🔔关注持续更新 AI Agent 实战，一个正在学 AI 的大学生 👨‍🎓

📚相关阅读：

• 《LangGraph 实战：一个 Coordinator 带着 5 个专家 Agent 干活》
• 《Agent 可观测性：用 LangSmith 追踪每一步》

📖参考资料：

• nanobot GitHub（HKUDS/nanobot，v0.1.5.post2，2026.04.21）
• 知乎：《NanoBot 深度拆解：4000 行代码如何重塑 AI Agent 的极简主义》
• 博客园：《深入剖析 nanobot：轻量级 AI Agent 框架的架构之道》
• 知乎：《nanobot（openclaw轻量化）代码详解》