Nanobot

Nanobot 快速入门

小巧但能跑长期任务 —— 自托管、可控的个人 AI Agent 运行时。

这是什么？适合谁？

Nanobot（包名 nanobot-ai，不是 nanobot——PyPI 上有个同名的旧 library 已经被这个新项目取代）是香港大学数据智能实验室（HKUDS）出品的开源、自托管个人 AI Agent 运行时。它的核心定位是「a self-hosted personal AI agent you can truly own」——把 Agent 的核心、WebUI、聊天渠道、工具、MCP、记忆、自动化、部署这些常用模块打包成一个能长期跑、可以一键部署到云的服务。GitHub 46.1K+ stars（截至 2026-07），MIT 开源，当前版本 v0.2.2（Durability Release）。

Nanobot 在 GitHub 趋势榜长期霸榜，2026 年获得 Moonshot Kimi 和 MiniMax 等国产模型平台的「开源合作伙伴」背书。

它跟 LangChain / smolagents 这种「Python 库」最大的区别是：Nanobot 是一个完整的 runtime——安装后是一个常驻服务，你通过 CLI、WebUI 或聊天软件跟它交互，而不是写 Python 代码来调用它。但它也暴露 OpenAI 兼容的 REST API + Python SDK，所以既能用 low-code 跑，也能二次开发。

适合谁？一是想自己完全掌控 Agent 部署的开发者（数据、记忆、安全都不上云）；二是需要把 Agent 接到 IM（飞书/微信/Telegram 等）的团队（多个内置 channel）；三是想做长时任务 + 自动化的产品（内置 cron / scheduling / memory）；四是想白嫖国产模型的用户（默认就是 OpenAI 兼容 API，国内模型无缝对接）。不适合：只想 5 分钟跑个一次性的 demo 的用户（这种直接用 LangChain 更轻）；也不适合不想自己运维服务的人（云端 SaaS 型 Agent 可能更省心）。

准备工作

1. Python 3.11 及以上：访问 python.org 下载安装。
2. 包管理器：pip、uv、pipx 均可——官方推荐 uv（更快、隔离更稳）。
3. LLM API Key：任意 OpenAI 兼容服务即可（OpenAI、Anthropic via proxy、DeepSeek、Kimi、智谱、MiniMax 等），推荐国内模型（速度快、无跨境问题）。
4. 操作系统：macOS / Linux 全功能支持；Windows 通过 PowerShell 一键脚本安装（注意：默认 shell executor 在 Windows 下要小心 CRLF，详见踩坑）。

环境变量：装完后用 nanobot onboard --wizard 交互式配置，会引导设置 API Key 和默认模型。

3 步快速上手

第 1 步：安装（macOS / Linux）

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

或者用 pip / uv 手动装：

pip install nanobot-ai
# 或
uv tool install nanobot-ai

注意包名是 nanobot-ai（不是 nanobot，避免和旧包冲突）。Windows 用 PowerShell：

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

第 2 步：初始化

nanobot onboard --wizard

向导会引导你设置：API Key、默认模型、WebUI 端口、记忆存储位置等。完成后配置文件存在 ~/.nanobot/config.yaml。

第 3 步：跟 Agent 对话

三种前端任选：

nanobot chat "今天北京天气怎么样？"          # CLI 单次问答
nanobot                                    # 进入交互式 CLI
nanobot webui                              # 启动本地 Web UI（默认 127.0.0.1:8080）

nanobot webui 启动后浏览器访问 http://localhost:8080，看到一个完整的聊天 UI——支持多会话、文件上传、工具调用可视化、记忆回看。生产环境部署后用 NANOBOT_WEB_TOKEN 设密码保护。

常见踩坑

踩坑 1：pip install nanobot 装的是旧图像处理库

