nanobot 本地部署教程：WebUI、模型配置、MCP 与聊天应用接入

nanobot 是一个轻量、自托管的个人 AI Agent 运行时，提供终端、WebUI、工具、长期记忆、MCP、定时自动化和多种聊天应用入口。它适合希望掌握数据和运行环境，又不想先搭建大型 Agent 平台的用户。

快速安装

nanobot 要求 Python 3.11 以上。稳定使用优先从 PyPI 或 uv 安装：

1

uv tool install nanobot-ai

也可以使用 pip：

1

python -m pip install nanobot-ai

安装后检查版本并启动引导：

1
2


nanobot --version
nanobot onboard --wizard

引导程序会创建 ~/.nanobot/config.json 和 ~/.nanobot/workspace/。

配置 OpenAI 兼容模型

nanobot 支持自定义 OpenAI 兼容 Provider。配置至少包括 API Key、API Base、模型 ID 和上下文长度。推荐使用命名的 modelPresets，便于切换主模型和备用模型。

不要把完整配置公开提交，因为 providers.<provider>.apiKey 可能包含真实密钥。先用一个低权限测试 Key 完成首次连接，再增加搜索、MCP 和聊天渠道。

启动 WebUI

稳定版本可启动 Gateway：

1

nanobot gateway

然后访问：

1

http://127.0.0.1:8765

较新的源码版本也提供：

1

nanobot webui

默认 WebUI 绑定 127.0.0.1，不会直接暴露给局域网。不要为了手机访问而简单改成 0.0.0.0；应先配置访问令牌、反向代理和防火墙。

验证 Agent 是否正常

1
2


nanobot status
nanobot agent -m "Hello!"

status 中多数未使用的 Provider 显示 not set 是正常的。重点确认当前激活模型、Config 和 Workspace 状态。

MCP、记忆和聊天应用怎么逐步开启

推荐顺序：

先跑通终端单次消息；
再打开本地 WebUI；
配置长期记忆并观察保存内容；
只添加一个经过审查的 MCP Server；
最后连接 Telegram、Discord、Slack、微信或邮件。

聊天应用会扩大输入来源，也可能触发 Shell、文件、网络和定时任务。为每个渠道配置允许用户、命令范围和工作目录，不要把公网机器人直接连接到拥有宿主机权限的 Agent。

安装方式怎样选

`uv tool`

1

uv tool install nanobot-ai

适合希望把 CLI 与系统 Python 隔离的用户。升级和卸载也比较清晰，是稳定版本的推荐路径。

pip

1

python -m pip install nanobot-ai

应在虚拟环境中执行。不要向系统 Python 强行安装，尤其不要用管理员权限绕过 externally-managed-environment。

源码安装

源码版本功能更新，但可能需要 bun 或 npm 构建 WebUI，配置和命令也比稳定包变化快。只有需要最新功能或参与开发时才选择源码。

`onboard` 会创建什么

运行：

1

nanobot onboard --wizard

主要生成：

~/.nanobot/config.json：Provider、模型、Agent 和工具配置；
~/.nanobot/workspace/：Agent 工作区、记忆和相关文件。

完成向导后先备份一份不含真实 Key 的配置模板。以后修改配置时采用合并方式，不要复制教程中的整段 JSON 覆盖向导生成内容。

Provider 与模型预设详解

配置通常分为两层：

1
2


providers：怎样连接服务，包括 API Key 和 API Base
modelPresets：使用哪个 Provider、模型 ID 和参数

一个概念示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "custom",
      "model": "model-id-from-your-provider",
      "maxTokens": 8192,
      "contextWindowTokens": 200000,
      "temperature": 0.1
    }
  }
}

真实配置应合并进现有文件。contextWindowTokens 不能随意写成很大数值，必须与 Provider 实际模型一致，否则长任务可能在服务端失败。

首次验证的五个层级

1. 配置状态

1

nanobot status

确认 Config、Workspace 和当前 Provider。未使用 Provider 显示 not set 并不代表错误。

2. 单次消息

1

nanobot agent -m "只回复当前模型名称，不调用任何工具。"

先验证模型连接，不要把 Shell、搜索和 MCP 一起打开。

3. 交互会话

1

nanobot agent

检查多轮上下文、退出和恢复是否符合预期。

4. WebUI

启动 Gateway 并访问 127.0.0.1:8765，验证会话列表、设置和工作区，不先开放局域网。

5. 一个只读工具

最后添加一个只读 MCP 或网页工具，观察工具调用、日志和错误处理。完成后再考虑写入权限。

WebUI 和 Gateway 端口不要混淆

稳定路径：

1

nanobot gateway

浏览器访问：

1

http://127.0.0.1:8765

18790 主要是健康检查端口，不是 WebUI。若页面打不开，先看 Gateway 日志和 8765 监听状态，不要把两个端口都暴露到公网。

后台运行可使用：

1
2
3
4
5


nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

长期运行前先确认日志位置、自动启动和异常退出恢复。

接入 Ollama 的检查项

