一、nanobot 是什么？一句话概括

nanobot 是一个超轻量级 AI Agent（智能体）框架：
用约 4000 行 Python 代码，实现了一个能接入多平台聊天软件、支持多 LLM、带记忆和工具系统的“个人 AI 助手”，代码量只有同类项目 Clawdbot / OpenClaw 的 1% 左右。

二、整体架构：从聊天窗口到 LLM 的“神经中枢”

先看一张整体架构示意图：

2.1 分层职责（从下往上理解）

1. Channels 通道层
   • 封装了各聊天平台的差异：Telegram、飞书、Discord、WhatsApp 等。
   • 每个 Channel 把平台消息转成统一的内部消息格式，推送到 MessageBus。
   • 出站时，把统一消息格式再转回各平台的 API 调用。
2. MessageBus（消息总线）
   • 一个 asyncio.Queue，负责接收所有通道的入站消息，按顺序交给 AgentLoop 处理。
   • 解耦“平台接入”和“Agent 决策逻辑”。
3. Agent Core（核心引擎）
   • AgentLoop：主循环，负责从消息总线取消息、调用 LLM、执行工具、控制最大迭代次数（防止死循环）。
   • ContextBuilder：组装系统提示词，包括身份信息、记忆、技能摘要、历史对话等。
   • MemoryStore：管理长期记忆（MEMORY.md）和每日笔记（memory/YYYY-MM-DD.md）。
   • SkillsLoader：加载“技能”（SKILL.md），让 Agent 动态获得新能力。
   • ToolRegistry：注册文件操作、Shell 执行、Web 搜索等工具。
4. LLM Providers
   • 通过 LiteLLM 统一封装 OpenRouter、Anthropic、OpenAI、DeepSeek、Gemini、vLLM 等多种后端。
   • 配置好 API Key / apiBase，Agent 就能透明切换模型。
5. 外部世界
   • 文件系统、Shell 命令、Web 搜索、定时任务等，通过工具系统与 Agent 交互。

---

三、核心原理：ReAct 循环 + 极简工程实现

3.1 Agent Loop：思考—行动—观察的闭环

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

关键点：

• 最大迭代次数：默认上限约 20 轮，防止工具调用死循环。
• 工具执行沙箱：生产环境建议配置 restrictToWorkspace: true，限制只能在工作目录内操作。

3.2 ContextBuilder：系统提示词是如何“拼出来”的

ContextBuilder 负责把多块信息拼成最终发给 LLM 的 messages：

1. 核心身份：当前时间、运行环境、工作目录等。
2. Bootstrap 文件：AGENTS.md、SOUL.md、USER.md、TOOLS.md、IDENTITY.md 等，用户可自定义。
3. 记忆上下文：从 MEMORY.md 和最近若干天的日记文件中读取。
4. 技能摘要：列出可用技能及其描述。
5. 历史对话：当前会话的聊天历史。
6. 当前用户消息：支持多模态（如图片）。
   这样设计的好处是：
   所有“人格”“记忆”“技能”都是可读的 Markdown 文件，调试和定制非常直观。

3.3 Memory：两层记忆系统

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，后续对话随时引用。

3.4 Skills & Tools：用 Markdown + Python 插件扩展能力

1. 技能（Skills）
   • 每个 SKILL.md 文件描述一个能力，如天气查询、GitHub 操作、tmux 终端管理等。
   • 头部 YAML 配置 always: true/false，决定是“始终加载”还是“按需加载”。
2. 工具（Tools）
   • 内置工具包括：read_file、write_file、edit_file、list_dir、shell、brave_search、fetch_url、message、spawn、cron 等。
   • 每个工具都是一个 Python 类，通过 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/                 # 命令行入口

核心特点：

• 约 4000 行核心代码，对比 OpenClaw 的 43 万行，体量小两个数量级。
• 单文件可理解：每个核心模块基本可以在一屏内看完。
• 显式优于隐式：没有“魔法基类”和复杂的元编程，适合学习 Agent 架构。

---

五、应用案例：从“个人助手”到“团队虚拟员工”

下面是几个比较典型的应用方向，你可以结合自己公司的场景改写。

案例 1：个人知识助手 + 日程管理

场景：你每天在 Telegram / 飞书里跟 nanobot 对话，让它帮你：

• 整理会议纪要、项目文档。
• 记录“项目背景”“关键决策”到 MEMORY.md。
• 设置定时提醒：每天早上 9 点自动推送“今日待办”。
  实现要点：

