nanobot：把自架個人 AI Agent 變成可長駐的工作台

如果你想把 AI Agent 放在自己的電腦或伺服器上，真正遇到的問題通常不是「能不能呼叫模型」，而是模型如何接上工具、記住上下文、持續執行任務，並且讓人可以從瀏覽器、終端機或既有聊天軟體操作。HKUDS/nanobot 正好把這些執行環節收斂成一個 Python 專案：它是可自架的個人 AI Agent framework，提供 WebUI、終端機與多種聊天通道，並把工具、長期記憶、MCP、模型路由、子代理與排程自動化放在同一個 runtime 裡。

本文以 GitHub repository 的 README、pyproject.toml 與官方文件連結為主要資料來源，整理 nanobot 的定位、架構、快速上手方式，以及它適合哪些 AI Chain 開發情境。

先看懂 nanobot 解決什麼問題

一般聊天機器人只需要處理「收到訊息 → 回覆文字」；可長駐的 Agent 則要處理更長的生命週期：

從 WebUI、CLI 或 Telegram、Discord、Slack、WeChat、Email、Mattermost 等通道接收工作。
讓模型在需要時呼叫檔案、Shell、網路搜尋、網頁擷取、MCP、排程、圖片生成或子代理工具。
保存工作階段歷史與長期記憶，讓任務不必每次從零開始。
將長時間目標與週期性自動化交給 gateway 持續執行。
透過 Python SDK 或 OpenAI-compatible API，讓其他應用程式也能整合這個 Agent。

nanobot 的價值不在於再包一層聊天 UI，而在於把「模型決策」和「可持續執行的工具環境」接起來。這使它比較接近一個可自架的 Agent runtime，而不是單次問答腳本。

核心設計：小型 Agent loop，加上可插拔能力

官方 README 將 nanobot 的核心描述為一個小型 agent loop：訊息先從聊天通道進來，LLM 再判斷是否需要使用工具；記憶與 skills 則在需要時作為上下文載入，而不是把所有資料都堆成一個龐大的 orchestration layer。

這個取捨很適合想讀懂、修改或自行部署 Agent 的開發者。你可以把系統拆成幾個容易理解的部分：

入口與通道：WebUI、終端機、聊天平台與 API 負責把使用者工作送進 runtime。
模型與路由：可設定不同 provider、模型與 fallback，也能使用 OpenAI-compatible endpoint 或本地模型服務。
工具層：檔案、Shell、搜尋、MCP、cron、圖片生成與 subagents 等能力由模型按需調用。
狀態與記憶：session history 與長期記憶讓 Agent 可以承接多步驟工作。
Gateway 與部署：前景或背景執行、Docker、Docker Compose、Linux service 與 macOS LaunchAgent 都有對應文件。

這種結構也提供清楚的擴充邊界：想新增聊天通道，可以先處理訊息適配；想接企業內部工具，則可從 MCP、Python SDK 或 OpenAI-compatible API 切入。

快速上手：先用 WebUI 驗證完整鏈路

官方建議第一次啟動使用 WebUI。環境需求是 Python 3.11 或更新版本；發佈套件已包含 WebUI，從目前原始碼安裝時則需要 bun 或 npm 建置前端。若使用 uv，可以先安裝 CLI：

uv tool install nanobot-ai

接著啟動瀏覽器工作台：

nanobot webui

首次啟動會在需要時建立設定與 workspace，啟動 gateway，並開啟 http://127.0.0.1:8765。在 Settings → Models 選擇 provider、憑證與模型後，建立一個 topic，送出 Hello! 驗證連線。官方說明中，初次 WebUI 預設綁定 localhost，不會直接暴露到區域網路；這是先在本機驗證設定時較安全的預設。

確認前景模式可用後，可以讓完整 gateway 在背景執行：

nanobot webui --background
nanobot gateway status
nanobot gateway logs

如果只想在終端機互動，則可使用：

nanobot agent
nanobot agent -m "Hello!"

agent -m 適合做一次性的 provider 檢查、Shell script 或本地自動化；gateway 則適合讓聊天通道與排程持續運作。

