30分钟跑通第一个AI Agent:learn-nanobot Nanobot安装配置完整教程与常见问题排错
30分钟跑通第一个AI Agent:learn-nanobot Nanobot安装配置完整教程与常见问题排错
learn-nanobot 是一份面向小白的 Nanobot 学习指南,本教程将带你用约 30 分钟完成 Nanobot 安装与配置,跑通你的第一个 AI Agent。Nanobot 是 HKUDS 开源的超轻量级 AI Agent 框架,核心代码仅约 4000 行,却能提供记忆、工具调用、多平台接入等工业级 Agent 能力,非常适合新手入门 AI Agent 开发。
为什么选 Nanobot 学 AI Agent?
| 特点 | 说明 |
|---|---|
| 🪶 超轻量 | 核心代码约 4000 行,安装后仅约 5MB,一个周末就能读完源码 |
| 🧠 功能完整 | 内置记忆系统、MCP 协议、技能加载、消息总线等核心模块 |
| 🌏 国内友好 | 原生支持飞书、钉钉等 8+ 平台,方便接入 DeepSeek 等国内模型 |
| 🆓 完全免费 | MIT 协议开源,无任何商业限制 |
Nanobot 的核心是四大模块:AgentLoop(核心引擎)、ToolRegistry(工具注册表)、SkillLoader(技能加载器) 和 MEMORY.md(长期记忆),理解了它们,你就理解了绝大多数 AI Agent 框架的通用架构。
配套教程见 docs/02-nanobot-overview/README.md,可深入了解项目背景与设计理念。
30 分钟上手路线图
先看一下整体步骤和时间预算,做到心里有数:
| 步骤 | 内容 | 预计耗时 |
|---|---|---|
| 1️⃣ 环境准备 | 检查 Python 版本、申请 LLM API Key | 5 分钟 |
| 2️⃣ 安装 | pip 或 uv 安装 nanobot-ai |
5 分钟 |
| 3️⃣ 配置向导 | 运行 nanobot onboard 生成配置文件 |
10 分钟 |
| 4️⃣ 定义身份 | 编写 AGENTS.md 告诉 Agent"你是谁" | 5 分钟 |
| 5️⃣ 首次对话 | 启动交互模式并观察运行产物 | 5 分钟 |
第 1 步:环境准备(5 分钟)
系统要求很简单:
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows (WSL) | macOS / Ubuntu 22.04+ |
| Python | 3.10+ | 3.11 或 3.12 |
| 磁盘空间 | 500 MB | 2 GB+ |
先检查 Python 版本:
python3 --version # 输出应为 Python 3.10 或更高
如果版本过低,最简单的方式是用 Conda 创建一个独立环境:
conda create -n nanobot python=3.12 -y
conda activate nanobot
💡 小提示:推荐使用 uv(Rust 编写的 Python 包管理器),安装速度比 pip 快 10-100 倍,也是 Nanobot 官方推荐的方式。
然后准备一个大模型 API Key(Nanobot 通过它驱动 Agent 思考)。任选其一:
- OpenAI(首选)
- DeepSeek(国内友好,推荐新手)
- 本地 Ollama(免费、离线)
export OPENAI_API_KEY="sk-xxxxxxxx" # 或 DEEPSEEK_API_KEY
第 2 步:安装 Nanobot(5 分钟)
有三种安装方式,新手任选其一:
# 方式一:pip 安装(最简单)
pip install nanobot-ai
# 方式二:uv 工具安装(推荐,环境隔离不污染全局)
uv tool install nanobot-ai
# 方式三:源码安装(适合开发者,便于阅读源码)
git clone 项目源码后执行 uv sync --dev
安装完成后验证:
nanobot --version # 输出版本号即成功
nanobot --help # 查看 onboard、run 等子命令
⚠️ 如果提示
nanobot: command not found,说明安装路径不在 PATH 中,可以改用python -m nanobot运行,或重新用 uv 安装。
第 3 步:配置向导 onboard(10 分钟)
Nanobot 提供交互式配置向导,无需手写配置文件:
mkdir my-agent && cd my-agent
nanobot onboard
向导会依次引导你完成 5 步:选择 LLM Provider → 输入 API Key → 选择默认模型 → 配置 Workspace → 生成配置文件。
完成后,你的工作目录会长这样:
my-agent/
├── config.json # 主配置文件
├── AGENTS.md # Agent 身份定义
└── memory/
└── MEMORY.md # 长期记忆文件
读懂 config.json 的 3 个关键参数
config.json 是 Nanobot 最核心的配置文件,参考 projects/01-hello-nanobot/config.json 这份最简示例,新手重点理解 3 个字段即可:
| 字段 | 默认值 | 作用 |
|---|---|---|
model + provider |
gpt-4o + openai | 指定用哪个模型、哪个服务商(两者必须匹配) |
temperature |
0.7 | 生成随机性:0 最稳定,越高越发散 |
max_tool_iterations |
40 | 单次对话允许的最大工具调用轮数,防止死循环 |
💡 排错关键点:
provider和model不匹配(比如 provider 配了 deepseek 却写gpt-4o)会直接报Model not found,这是新手最常见的配置错误之一。
完整的配置详解(providers、channels、tools 全部字段)见 docs/06-install-and-hands-on/README.md 第 6.5 节。
第 4 步:用 AGENTS.md 定义 Agent 身份(5 分钟)
AGENTS.md 决定了你的 Agent "是谁"——它的内容会被注入 System Prompt。参考 projects/01-hello-nanobot/AGENTS.md 这份示例,10 行 Markdown 就够了:
# 代码审查助手
你是一个专业的代码审查助手。
## 职责
- 审查用户提交的代码
- 指出潜在的 bug 和安全问题
- 提供代码改进建议
## 规则
- 使用中文回答
- 给出具体的代码示例
这就是 Nanobot "Markdown 即配置" 的设计哲学:JSON 给机器读,Markdown 给人和 AI 读,改几个字就能改变 Agent 的行为。
第 5 步:第一次对话,观察 Agent 如何工作(5 分钟)
在配置目录下直接启动:
nanobot
进入交互模式后,试着让它做点需要工具的事,比如"帮我创建一个 hello.py 文件"。你一次完整的对话,Agent 内部经历了 4 步循环:
运行后一定要看这几处产物(面试中都是加分细节):
memory/MEMORY.md—— 长期记忆,Agent 把你认为重要的信息"刻"在这里memory/HISTORY.md—— 历史时间线,记录每次会话摘要sessions/—— JSONL 格式的完整会话记录AGENTS.md—— 下次启动时会被重新加载,身份定义生效
可以试试:对话时告诉它"我叫张三,我喜欢用 Python",退出后重启再问"我叫什么",它应该能记住——这就是记忆系统在起作用。原理详解见 docs/07-memory-system/README.md。
常见问题快速排错
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
nanobot: command not found |
安装路径不在 PATH | 用 python -m nanobot 运行,或改用 uv tool install nanobot-ai |
requires Python >= 3.10 |
Python 版本过低 | 用 pyenv/conda 升级到 3.12 后重装 |
Authentication failed |
API Key 抄错或含空格 | 重新复制 Key;确认 provider 与 Key 匹配 |
Model not found |
model 与 provider 不匹配 | 如 deepseek 应配 deepseek-chat,openai 应配 gpt-4o |
| 连接超时(国内常见) | 直连境外 API 不稳定 | 配置 DeepSeek 等国内 Provider,或把 api_base 指向代理地址 |
| 工具调用失败 | 权限或配置缺失 | 检查 restrict_to_workspace 限制、exec 是否被禁用、web_search 是否配了 Key |
| 找不到记忆文件 | workspace 路径配置错误 | 检查 config.json 中 workspace 字段,手动 mkdir -p memory |
🎯 排错心法:90% 的安装问题出在 Python 版本、API Key、model/provider 匹配 这三处,按上表逐项排查基本都能解决。
下一步学什么?
跑通第一个 Agent 只是开始,按这条路径继续即可:
- 记忆系统 —— 理解 MEMORY.md 与记忆压缩机制:docs/07-memory-system/README.md
- 技能与工具 —— 给 Agent 装上手脚:docs/08-skills-and-tools/README.md
- 多平台接入 —— 接入 Telegram / 飞书 / 钉钉:docs/09-multi-platform/README.md
- 安全与部署 —— 把 Agent 放到生产环境:docs/11-security-and-deploy/README.md
还有 4 个递进式的实战项目等你动手:projects/01-hello-nanobot/(Hello Nanobot)、projects/02-custom-skill/(自定义技能)、projects/03-mcp-server/(MCP Server)、projects/04-multi-platform-bot/(多平台 Bot)。完整 17 章学习路线图见 README.md,祝你的第一个 AI Agent 顺利跑起来!🚀


