opencalw平替之nanobot 源码解析（一）：环境搭建、Debug 配置与 onboard 命令详解

学习任何一个开源项目，第一步永远是：把它跑起来，然后看它怎么动。
nanobot 的安装和配置非常简单，但简单背后隐藏着很多 Agent 设计的精妙之处。今天，我们就来拆解它的“启动仪式”。
1. 准备工作：克隆与安装

首先，把代码拉到本地。nanobot 是纯 Python 写的，对环境非常友好。

1. git clone https://github.com/HKUDS/nanobot.git
2. cd nanobot
3. pip install -e .

复制代码

2. 核心命令：Agent 的三板斧

安装完成后，你会获得一个 nanobot 命令。它主要有三个核心子命令：onboard、agent 和 gateway。
onboard：初始化你的“大脑”

运行 nanobot onboard，这是你和 nanobot 的第一次亲密接触。它的核心功能有两个：

• 初始化配置文件：在 ~/.nanobot/config.json 创建配置。如果文件已存在，它会聪明地问你是要覆盖（y）还是保留旧配置并添加新字段（N）。强烈建议选 N，这样你的 API Key 就不会丢。
  
• 创建工作空间：在 ~/.nanobot/workspace 准备好 Agent 的“家”，包括 AGENTS.md（定义角色）、SOUL.md（定义性格）等模板文件。这些文件来自 nanobot/templates 目录。同时还会创建该目录下没有的 skills 文件夹和 HISTORY.md 文件。
  

agent：直接对话

这是最简单的交互方式。运行 nanobot agent -m "xxx"，你就可以直接在终端和你的 AI Agent 聊天了。它会加载你的配置和工作空间，进入一个交互式的 loop。
gateway：开启多端连接

如果你想让你的 Agent 登录 Telegram、飞书或者 Discord，那就需要运行 nanobot gateway。它像一个中转站，把各种聊天平台的信号接入到 nanobot 的核心逻辑中。
3. 深度拆解：配置文件里藏了什么？

~/.nanobot/config.json 是 nanobot 的灵魂。虽然它看起来很长，但逻辑非常清晰。我精简了一下核心部分，你重点看这几个维度：

1. {
2.         "agents": {
3.                 "defaults": {
4.                         "workspace": "~/.nanobot/workspace",
5.                         "model": "gemini-3-pro-preview",
6.                         "provider": "auto"
7.                 }
8.         },
9.         "providers": {
10.                 "gemini": {
11.                         "apiKey": "YOUR_API_KEY"
12.                 }
13.         },
14.         "gateway": {
15.                 "host": "0.0.0.0",
16.                 "port": 18790
17.         }
18. }

复制代码

agents：定义了 Agent 的默认行为，比如去哪里读记忆（workspace），用哪个模型。
providers：配置各种大模型供应商的 API Key。nanobot 支持几乎所有主流供应商。
gateway：定义了网关的监听地址和端口。
4. 技术揭秘：为什么输入 nanobot 就能运行？

在 README 里，我们看到可以直接用 nanobot agent -m "hello"。你有没有想过，系统是怎么知道 nanobot 这个命令对应哪段代码的？
秘密就在项目根目录的 pyproject.toml 文件里：

1. [project.scripts]
2. nanobot = "nanobot.cli.commands:app"

复制代码

注册命令：这段配置告诉 Python 安装工具，在安装项目时，在系统的 PATH 中创建一个名为 nanobot 的可执行脚本。
指定入口：当你输入 nanobot 时，它实际上调用的是 nanobot/cli/commands.py 文件中的 app 对象。
Debug 小贴士：如果你想调试 nanobot 的启动逻辑，直接定位到 nanobot/cli/commands.py，从 app 对象开始追踪即可。
5. 看看你的 Agent 长什么样

完成 onboard 后，你的工作空间（~/.nanobot/workspace）会生成一系列 Markdown 文件。这些文件就是 Agent 的“说明书”：

1. ~/.nanobot/workspace/
2. ├── AGENTS.md # 角色定义
3. ├── SOUL.md # 性格与价值观
4. ├── TOOLS.md # 拥有的工具
5. ├── USER.md # 用户画像
6. └── memory/ # 长期记忆存储
7.         ├── HISTORY.md
8.         └── MEMORY.md
9. └── skills/ # 技能存储

复制代码

nanobot 的精妙之处在于：它把 Agent 的逻辑和数据完全解耦了。你只需要修改这些 Markdown 文件，就能改变 Agent 的行为，而不需要动一行 Python 代码。
现在，你的 nanobot 应该已经跑起来了。
Debug 小贴士：
既然 nanobot 是一个 CLI 工具，最专业的调试方式就是在 IDE（如 PyCharm 或 VS Code）中创建针对不同子命令的 Debug 配置。由于 nanobot 使用了 typer 库，所有的命令入口最终都会汇聚到 nanobot/cli/commands.py。

• 入口文件：脚本路径指向 nanobot/cli/commands.py。
  
• 命名规范：建议采用 nanobot: [command] 的格式，例如 nanobot: onboard、nanobot: agent 或 nanobot: gateway。
  
• 参数配置：在 Parameters/Args 中填入对应的子命令和参数（如 agent -m "hello"）。
  

这样你的 Debug 列表会非常整洁，一眼就能看出当前在调试哪个功能，这才是专业开发者的姿态。
如果你也想 debug nanobot 项目的话，请参考我的配置。

图：nanobot: onboard 配置示例

图：nanobot: agent 配置示例

图：nanobot: gateway 配置示例
下一篇，我们将深入解析 nanobot 的 agent 命令解析。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！