從「會聊天」走向「能完成工作」

nanobot 的實作潛力，主要來自幾個可以組合的能力。

1. 工具與 MCP

Agent 不只產生文字，也能根據任務需要讀寫檔案、執行 Shell、搜尋網路、擷取網頁，或透過 MCP 連接外部工具。這讓它可以從「回答如何做」進一步走到「在授權範圍內完成一段流程」。部署到工作環境時，仍應先針對 workspace、Shell 與網路工具設定最小權限，並分開測試高風險操作。

2. 記憶與長時間任務

README 將 session history、long-term memory 與 Dream 列為功能的一部分。對研究、內容整理、專案維護或週期性報表來說，這比單一對話視窗更接近實際工作流：任務可以保留上下文，排程也可以在 gateway 持續啟動。

3. 多代理與模型切換

目前版本的 release 說明包含 inline subagents、每個 session 的 model switching，以及更完整的執行控制。這代表一個主 Agent 可以在同一個工作情境中，把特定子任務交給 helper，或依工作需求切換模型預設；不過模型切換和子代理不等於自動保證正確性，仍需要在 prompt、工具權限、輸出驗證與失敗重試上建立工程規則。

4. 聊天通道與 API 整合

WebUI 適合除錯與觀察工具呼叫，CLI 適合開發者快速測試，聊天平台則適合把 Agent 放進日常協作。若要接到既有服務，也可以評估 Python SDK 或 OpenAI-compatible API，而不是直接耦合內部模組。

什麼情況適合採用？

nanobot 特別適合以下幾類情境：

想在自己的硬體或伺服器部署個人 AI 助理，而不是把資料全部交給代管平台。
需要把 LLM 接到檔案、命令列、搜尋、MCP 或既有聊天通道。
想先用 WebUI 驗證 Agent，再以 gateway、Docker 或系統服務長駐。
需要 session、長期記憶與排程，讓 Agent 支援多步驟或週期性工作。
想研究一個相對容易閱讀的 Python Agent runtime，並在其上自訂 provider、tool 或 channel。

反過來說，如果需求只是一次性的模型問答、完全不需要工具和背景執行，nanobot 的 gateway、通道與權限設定可能會超出必要範圍。

自架前的三個檢查點

第一，先界定執行邊界。 Shell、檔案與網路工具會讓 Agent 具備實際影響力。應從專用 workspace、受限帳號與明確的工具白名單開始，而不是一開機就給它整台主機的權限。

第二，把模型設定和秘密管理分開。 API key 不應寫入文章、版本庫或聊天訊息；部署時使用環境變數或專用秘密管理機制，並確認 log 不會回顯敏感值。

第三，為長時間任務設計可觀測性。 WebUI 能查看 reasoning、tool calls、檔案編輯、diff、命令輸出與產物；正式環境仍建議保留 gateway status、logs、失敗通知與人工核准點，讓自動化可以被追蹤和停止。

結語

nanobot 把自架 AI Agent 的幾個關鍵部件放在同一個可執行環境：WebUI 與 CLI 負責操作，gateway 負責長駐，工具與 MCP 負責延伸能力，記憶與 session 負責延續上下文，SDK 與 API 負責整合其他服務。它最值得研究的地方，不是功能清單很長，而是試圖用一個相對小型、可讀的 Agent loop，承接從個人助理到自動化工作流的完整路徑。

若要評估它是否適合你的團隊，建議先用本機 WebUI 完成一個低風險任務，再逐步加入 MCP、聊天通道、排程與背景 gateway；每增加一項能力，就同步補上權限、記錄與停止機制。這樣才能把「會呼叫模型」穩定地轉成「能在自己的環境完成工作」。

官方資料

GitHub repository：<https://github.com/HKUDS/nanobot>
官方 README：<https://github.com/HKUDS/nanobot/blob/main/README.md>
官方文件：<https://nanobot.wiki/docs/latest/getting-started/nanobot-overview>
Python package：<https://pypi.org/project/nanobot-ai/>
Release v0.3.0：<https://github.com/HKUDS/nanobot/releases/tag/v0.3.0>