Ollama 可以通过本地 OpenAI 兼容接口连接，但至少要核对：

API Base 是否可从 nanobot 进程访问；
模型 ID 与 ollama list 一致；
模型是否可靠支持工具调用；
上下文长度配置是否真实；
并发是否会耗尽显存；
Gateway 与 Ollama 是否只监听可信网络。

先测试普通对话，再测试单个工具。若模型返回了看似 JSON 但格式不合法的工具调用，问题可能是模型能力或模板兼容性。

MCP Server 怎样分级授权

类型	初始权限建议
文档查询	只读，可先启用
本地文件	限定工作区，只读起步
浏览器	使用测试 Profile
数据库	只读账号和测试库
Shell	独立低权限环境
云平台	最小 IAM、短期凭据

安装前阅读 Server 源码和工具清单。MCP 配置中出现命令、环境变量和 URL 时，都应视为可执行供应链的一部分。

长期记忆要保存什么

记忆适合保存稳定偏好、项目约定和用户明确要求保留的信息，不适合自动保存：

API Key 和密码；
一次性验证码；
客户原始数据；
未确认的模型推断；
可从项目文件重新读取的大段内容；
已过期的临时任务状态。

启用后定期抽查记忆文件，确认删除和更正机制有效。长期记忆错误会在后续任务中被反复放大。

聊天应用接入顺序

先使用一个测试机器人和只允许自己的白名单账号，再开放群聊。每个渠道都要确认：

谁能向机器人发消息；
群成员能否触发工具；
附件保存在哪里；
是否回显内部日志；
定时任务由谁创建和取消；
机器人离线后怎样恢复；
聊天平台是否保留消息副本。

聊天便利性不能替代身份和权限控制。

定时自动化的安全规则

长时间目标和 Cron 任务应具备：

明确运行频率；
最大执行时间；
最大模型费用；
工具调用次数限制；
幂等或去重机制；
失败通知；
人工停止开关；
不使用无限重试。

第一次创建自动化时只做只读汇总，观察几轮后再允许写文件或发送消息。

公网部署检查清单

如果必须通过服务器访问 WebUI：

设置强随机 NANOBOT_WEB_TOKEN；
使用 HTTPS 反向代理；
只暴露必要端口；
限制来源 IP 或使用 VPN；
持久化配置、工作区和记忆；
不把 Key 写进镜像；
限制容器权限与挂载；
配置日志轮转和备份；
升级前记录版本并测试恢复。

Render 等平台的一键部署也需要持久磁盘，否则会话和记忆可能随实例重建丢失。

故障排查矩阵

现象	常见原因	处理方法
`nanobot` 找不到	工具目录不在 PATH	使用 `uv tool run` 或修复 PATH
401	Key 或 Provider 配置错误	检查 `providers`
404 模型不存在	模型 ID 或 API Base 不匹配	对照服务端模型列表
WebUI 打不开	端口混淆或 Gateway 未启动	检查 8765 和日志
工具调用格式错误	模型不支持或模板不兼容	更换支持工具的模型
重启后会话消失	工作区未持久化	检查磁盘和挂载
聊天机器人无响应	Token、白名单或 Gateway	分层检查渠道日志
定时任务重复执行	缺少幂等和状态记录	增加去重键与执行锁

常见问题

`nanobot` 不在 PATH 中怎么办？

使用安装方式对应的启动命令，例如：

1

uv tool run --from nanobot-ai nanobot --version

也可以检查 uv tool 或虚拟环境的可执行目录是否已加入 PATH。

WebUI 打不开但健康检查正常

WebUI 默认端口是 8765；Gateway 的 18790 端口主要用于健康检查，不是浏览器界面。确认终端中的实际监听地址和错误日志。

可以直接接 Ollama 吗？

可以通过本地 OpenAI 兼容接口配置，但要确认模型支持所需工具调用格式、上下文长度和并发量。普通对话成功不代表 MCP 与复杂工具调用一定稳定。

`nanobot webui` 和 `nanobot gateway` 有什么区别？

稳定发行版优先使用 gateway 并手动打开页面；较新的源码版本可能提供 webui 命令自动准备通道并打开浏览器。以当前安装版本的帮助信息为准。

可以多人共享同一个 nanobot 吗？

需要验证用户、会话、工作区和工具权限是否真正隔离。未确认前按单用户 Agent 使用，不要仅靠聊天昵称区分权限。

怎样备份？

备份 ~/.nanobot/config.json 的安全模板、Workspace、记忆和必要会话数据。真实 Key 最好由密钥管理重新注入，不进入普通备份。

更新后配置失效怎么办？

先查看版本变更和迁移说明，用备份恢复后逐项合并配置。不要用旧文件整段覆盖新版本生成的默认结构。

总结

nanobot 的优势是核心较小，同时具备 WebUI、记忆、MCP、自动化和聊天入口。最稳妥的部署方式是从本地终端开始，逐层开放功能和网络范围，并为工具、聊天渠道和长期记忆分别设置权限边界。