[Python] 港大开源Nanobot：用1%代码量复刻Clawdbot的AI助手，附安装部署教程

一、项目简介

Nanobot 是一款由 HKUDS（香港大学数据科学实验室）开发的超轻量级个人人工智能助手。

若想了解另一个热门项目 ClawdBot，可以参阅其介绍。

核心特点

• 极致精简：仅需约 4，000 行代码即可实现核心代理（Agent）功能，相较于 Clawdbot 的 430k+ 行代码，精简了约 99%。
• 多模型支持：兼容 OpenRouter、Anthropic 等多个 AI 服务提供商的模型。
• 多渠道接入：支持命令行界面（CLI）与 WhatsApp 等多种交互方式。
• 工具扩展：内置文件操作、命令行执行等多种工具能力，具备良好的可扩展性。

注意：当前的代码量是主体实现，部分功能仍在开发中。

二、架构说明

Nanobot 采用模块化设计，其核心架构旨在清晰分离消息处理、智能决策与工具执行。

工作流程

1. 消息接收：用户通过 CLI 或 WhatsApp 发送指令或消息。
2. 消息路由：Gateway（网关）接收消息并将其路由至相应的 Agent 进行处理。
3. 意图理解：Agent 调用后端的大语言模型（LLM）来理解用户的指令意图。
4. 工具调用：根据 LLM 的分析结果，Agent 调用相应的工具（如文件操作、执行系统命令等）来完成任务。
5. 结果返回：将工具执行的结果或 LLM 生成的回复返回给用户。

三、安装部署

前置要求

• Python 版本：需要 Python 3.8 或更高版本。
• API 密钥：需要提前准备 OpenRouter 或其他支持的 LLM 服务商的 API Key。

安装步骤

# 1. 克隆仓库
git clone https://github.com/HKUDS/nanobot.git

# 2. 进入项目目录
cd nanobot

# 3. 安装依赖（推荐使用开发模式）
pip install -e .

配置说明

1. 初始化配置

首次使用时，需要运行以下命令进行初始化配置：

nanobot onboard

2. 配置文件位置

配置文件通常位于以下路径：

• Linux/Mac: ~/.nanobot/config.json
• Windows: C:\Users\你的用户名\.nanobot\config.json

3. 配置项详解

3.1 API 服务提供商配置

在此部分配置您使用的 LLM 服务商及 API 密钥。

{
  "providers": {
    "openrouter": {
      "apiKey": "你的-OpenRouter-API-密钥"
    }
  }
}

3.2 Agent 默认配置

此部分定义了 Agent 的默认行为参数，如使用的模型、工作空间、生成长度等。

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4.5",
      "workspace": "~/.nanobot/workspace",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 20
    }
  }
}

3.3 WhatsApp 集成配置

如果需要启用 WhatsApp 通道，需在此进行配置。

{
  "whatsapp": {
    "enabled": true,
    "bridgeUrl": "ws://localhost:3001",
    "allowFrom": [""]
  }
}

参数说明：

• enabled: 布尔值，是否启用 WhatsApp 通道。
• bridgeUrl: WhatsApp 桥接服务的 WebSocket 地址。
• allowFrom: 允许接收消息的电话号码白名单列表（需使用国际格式，例如 +8612345678901）。

四、WhatsApp 集成配置

1. 登录 WhatsApp

首次启用 WhatsApp 功能时，需要登录您的账号：

nanobot channels login

执行流程如下：

1. 该命令会从项目源码中复制 WhatsApp 桥接服务文件到本地目录（例如：C:\Users\你的用户名\.nanobot\bridge\src\whatsapp.ts）。
2. 启动桥接服务后，终端会显示一个二维码。
3. 在您的手机上打开 WhatsApp 应用。
4. 进入 设置 → 已关联的设备 → 关联设备。
5. 扫描终端上显示的二维码。扫描成功后，终端会显示 ✓ Connected to WhatsApp 的消息，表示连接成功。

五、启动服务

启动 Gateway

配置完成后，通过以下命令启动 Nanobot 网关服务：

nanobot gateway

预期输出示例：

[2026-02-04 10:30:00] INFO - Starting Nanobot Gateway...
[2026-02-04 10:30:01] INFO - Gateway server started on port 3000
[2026-02-04 10:30:02] INFO - Connected to WhatsApp bridge
[2026-02-04 10:30:02] INFO - ✓ All systems ready

当看到 Connected to WhatsApp bridge 日志时，表示 WhatsApp 通道已成功连接并准备就绪。

六、功能测试

1. 命令行测试

通过 CLI 测试基础问答功能：

nanobot agent -m “What is 2+2?”

预期输出示例：

| INFO | nanobot.agent.loop:_process_message:138 - Processing message from cli:user
🐈 2 + 2 = **4**

2. 功能测试结果

在实际测试中，Nanobot 能较好地理解和响应指令，但其能力边界需要明确：它主要通过调用预定义工具（如执行命令行）来操作环境，而非直接控制图形界面。

• 测试 1：打开浏览器
  • 结果：未能打开图形化浏览器。Agent 澄清了其作为后台服务的定位，并提供了替代的网络操作建议（如网页搜索、获取内容、执行命令行启动浏览器）。

• 测试 2：打开 D 盘
  • 结果：成功执行了列出目录的命令。Agent 理解了“打开”在此上下文中的意图是“浏览”或“列出”，并执行了相应的命令行工具来展示 D 盘根目录下的文件夹列表。

总的来说，Nanobot 作为一个轻量级、代码精简的 AI 助手，在理解和执行基于工具/命令行的任务方面表现合格。它清晰地将自己定位为一个增强效率的智能体，而非一个全能的桌面控制机器人。对于希望在本地快速部署一个可扩展、支持多通道的 AI 助手框架的Python开发者而言，这是一个非常有价值的开源实战项目。

如果你对构建类似的人工智能应用或探讨更多技术细节感兴趣，欢迎在云栈社区交流分享。