• 症状：执行 pip install nanobot 后，nanobot --help 显示的是图像处理命令，不是 Agent 功能
• 原因：PyPI 上存在一个同名的旧项目 nanobot（0.4MB 的图像处理工具，已停更）；新项目注册在 nanobot-ai 包名下
• 解决：必须 pip install nanobot-ai（末尾有 -ai）；安装后验证用 nanobot --version 确认版本号 ≥ 0.2.x
• 参考：GitHub Issue #2（Feature Request 中讨论了包名问题）

踩坑 2：Windows shell 执行报 \r: command not found

• 症状：在 Windows git-bash 中运行安装脚本或 nanobot 命令时，每行末尾报 \r: command not found 错误
• 原因：Windows 默认使用 CRLF（\r\n）行尾，Nanobot 的 shell 脚本以 LF（\n）为标准，CR 字符被 shell 解释为命令
• 解决：git clone 前设置 git config core.autocrlf false；已 clone 的用 dos2unix scripts/*.sh 转换；官方在 2026-07 已修复 Docker 场景的 CRLF 问题
• 参考：GitHub Issue #215（飞书连接问题讨论中也涉及 Windows 环境差异）

踩坑 3：API Key 写进 config 文件被 commit 到 Git

• 症状：Config 文件中的 API Key 明文暴露，误提交到公共仓库后被他人盗用
• 原因：~/.nanobot/config.yaml 默认存储明文 API Key，用户未将其加入 .gitignore 就提交了仓库
• 解决：config 文件中使用环境变量占位符（${ANTHROPIC_API_KEY}），Key 本身通过 export ANTHROPIC_API_KEY=... 设置；将 ~/.nanobot/config.yaml 或 .nanobot/ 加入 ~/.gitignore；生产环境用 .env 文件（已列在官方 .gitignore 模板中）
• 参考：GitHub Issue #336（DeepSeek provider 配置错误讨论——Key 管理是高频话题）

踩坑 4：WebUI 启动后浏览器 404

• 症状：nanobot webui 启动成功，但浏览器访问 http://localhost:8080 显示 404 Not Found
• 原因：默认绑定 127.0.0.1（仅本机），某些 Docker 或 WSL 环境下本机 IP 映射不对；或端口被占用
• 解决：用 netstat -ano | findstr 8080 检查端口；本机访问用 http://127.0.0.1:8080（不要用 localhost）；外网暴露用 nanobot webui --host 0.0.0.0 并务必设 NANOBOT_WEB_TOKEN 密码
• 参考：GitHub Issue #218（WebUI 功能改进——feat(whatsapp) 讨论中也涉及 WebUI 绑定问题）

踩坑 5：记忆系统持续膨胀占用磁盘

• 症状：运行数天后磁盘使用量持续增加，~/.nanobot/memory/ 目录体积快速增长
• 原因：Nanobot 的 Dream 长期记忆默认索引所有会话并持久化，不做自动清理
• 解决：nanobot memory prune --max-age 30d 定期清理旧记忆；在 config 中设置 memory_max_size 限制最大容量；配置 memory.dream_interval 减少索引频率
• 参考：GitHub Issue #4867（Preserve exact prompt prefix 讨论涉及 memory 性能优化）

踩坑 6：飞书渠道事件回调收不到

• 症状：在飞书群聊中 @Agent 不响应，飞书开发者后台显示「回调请求超时」
• 原因：飞书要求回调地址为公网 HTTPS，本地开发环境没有公网 IP 和证书；事件订阅未正确配置 im.message.receive_v1
• 解决：用 frp / ngrok 做 HTTPS 穿透到本地（nanobot webui 的端口）；在飞书开放平台事件订阅中勾选 im.message.receive_v1；确保 config 中 feishu.verification_token 与后台一致
• 参考：GitHub Issue #215（「飞书无法建立长连接」——最活跃的 feishu 相关 issue，24 条评论）

踩坑 7：CLI 中文乱码

• 症状：在 Windows PowerShell / cmd 中输入中文后，终端显示乱码或报错
• 原因：Windows 控制台默认编码 GBK，Nanobot CLI 输出 UTF-8 字符时无法正确显示
• 解决：chcp 65001 切换到 UTF-8 代码页；或直接用 nanobot webui 浏览器界面（原生 UTF-8 无此问题）
• 参考：GitHub Issue #218（WebUI vs CLI 的中文支持差异在讨论中被多次提及）

踩坑 8：Cron 定时任务不触发

• 症状：配置好 cron 表达式后任务到时间不执行，nanobot cron list 显示任务但始终不运行
• 原因：v0.2.0→v0.2.1 的 cron 实现从 daemon 改为 crontab-based auto-reg 方式，升级后老配置丢失；或 cron daemon 未启动
• 解决：升级后重新 nanobot cron add 注册任务；用 nanobot cron list 验证任务是否在册；检查任务日志 nanobot cron logs <task-id> 看执行状态
• 参考：GitHub Issue #336（DeepSeek provider 问题讨论中也涉及服务自启动和定时任务可靠性）

初级用法

• CLI 模式：nanobot chat "你的问题" 一次问答；nanobot 进入 REPL 风格的多轮会话。
• WebUI：nanobot webui 启动本地聊天 UI，支持文件上传、工具调用可视化、多会话。
• 接 IM 渠道：nanobot channel add telegram --token xxx，把 Agent 接到 Telegram bot（同样支持 Discord / Slack / 飞书 / 微信 / 邮件 / Mattermost）。
• 模型路由：在 config 里配 providers，可以多模型 fallback（首选 Anthropic，挂了自动切 DeepSeek）。
• MCP 工具：nanobot mcp add github-server --url ...，一行接入任意 MCP Server 的工具。
• OpenAI 兼容 API：nanobot serve 启动一个 OpenAI 兼容的 REST endpoint（/v1/chat/completions），现有 OpenAI 客户端代码可以直接指向 Nanobot。
• 子 Agent：nanobot agent create researcher --prompt "你是研究员" 创建可复用的子 Agent，父 Agent 通过 delegate 工具调用。

高级玩法

• 长期目标（/goal）：v0.2.1+ 新增 /goal 显式激活，让 Agent 拆解长期任务、自动规划（适合「帮我准备一次日本旅行」这种跨周任务）。
• 自动化 / Scheduling：内置 cron 表达式定时任务（nanobot cron add "0 9 * * *" "汇总昨天的邮件"），不依赖外部 scheduler。
• 多 Agent 编排：通过 agents/ 目录定义多个 Agent YAML 配置，主 Agent 把子 Agent 当 tool 调用。
• Langfuse 集成：config 里加 observability.langfuse.enabled: true，所有 trace 自动发到 Langfuse（自托管或云）。
• MCP 双向：Nanobot 既能消费 MCP 工具，也能作为 MCP Server 被其他 Agent 调用（nanobot mcp serve）。
• Render 一键部署：仓库自带 render.yaml，点 README 里的 “Deploy to Render” 按钮就能把 Nanobot gateway + WebUI 部署成 Web 服务（需要 Render 付费账户，因为要用 persistent disk）。
• OpenAI 兼容 API + Python SDK：暴露 /v1/chat/completions 给现有 OpenAI 客户端用；同时提供 Python SDK 二次开发（from nanobot import Client）。
• 图片生成 / STT / Search：内置 provider 抽象，config 改一行就能接 OpenAI DALL-E / Stability / ElevenLabs STT / Serper search。

小技巧

1. 先用 nanobot onboard --wizard：不要手写 config，wizard 会引导你填好 API Key、默认模型、WebUI 端口等，避免漏配。
2. nanobot webui --host 0.0.0.0 + Web Token：本机测试够用，外网暴露必须设 NANOBOT_WEB_TOKEN=$(openssl rand -hex 32) 密码。
3. 环境变量引用而不是明文：config.yaml 里写 ${ANTHROPIC_API_KEY} 而不是 sk-ant-...，避免误提交。官方 SECURITY.md 明确推荐这种做法。
4. CLI 调试技巧：交互模式输入 /tools 看可用工具、/memory 看长期记忆、/goal 激活长期目标。WebUI 右下角齿轮里同样有这些面板。
5. 国产模型无缝对接：Nanobot 默认 OpenAI 兼容 API，国内 DeepSeek / Kimi / 智谱 GLM / MiniMax 等都能直接配（Kimi 和 MiniMax 在 README 是官方合作伙伴）。
6. 多渠道路由：单一 Nanobot 实例可以同时接 Telegram + Discord + 飞书 + 邮件，每个渠道独立会话上下文，Agent 自动识别来源。

进阶学习建议

如果你想从「能跑通 Nanobot」走到「能自己扩展 Nanobot」，按这条路径走最快：

1. 先看 Start Without Technical Background：零基础也能跑通的全图文指南。
2. 跑 CLI → WebUI → IM 渠道：按「最少代码 → 完整 UI → IM 集成」顺序渐进，每一步都验证 Agent 能正常回话。
3. 学 config schema：Configuration 文档 讲清楚 providers / memory / mcp / tools / channels 所有可配置项。
4. 读 Architecture 文档：理解 Nanobot 的 runtime 设计（gateway / session / provider / dream memory），方便二次开发。
5. 接 MCP：把 Nanobot 接入已有的 MCP Server（例如 GitHub MCP、Filesystem MCP），立刻获得一批新工具。
6. Render 部署 / Docker 自托管：把 Nanobot 跑成长期服务，再接 IM 渠道做 7×24 个人助手。

可以对比阅读的几个相关项目：LangChain、OpenAI Agents SDK、CowAgent（IM 渠道接 AI 类似思路）。

FAQ

Q1: Nanobot 是免费的吗？

A1: 软件 MIT 开源免费。运行成本 = 模型 API 调用费：默认 OpenAI 兼容 API，国内 DeepSeek-V3 单次约 ¥0.001、GPT-4o-mini 约 ¥0.001、Claude Sonnet 约 ¥0.03。本地模型 0 边际成本（需要显卡）。无平台订阅费、无席位费。

Q2: 跟 LangChain 有什么区别？

A2: LangChain 是 Python 库，你写代码调用它；Nanobot 是 runtime 服务，你跟它对话（或接 IM）。LangChain 适合「用代码构建 Agent 流水线」，Nanobot 适合「跑一个长期在线的个人助手 + 接 IM」。两者可以共存——Nanobot 的 OpenAI 兼容 API 让 LangChain 客户端指向 Nanobot 后端。

Q3: 必须自己部署吗？有没有云服务？

A3: 目前只支持自托管（Render 一键部署是最省事的，但需要付费账户）。官方没出 SaaS，云服务形态依赖用户自己跑。MIT 开源 + 自托管是它的核心定位。

Q4: 包名到底是 nanobot 还是 nanobot-ai？

A4: PyPI 包名是 nanobot-ai。PyPI 上有个同名的旧 nanobot（图像处理工具，已停更）。pip install nanobot-ai 装的是新项目；pip install nanobot 装的是老包。

Q5: 跟 Manus / Devin 这类「自主 Agent 产品」是一个赛道吗？

A5: 不是。Manus / Devin 是「接到任务、自主执行」的执行型 Agent（云端托管、有沙箱浏览器/桌面环境）；Nanobot 是「自托管的个人助手 + IM 接入」，定位偏 ChatGPT + Zapier。两者解决的问题不同——Manus 是「替我干活」，Nanobot 是「长期在线陪我聊天 + 帮我处理小任务」。

参考链接

• Nanobot GitHub
• Nanobot 官方文档
• Start Without Technical Background
• Nanobot 架构文档
• Render 一键部署

免责声明

本文涉及的 GitHub stars 数、版本号、价格等信息基于公开资料整理（截至 2026-07），实际数据请以各项目仓库为准。Nanobot 项目仍在快速迭代（v0.2.x 频繁发版），API 接口和 config schema 可能在后续版本变化，部署到生产前请阅读最新 README 和 CHANGELOG。文中代码示例仅供学习参考，请在遵循各项目许可证的前提下使用。