type
Post
status
Published
date
Mar 9, 2026
slug
nanobot-source-code-analysis-1
summary
想要深入理解 AI Agent？先从跑通 nanobot 开始。本文带你完成环境搭建，拆解核心命令，并揭秘命令注册背后的技术细节。
tags
nanobot
agent
category
技术分享
icon
password
学习任何一个开源项目，第一步永远是：把它跑起来，然后看它怎么动。
nanobot 的安装和配置非常简单，但简单背后隐藏着很多 Agent 设计的精妙之处。今天，我们就来拆解它的“启动仪式”。
1. 准备工作：克隆与安装
首先，把代码拉到本地。nanobot 是纯 Python 写的，对环境非常友好。
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 的灵魂。虽然它看起来很长，但逻辑非常清晰。我精简了一下核心部分，你重点看这几个维度：agents：定义了 Agent 的默认行为，比如去哪里读记忆（workspace），用哪个模型。providers：配置各种大模型供应商的 API Key。nanobot 支持几乎所有主流供应商。gateway：定义了网关的监听地址和端口。4. 技术揭秘：为什么输入 nanobot 就能运行？
在 README 里，我们看到可以直接用
nanobot agent -m "hello"。你有没有想过，系统是怎么知道 nanobot 这个命令对应哪段代码的？秘密就在项目根目录的
pyproject.toml 文件里：注册命令：这段配置告诉 Python 安装工具，在安装项目时，在系统的 PATH 中创建一个名为
nanobot 的可执行脚本。指定入口：当你输入
nanobot 时，它实际上调用的是 nanobot/cli/commands.py 文件中的 app 对象。Debug 小贴士：如果你想调试 nanobot 的启动逻辑，直接定位到
nanobot/cli/commands.py，从 app 对象开始追踪即可。5. 看看你的 Agent 长什么样
完成
onboard 后，你的工作空间（~/.nanobot/workspace）会生成一系列 Markdown 文件。这些文件就是 Agent 的“说明书”：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 的 agent 命令。