1. 在 ~/.nanobot/config.json 中配置一个默认 Agent 和 LLM 提供商：

   {
     "agents": {
       "defaults": {
         "model": "anthropic/claude-sonnet-4-20250514",
         "maxTokens": 8192,
         "temperature": 0.7
       }
     },
     "providers": {
       "openrouter": { "apiKey": "sk-or-v1-..." }
     }
   }
   

2. 在工作目录写 AGENTS.md / USER.md，定义你的“人格”：

   • 你是某产品的负责人；
   • 你关心哪些指标；
   • 你希望如何被称呼等。

3. 使用内置工具：

   • write_file/edit_file：自动更新项目文档。
   • cron 工具：添加定时任务，例如每天早上提醒你查看某个看板。

案例 2：飞书群里的“虚拟运维员工”

场景：在飞书群里，@nanobot 发送：

• 查日志 xxx
• 重启服务 yyy
• 查最近 1 小时的异常
  nanobot 调用后端 API / 日志平台，把结果回填到群里。
  实现要点：

1. 在飞书开放平台创建企业自建应用，获取 App ID / App Secret，开通机器人能力和相应权限。

2. 在 nanobot 中配置 feishu 通道：

   "channels": {
     "feishu": {
       "enabled": true,
       "appId": "...",
       "appSecret": "...",
       "allowFrom": []
     }
   }
   

3. 编写自定义工具或技能：

   • 封装公司内部的日志查询 / 发布部署接口。
   • 在 SKILL.md 中描述“运维技能”，让 Agent 知道何时调用。

4. 在飞书群里 @机器人，即可触发运维操作，无需额外开发 UI。

案例 3：Telegram / Discord 的 7×24 小时监控助手

场景：

• 服务器有监控告警（Prometheus / 自定义脚本）；
• 你希望异常发生时，nanobot 能自动在 Telegram / Discord 里发消息，甚至尝试自愈。
  实现要点：

1. 使用 nanobot 的 Telegram / Discord 通道：

   nanobot telegram   # 或 nanobot discord
   

2. 配置 cron 工具，定时执行脚本检查监控指标。

3. 当脚本发现异常时，调用 nanobot 的 message 工具，向指定群 / 用户发送告警。

4. 可进一步让 nanobot 执行“自愈脚本”（如重启服务、清理磁盘），实现自动修复。

案例 4：多模型“混合大脑”助手

场景：

• 常规对话用便宜模型；
• 复杂推理 / 代码任务用更强的模型。
  实现要点：

1. 在 providers 中配置多个 LLM 后端。
2. 在 AGENTS.md 中写：
   • 对于简单聊天，使用模型 A；
   • 对于代码、数据分析，调用模型 B。
3. 通过工具 / 技能封装“切换模型”的能力，让 Agent 根据任务类型自动选择模型。

---

六、与 OpenClaw / Clawdbot 的对比：极简主义的代价

从公开数据对比一下：

指标	OpenClaw（Clawdbot）	nanobot
核心代码量	430,000+ 行	~4,000 行
启动时间	数十秒到分钟级	< 1 秒
部署复杂度	较高，依赖多	pip install 即可
可读性	认知负荷大	一天可通读核心模块
浏览器自动化等	支持	不支持
平台集成数量	50+ 平台	8–10 个主流平台
nanobot 的取舍是：砍掉 20% 的“高级功能”，换取 99% 的代码减少和更高的可维护性。
对于个人开发者、小团队、研究者来说，这是一个非常“舒服”的平衡。

---

七、如何在一台服务器上快速部署 nanobot？

简要步骤（你可以整理成“部署实战”章节）：

1. 安装（任选其一）

   pip install nanobot-ai
   # 或
   uv tool install nanobot-ai
   # 或从源码
   git clone https://github.com/HKUDS/nanobot.git
   cd nanobot && pip install -e .
   

2. 初始化配置

   nanobot onboard
   

   按提示填写 API Key 和默认模型。

3. 启动

   • 命令行对话：nanobot agent
   • 启动 Telegram Bot：nanobot telegram
   • 启动飞书等通道：nanobot gateway

4. 配置通道
   编辑 ~/.nanobot/config.json，按官方文档填写 Telegram / 飞书 / Discord 的凭证。

---

八、小结：nanobot 的意义

nanobot 并不是要取代所有大型 Agent 框架，而是用 极简架构 + 清晰代码 证明了一件事：

一个功能完整的 AI Agent，不需要几十万行代码，也不需要复杂的“平台化”设计。
对于想学习 Agent 原理、搭建个人/团队 AI 助手的开发者来说，nanobot 是一个非常好的“教材级项目”。你可以：

• 通读源码，理解 ReAct 循环、记忆管理、工具调用；
• 在它的基础上，增加你自己的工具和平台适配；
• 把它当作企业内部“虚拟员工”的原型，快速验证想法。