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、自動化和聊天入口。最穩妥的部署方式是從本地終端開始，逐層開放功能和網路範圍，併為工具、聊天渠道和長期記憶分別設定許可權邊界。