nanobot 是一个超轻量级、开源、自托管的 Python AI Agent 框架，内置 WebUI、工具链、长期记忆、MCP 集成、多智能体委托、定时自动化，以及 OpenAI 兼容 API。
🐈 nanobot 安装与使用指南
超轻量级 · 开源 · 自托管的 Python AI Agent 框架，内置 WebUI、工具链、长期记忆、MCP 集成、多智能体委托与定时自动化。
一、前置要求
- Python 3.11 或更高版本
- 一个可用的 AI 提供商（API Key + 模型 ID）
- 本地有终端访问权限
Git 和 Bun 仅源码安装时需要；稳定版包已内置 WebUI，无需额外构建。
二、安装（四选一）
方式一：一键脚本（推荐）
macOS / Linux：
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
Windows PowerShell：
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
脚本会自动创建虚拟环境（~/.nanobot/venv），安装最新稳定版，并打印出确切的运行命令。
方式二：uv 安装
uv tool install nanobot-ai
方式三：pip 安装
python -m pip install nanobot-ai
若提示
externally-managed-environment，请使用 uv、pipx 或虚拟环境，勿强行全局安装。方式四：源码安装（开发用）
git clone https://github.com/HKUDS/nanobot.git cd nanobot python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 python -m pip install -e .
三、验证安装
nanobot --version nanobot status
成功的话能看到版本号和配置状态概览。
四、首次启动 WebUI
nanobot webui
首次运行会自动创建配置文件和 workspace，并在浏览器打开 http://127.0.0.1:8765。
首屏三步：
- Settings → Models：选择 Provider，填入 API Key 和 Base URL，选择模型
- 新建话题，发送
Hello!测试连通性 - 确认正常回复后，开始正常使用
默认绑定 localhost，局域网其他设备暂无法访问；如需远程访问请参考部署文档。
五、常用命令速查
| 命令 | 说明 |
|---|---|
nanobot webui |
启动 WebUI（推荐首次使用） |
nanobot agent -m "消息" |
单条消息，直接输出结果 |
nanobot chat |
交互式终端聊天（Enter 发送，Tab 等待响应） |
nanobot gateway --background |
将 Gateway 保活到后台 |
nanobot gateway status |
查看 Gateway 状态 |
nanobot gateway logs |
查看 Gateway 日志 |
nanobot gateway stop |
停止后台 Gateway |
nanobot status |
检查配置和连通性 |
nanobot onboard --refresh |
将旧版 config 升级到最新 schema |
nanobot channels status |
查看所有频道连接状态 |
六、配置文件详解
配置文件路径：~/.nanobot/config.json
最小可用配置（OpenAI 兼容 API）
{
"providers": {
"custom": {
"apiKey": "sk-your-key-here",
"apiBase": "https://api.example.com/v1"
}
},
"modelPresets": {
"primary": {
"provider": "custom",
"model": "your-model-id"
}
},
"agents": {
"defaults": {
"modelPreset": "primary"
}
}
}
敏感信息使用环境变量（推荐）
{
"providers": {
"custom": {
"apiKey": "${PROVIDER_API_KEY}"
}
}
}
启动前确保 PROVIDER_API_KEY 已设置，nanobot 会在内存中解析，值不会写入磁盘。
七、核心功能一览
工具链（Tools）
| 工具 | 说明 |
|---|---|
web |
网页搜索 + 内容抓取 |
exec |
Shell 命令执行（可配合 bwrap 沙箱） |
file |
文件读写操作 |
imageGeneration |
图片生成（支持自定义 Provider） |
mcpServers |
MCP 外部工具集成 |
cron |
定时任务调度 |
subagents |
子智能体并行委托 |
MCP 集成
在 WebUI → Apps 页面或 config.json 中添加：
{
"tools": {
"mcpServers": {
"python-web-mcp": {
"url": "http://localhost:8000/mcp",
"transport": "streamableHttp",
"enabledTools": ["video_create", "video_query"]
}
}
}
}
MCP 配置修改后需重启 Gateway 生效。
多模型预设（Model Preset）
支持多个模型预设，通过 /model <preset> 切换，或在 WebUI ModelPresetBadge 点击切换。
八、接入聊天平台
在 WebUI Settings → Channels 中配置，或直接在 config.json 中启用：
{
"channels": {
"telegram": { "enabled": true, "token": "${TELEGRAM_TOKEN}" },
"discord": { "enabled": true, "token": "${DISCORD_TOKEN}" },
"wechat": { "enabled": true },
"feishu": { "enabled": true }
}
}
各平台详细配置见官方 Chat Apps 文档。
九、安全加固
{
"tools": {
"restrictToWorkspace": true,
"exec": {
"sandbox": "bwrap"
},
"ssrfWhitelist": ["10.0.0.0/8", "172.16.0.0/12"]
}
}
| 配置项 | 作用 |
|---|---|
restrictToWorkspace: true |
工具操作限制在 workspace 目录内 |
exec.sandbox: "bwrap" |
Shell 命令在 bubblewrap 沙箱中运行 |
ssrfWhitelist |
MCP / 工具请求的白名单 CIDR |
十、部署为后台服务
# 启动后台 Gateway nanobot gateway --background # 管理服务 nanobot gateway status nanobot gateway logs nanobot gateway restart nanobot gateway stop
systemd 持久运行示例
# /etc/systemd/system/nanobot.service [Unit] Description=nanobot Gateway After=network.target [Service] User=youruser EnvironmentFile=/home/youruser/nanobot_secrets.env ExecStart=/home/youruser/.nanobot/venv/bin/nanobot gateway Restart=always [Install] WantedBy=multi-user.target
sudo systemctl daemon-reload sudo systemctl enable --now nanobot
十一、故障排查
| 症状 | 排查方向 |
|---|---|
nanobot: command not found |
使用安装命令打印的完整路径，或 uv tool run --from nanobot-ai nanobot |
| JSON parse error | 检查逗号和大括号；文档示例通常为片段，需合并到现有配置 |
| 401 / invalid API key | 确认 Key 属于所选 Provider，去掉首尾空格 |
| Model not found | 确认 Model ID 在该 Provider 下可用 |
| CLI 正常但 WebUI 打不开 | 访问 http://127.0.0.1:8765，不是 Gateway 健康端口 18790 |
| WebUI 正常但频道无响应 | nanobot channels status 检查频道连接状态 |
十二、目录结构
~/.nanobot/ ├── config.json # 主配置文件 ├── workspace/ # 工作区（记忆、技能、自动化） │ ├── SOUL.md # Agent 人格设定 │ ├── USER.md # 用户画像 │ ├── skills/ # 自定义技能 │ └── memory/ # Dream 长期记忆 └── sessions/ # 会话历史（按 session-hash 分目录）
参考
- HKUDS
https://github.com/HKUDS/nanobot - nanobot.wiki
https://nanobot.wiki
ChiuYut
2026年09月04日