nanobot：把自架个人 AI Agent 变成可长驻的工作台
# 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 的开发者。你可以把系统拆成几个容易理解的部分：
1. **入口与通道**：WebUI、终端机、聊天平台与 API 负责把使用者工作送进 runtime。
1. **模型与路由**：可设定不同 provider、模型与 fallback，也能使用 OpenAI-compatible endpoint 或本地模型服务。
1. **工具层**：档案、Shell、搜寻、MCP、cron、图片生成与 subagents 等能力由模型按需调用。
1. **状态与记忆**：session history 与长期记忆让 Agent 可以承接多步骤工作。
1. **Gateway 与部署**：前景或背景执行、Docker、Docker Compose、Linux service 与 macOS LaunchAgent 都有对应文件。
这种结构也提供清楚的扩充边界：想新增聊天通道，可以先处理讯息适配；想接企业内部工具，则可从 MCP、Python SDK 或 OpenAI-compatible API 切入。
## 快速上手：先用 WebUI 验证完整链路
官方建议第一次启动使用 WebUI。环境需求是 Python 3.11 或更新版本；发布套件已包含 WebUI，从目前原始码安装时则需要 `bun` 或 `npm` 建置前端。若使用 `uv`，可以先安装 CLI：
```bash
uv tool install nanobot-ai
```
接着启动浏览器工作台：
```bash
nanobot webui
```
首次启动会在需要时建立设定与 workspace，启动 gateway，并开启 `http://127.0.0.1:8765`。在 **Settings → Models** 选择 provider、凭证与模型后，建立一个 topic，送出 `Hello!` 验证连线。官方说明中，初次 WebUI 预设绑定 localhost，不会直接暴露到区域网路；这是先在本机验证设定时较安全的预设。
确认前景模式可用后，可以让完整 gateway 在背景执行：
```bash
nanobot webui --background
nanobot gateway status
nanobot gateway logs
```
如果只想在终端机互动，则可使用：
```bash
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：
- 官方 README：
- 官方文件：
- Python package：