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

学习任何一个开源项目，第一步永远是：把它跑起来，然后看它怎么动。

nanobot 的安装和配置非常简单，但简单背后隐藏着很多 Agent 设计的精妙之处。今天，我们就来拆解它的"启动仪式"。

1. 准备工作：克隆与安装

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

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

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

安装完成后，你会获得一个 nanobot 命令。它主要有三个核心子命令：onboard、agent 和 gateway。

onboard：初始化你的"大脑"

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

1. 初始化配置文件 ：在 ~/.nanobot/config.json 创建配置。如果文件已存在，它会聪明地问你是要覆盖（y）还是保留旧配置并添加新字段（N）。强烈建议选 N，这样你的 API Key 就不会丢。
2. 创建工作空间 ：在 ~/.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 的灵魂。虽然它看起来很长，但逻辑非常清晰。我精简了一下核心部分，你重点看这几个维度：

{
	"agents": {
		"defaults": {
			"workspace": "~/.nanobot/workspace",
			"model": "gemini-3-pro-preview",
			"provider": "auto"
		}
	},
	"providers": {
		"gemini": {
			"apiKey": "YOUR_API_KEY"
		}
	},
	"gateway": {
		"host": "0.0.0.0",
		"port": 18790
	}
}

agents：定义了 Agent 的默认行为，比如去哪里读记忆（workspace），用哪个模型。

providers：配置各种大模型供应商的 API Key。nanobot 支持几乎所有主流供应商。

gateway：定义了网关的监听地址和端口。

4. 技术揭秘：为什么输入 nanobot 就能运行？

在 README 里，我们看到可以直接用 nanobot agent -m "hello"。你有没有想过，系统是怎么知道 nanobot 这个命令对应哪段代码的？

秘密就在项目根目录的 pyproject.toml 文件里：

[project.scripts]
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 的"说明书"：

~/.nanobot/workspace/
├── AGENTS.md # 角色定义
├── SOUL.md # 性格与价值观
├── TOOLS.md # 拥有的工具
├── USER.md # 用户画像
└── memory/ # 长期记忆存储
	├── HISTORY.md
	└── MEMORY.md
└── 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 命令解析。