hkuds/nanobot · 上手攻略

• 仓库：HKUDS/nanobot
• 链接：https://github.com/HKUDS/nanobot
• 分类：agent · llm-infra
• 作者：Tom
• 更新：2026-07-09

它是什么

nanobot 是香港大学研究团队开源的轻量级个人 AI Agent 运行时，定位是"你可以真正拥有的个人 AI 助手"。v0.2.2（Durability Release），MIT 许可证，Python 实现，当前 Stars 超过 45k，是近期增长最快的开源 Agent 项目之一。

核心理念：保持 Agent 核心代码小而可读，将重量级的编排层（如复杂的工作流引擎）拆散，按需引入工具、记忆、MCP、模型路由、自动化和部署能力，而不是一股脑塞进核心。官方口号："ultra-lightweight personal AI agent you can truly own"。

支持能力一览： - 运行形态：浏览器 WebUI 或纯终端 - 聊天渠道：Telegram、Discord、Slack、WeChat、Email、Mattermost、Feishu 等 - 工具：文件操作、Shell 命令、Web 搜索、Web 抓取、MCP、CRON 定时任务、图片生成、子 Agent - 记忆：Session 历史 + 长期记忆（Dream 模块） - 自动化：长时程目标执行、定时任务 - 集成：Python SDK、OpenAI 兼容 API

解决什么问题

• 不想被平台锁定：不想用闭源的 ChatGPT Agent 或商业套件，想自己托管完全可控的个人 Agent。
• 需要接入多个聊天渠道：希望同一个 Agent 既能在 Telegram、Discord 工作，又能在内部 IM 里跑。
• Agent 核心需要可读可改：主流框架（LangChain/LangGraph）体量太大，nanobot 核心代码小，适合学习或深度定制。
• 个人生产力自动化：需要一个 24/7 跑着的个人助手，处理搜索、提醒、代码任务、知识管理。

快速安装

环境要求

• Python 3.11+
• 一个 LLM Provider（OpenAI / Azure / Ollama / Kimi / MiniMax 等，支持任意 OpenAI 兼容 API）

一键安装（推荐）

macOS / Linux：

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

Windows PowerShell：

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

安装脚本会自动创建虚拟环境（避免污染系统 pip），安装 nanobot-ai，然后启动 nanobot onboard --wizard 交互式引导。

预览安装计划（不实际修改环境）：

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

手动安装

# PyPI + uv（推荐）
uv tool install nanobot-ai

# 或 pip（建议在虚拟环境中）
python -m pip install nanobot-ai

# 源码安装（最新功能）
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install -e .

验证安装：

nanobot --version

核心用法

第一步：初始化

nanobot onboard

创建两个核心文件： - ~/.nanobot/config.json — 主配置文件 - ~/.nanobot/workspace/ — Agent 工作空间（含记忆、会话、技能等）

交互式向导：nanobot onboard --wizard

第二步：配置 Provider 和 Model

编辑 ~/.nanobot/config.json，添加 provider 配置（以通用自定义 provider 为例）：

{
  "providers": {
    "custom": {
      "apiKey": "${YOUR_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "custom",
      "model": "你的模型ID",
      "maxTokens": 8192,
      "contextWindowTokens": 200000,
      "temperature": 0.1
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

注意：apiBase 只有在使用 custom provider（第三方/自托管 OpenAI 兼容 API）、Ollama、vLLM 等本地模型时才需要设置。官方各 Provider（如 OpenAI、Kimi、Azure 等）已有默认 endpoint，通常只需填 apiKey 和 model。

环境变量方式（避免密钥明文写入配置）：

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

第三步：验证配置

nanobot status

检查 Config 和 Workspace 是否显示 ✓，Active Model 是否为你的预设模型。

第四步：发送第一条消息

单次 CLI 消息（测试用）：

nanobot agent -m "Hello!"

交互式聊天（终端内）：

nanobot agent

打开 WebUI（浏览器界面）：

nanobot webui

然后访问 http://127.0.0.1:8765 ，首次引导会自动设置 WebSocket 通道。

WebUI 默认绑定 127.0.0.1，不会暴露到 LAN。如需远程访问，见 WebUI LAN 访问文档。

接入聊天应用（可选）

以 Telegram 为例：

1. 在 Telegram 找 @BotFather 创建 Bot，获得 Bot Token
2. 编辑 ~/.nanobot/config.json，合并：

{
  "channels": {
    "telegram": {
      "token": "你的BotToken",
      "allowFrom": ["*"]
    }
  }
}

3. 启用插件：

nanobot plugins enable telegram
nanobot channels status
nanobot gateway

其他平台（Discord、Slack、WeChat、Email 等）配置方式类似，见 Chat Apps 文档。

使用 MCP（Model Context Protocol）

nanobot 支持 MCP 扩展工具，具体配置见 Configuration 文档。

典型适用场景

坑与注意

1. Python 3.11+ 严格：不支持 3.10 及以下版本，部分 Linux 发行版默认 Python 较旧，需要手动安装。
2. 首次安装建议走一键脚本：手动 pip install 不一定会创建虚拟环境，可能污染系统包；官方脚本会用 uv/pipx/venv 自动隔离。
3. Gateway 需要长期运行：接聊天渠道时 nanobot gateway 必须持续运行，断开后 Bot 不再响应；建议用 systemd 或 Docker 守护进程。
4. API Key 建议用环境变量：${VAR_NAME} 语法支持引用环境变量，避免密钥明文写在 config.json 里。
5. WebUI 默认不回传 LAN：默认只监听 127.0.0.1，如果需要其他设备访问要走 LAN 配置流程。
6. provider 和 model 必须匹配：preset 里的 provider 值必须和 providers 里的 key 一致，否则会报 provider not found。
7. Windows PowerShell 安装脚本：需要 PowerShell 7+ 支持，部分 Windows 旧版本需要手动安装。

与同类对比

一句话推荐结论

如果你想要一个完全自己掌控、轻量到可以读懂源码、又能接 Telegram/Discord 多渠道、24/7 跑着的个人 AI Agent，nanobot 是目前开源社区里"最小可用地板"最低的选择——45k Stars 的爆发增长已经证明了它的实用价值。