nanobot 实战与二次开发4000 行代码一套完整的 AI Agent 框架‍♂️ 个人主页小李同学_LSH的主页✍ 作者简介LLM学习者 希望大家多多支持我们一起进步如果文章对你有帮助的话欢迎评论 点赞 收藏 加关注文章目录 nanobot 实战与二次开发4000 行代码一套完整的 AI Agent 框架 为什么是 nanobot️ 第一部分架构全景 第二部分从零安装到跑通安装三选一交互式初始化最简 config.json三种使用方式⚙️ 第三部分深入配置完整 config.json 结构Dream双阶段记忆系统v0.1.5 核心新功能 第四部分二次开发——写一个自定义 SkillSkill 目录结构实战开发一个「每日 AI 新闻摘要」Skill 第五部分接入 MCP 工具服务器在 config.json 里配置 MCP自定义 MCP Server 接入 第六部分接入飞书/Telegram让 Agent 成为团队机器人Telegram Bot飞书机器人适合企业内部部署⏰ 第七部分定时任务——让 Agent 主动工作️ 第八部分二次开发进阶——添加自定义 LLM Provider 横评nanobot 在 Agent 框架里的位置 总结速查 最后写在前面2026 年初香港大学数据智能实验室HKUDS开源了 nanobot——用约 4000 行代码实现了一套功能完整的个人 AI Agent 框架是 OpenClaw 代码量的 1%。上线 24 小时 1300 Star现已超过23k Star。这篇文章从安装到架构拆解再到自定义 Skill 和接入 MCP带你把 nanobot 真正用起来。当前版本v0.1.5.post22026年4月21日发布Windows Python 3.14 支持WebUI 上线GitHubgithub.com/HKUDS/nanobotMIT 协议 为什么是 nanobot2026 年 AI Agent 框架已经很多了——LangGraph、AutoGen、CrewAI、DeerFlow……它们各有优势但普遍有一个共同问题代码量大依赖重想改一行逻辑要先搞懂几十个抽象层。nanobot 的出发点完全不同“如果一个 Agent 框架的核心逻辑能被一个开发者完全读懂那它就是可控的、可改的、可信赖的。”核心数据对比框架代码行数核心安装依赖数启动时间OpenClaw~430,000 行重慢LangGraph~50,000 行中中nanobot~4,000 行极轻秒级对于想学习 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 / 直接回答 ↓ [工具执行] ToolsShell / 文件 / 搜索 / MCP ↓ [循环直到完成] MessageBus → Channel → 用户nanobot 的 Agent Loop 是标准的ReActReasoning Acting循环# 简化版核心逻辑agent/loop.pyasyncdef_process_message(self,msg:InboundMessage):# 1. 加载会话历史historyawaitself.session.load(msg.session_id)# 2. 组装完整上下文contextself.context_builder.build(user_inputmsg.content,memoryawaitself.memory.load(),# 持久化记忆skillsself.skills.get_context(),# 可用技能historyhistory,# 对话历史)# 3. ReAct 循环for_inrange(self.config.max_iterations):responseawaitself.provider.complete(context)ifresponse.tool_calls:# 执行工具把结果作为新观察追加到 contextforcallinresponse.tool_calls:resultawaitself.tools.execute(call)context.append_observation(call,result)else:# 任务完成返回最终答案returnresponse.content虚拟工具技巧nanobot 用 Function Calling 而不是 Prompt 指令来控制结构化输出避免 LLM 自作聪明在 JSON 前后加 Markdown这是框架里一个值得学习的工程设计。 第二部分从零安装到跑通安装三选一# 方式 1推荐用 uv最快uv toolinstallnanobot-ai# 方式 2pippipinstallnanobot-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 gatewayv0.1.5.post2 新增 WebUInanobot 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 新闻摘要」SkillStep 1创建目录mkdir-p~/.nanobot/skills/ai_news_digest/scriptsStep 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:int10)-list[dict]: 实际场景中接入真实 API这里用 Hacker News 演示 生产中可接 NewsAPI、Brave Search、RSS 等 results[]# 示例用 Brave Search API 搜索# 实际使用时从 config 读取 API Keyapi_keysys.argv[1]iflen(sys.argv)1elsefortopicintopics:try:resphttpx.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},timeout10,)ifresp.status_code200: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):iferrorinitem:lines.append(f{i}. ⚠️ [{item[topic]}] 获取失败:{item[error]}\n)continuelines.append(f{i}. **{item[title]}**\nf - 话题{item[topic]}\nf - 摘要{item[snippet][:100]}...\nf - 来源{item[url]}\n)return\n.join(lines)if__name____main__:# nanobot 通过 stdin 传入参数JSON 格式params{}ifnotsys.stdin.isatty():try:paramsjson.loads(sys.stdin.read())exceptException:passtopicsparams.get(topics,[大模型发布,AI Agent,开源模型])max_itemsparams.get(max_items,10)newsfetch_news(topics,max_items)reportformat_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 新闻摘要nanobotcronadd0 8 * * *帮我整理今天的 AI 新闻发到 Telegram# 每 4 小时检查一次 GitHub 新 Issuenanobotcronadd0 */4 * * *检查我关注的 GitHub 仓库有没有新 issue# 查看已有定时任务nanobotcronlist# 删除任务nanobotcronremovejob_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 Providernanobot v0.1.4.post6 移除了 LiteLLM 依赖改用原生的 openai anthropic SDK新增 Provider只需改两个文件# providers/my_provider.pyfromanthropicimportBaseModelfromnanobot.providers.baseimportBaseProvider,CompletionResponseclassMyProvider(BaseProvider):接入任何兼容 OpenAI 接口的模型def__init__(self,config):fromopenaiimportAsyncOpenAI self.clientAsyncOpenAI(api_keyconfig.api_key,base_urlconfig.base_url,# 例如 https://api.deepseek.com/v1)self.modelconfig.modelasyncdefcomplete(self,messages:list,tools:listNone,**kwargs)-CompletionResponse:responseawaitself.client.chat.completions.create(modelself.model,messagesmessages,toolstoolsor[],**kwargs,)msgresponse.choices[0].messagereturnCompletionResponse(contentmsg.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):OPENAIopenaiANTHROPICanthropicDEEPSEEKdeepseekMY_MODELmy_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 框架里的位置维度nanobotLangGraphAutoGenDeerFlow代码量极少4K中50K大大上手难度极低中中中多渠道接入原生支持9种需自定义无无持久记忆Dream 双阶段需自定义基础无MCP 支持原生通过适配无无定时任务原生需自定义无无生产稳定性快速迭代成熟成熟成熟适合学习原理⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐适合用 nanobot 的场景个人 AI 助手、小团队内部工具、学习 Agent 原理、快速原型验证。不适合的场景复杂多 Agent 协作、需要严格工作流编排、生产级高可靠系统这些场景用 LangGraph 更合适。 总结速查场景命令 / 方法安装pip install nanobot-ai初始化nanobot onboard单次对话nanobot agent -m 你的问题启动网关接渠道nanobot gateway启动 WebUInanobot webui添加定时任务nanobot cron add 0 8 * * * 任务描述自定义 Skillworkspace/skills/名字/SKILL.md scripts/main.pyMCP 接入config.json→tools.mcpServers新增 Providerproviders/新建文件 config/schema.py加枚举记忆文件位置~/.nanobot/memory/MEMORY.mdDream 触发nanobot agent --dream或自动默认每 2 小时 最后如果这篇帮你把 nanobot 真正用起来了点赞让更多想做 AI Agent 的同学看到⭐收藏配置和代码随时查阅评论参与投票或者分享你用 nanobot 做了什么关注持续更新 AI Agent 实战一个正在学 AI 的大学生 ‍相关阅读《LangGraph 实战一个 Coordinator 带着 5 个专家 Agent 干活》《Agent 可观测性用 LangSmith 追踪每一步》参考资料nanobot GitHubHKUDS/nanobotv0.1.5.post22026.04.21知乎《NanoBot 深度拆解4000 行代码如何重塑 AI Agent 的极简主义》博客园《深入剖析 nanobot轻量级 AI Agent 框架的架构之道》知乎《nanobotopenclaw轻量化代码详解》