15 分钟搭建个人 AI Agent：nanobot 实战教程
本文带你从零开始，在本地部署轻量级 AI Agent nanobot。学完后可在 15 分钟内跑通从安装、配置模型到启动 WebUI 的完整流程，让 AI 帮你查日志、搜资料、执行日常任务，实现个人工作流自动化。
你是不是也遇到过这些情况：半夜上线出了 bug，要翻好几台服务器的日志；写代码时频繁切换搜索引擎查资料；重复的运维脚本每次都要手动跑……后端开发者的日常，其实有 30% 的时间花在「信息查找」和「重复操作」上。
只需要一条命令，就能在本地跑一个随叫随到的 AI 助手，它能帮你查文件、搜资料、跑脚本，还能通过 WebUI 像聊天一样交互。今天带你从零搭建 HKUDS/nanobot，一个 4.5 万星的轻量级开源 AI Agent。学完这篇，你可以在本地拥有自己的 AI 自动化入口。
前置条件
开始之前，确认你满足以下条件：
- Python 3.11+（这是 nanobot 的硬性要求）
- 一个可用的 LLM API Key（OpenAI、Moonshot、DeepSeek 等 OpenAI 兼容接口都行，本地部署 Ollama 也可以）
- 基础的终端操作能力（会 cd、会改 JSON 就够）
- 系统：macOS / Linux / Windows 均可
我用的是 Ubuntu 22.04 + Python 3.11，但你换成 Mac 操作几乎一样。
第一步：一键安装
nanobot 提供了一键安装脚本，会自动处理虚拟环境、安装依赖、甚至启动引导向导：
bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh这背后做了什么？脚本会检查你有没有 uv、pipx 或者可用 venv，如果没有，它会在 ~/.nanobot/venv 创建一个隔离环境，然后把 nanobot-ai 包装进去。好处是不污染系统 Python 环境。
Windows 用户用 PowerShell 执行对应脚本：
powershell
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex如果你更习惯手动安装，也可以用 uv 或 pip：
bash
uv tool install nanobot-ai
## 或
python -m pip install nanobot-ai安装完验证一下：
bash
nanobot --version第二步：初始化与配置模型
安装完成后，先跑一下引导命令（如果你的一键安装已经帮你跑过 wizard，这一步可以直接跳过）：
bash
nanobot onboard --wizard这个命令会交互式地引导你完成初始配置，包括选择模型提供商和输入 API Key。执行后，它会在 ~/.nanobot/ 下生成配置文件和工作目录。
如果你想手动配置，打开 ~/.nanobot/config.json，核心要配置两块：providers 和 modelPresets。下面以 OpenAI 兼容接口为例：
json
{
"providers": {
"custom": {
"apiKey": "sk-your-api-key-here",
"apiBase": "https://api.openai.com/v1"
}
},
"modelPresets": {
"primary": {
"label": "Primary",
"provider": "custom",
"model": "gpt-4o-mini",
"maxTokens": 8192,
"contextWindowTokens": 200000,
"temperature": 0.1
}
},
"agents": {
"defaults": {
"modelPreset": "primary"
}
}
}配置结构说明：
providers.custom里放你的 API 密钥和接口地址。如果你用 Moonshot、DeepSeek、SiliconFlow 或者本地 Ollama，改apiBase就行。modelPresets.primary定义了默认用哪个模型。把model换成你提供商支持的模型 ID。agents.defaults.modelPreset把默认模型预设关联到 agent 上。
为什么用 modelPresets 而不是直接写 model？ 因为 nanobot 支持模型切换和 fallback，预设机制让你后续可以通过 /model 命令热切换，不用改配置文件重开。
第三步：启动 WebUI
配置好之后，启动 agent 网关：
bash
nanobot gateway终端会挂着不要关，然后浏览器打开 http://127.0.0.1:8765，就能看到 nanobot 的 WebUI 了。
如果不想一直开着终端，用后台模式：
bash
nanobot gateway --background
## 后续可以用下面这些命令管理
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop实战：让 Agent 帮你查日志
WebUI 启动后，我们来跑一个真实场景。假设你线上服务出了个报错，日志在 ~/logs/app/ 下面，你想让 AI 帮你快速定位问题。
在 WebUI 的聊天框里，你可以直接这样问：
"帮我查看 ~/logs/app/error.log 文件最后 50 行，分析一下最近的报错原因"
nanobot 会调用文件读写工具，读取日志内容，然后让 LLM 分析报错。整个过程你不需要离开浏览器。
在命令行里也能做同样事情：
bash
nanobot agent -m "读取 ~/.nanobot/workspace/ 下的文件列表，告诉我有什么"如果你想要更长期的自动化能力，nanobot 还支持 goals（目标） 和 automations（定时任务）。
进阶：连接 Telegram / 飞书 / 企业微信
nanobot 支持多种聊天渠道。你可以把 agent 挂到 Telegram、Discord、飞书、微信、Slack 或邮件上。这样你走到哪儿，掏出手机就能跟自己的 AI Agent 对话。
配置方式在 config.json 的 chat channel 部分，具体可以参见官方 Chat Apps 文档。以 Telegram 为例，填上 Bot Token 就行。
常见问题与踩坑提醒
Q1：externally-managed-environment 报错怎么办？
这是 pip 在某些系统（尤其 macOS 和 Ubuntu）上的保护机制。解决方案：用 uv tool install 或 pipx install，或者手动创建 venv 再装。
Q2：WebUI 打开后连不上？
确认 nanobot gateway 正在运行，并且你访问的是 http://127.0.0.1:8765（不是 localhost:8765，部分浏览器行为不同）。另外注意 18790 是健康检查端口，别搞混了。
Q3：Provider 显示 not set？
跑 nanobot status 看看状态。如果 active preset 对应的 provider 没配好 apiKey，就会显示 not set。检查 config.json 里的 providers 和 modelPresets 是否匹配。
Q4：想用本地模型？
把 apiBase 改成 Ollama 的地址（默认 http://localhost:11434/v1），model 写你 pull 的模型名，比如 llama3。零额外成本。
总结
回顾一下今天的步骤：
- 一条命令安装
nanobot-ai - 执行
nanobot onboard初始化 - 在
~/.nanobot/config.json配置 API Key 和模型 nanobot gateway启动，浏览器打开 WebUI- 在聊天框里让 Agent 帮你干活
nanobot 的核心设计理念是「小而美」——核心代码可读、可扩展、可自托管。不像一些重型框架，它更像瑞士军刀，给你必要的能力（聊天、工具、记忆、自动化），但不替你做过多的架构决策。
下一步建议：
- 研究一下 MCP（Model Context Protocol）的集成，把更多外部工具接进来
- 试试
automations功能，让 Agent 定时帮你跑日报、监控、数据处理 - 看看 Python SDK 文档，把 nanobot 嵌入自己的后端服务
动手搭一个吧，有问题欢迎评论区交流。