nanobot - 超轻量级 AI 助手

nanobot 是香港大学数据智能实验室（HKUDS）开发的超轻量级个人 AI 助手，仅用约 4,000 行 Python 代码实现核心功能，比 OpenClaw 的 43 万行代码小 99%。

这页适合作为“轻量级自托管 AI 助手”的入口文档。nanobot 的价值不只是代码少，而是在资源占用、上手速度、可学习性和多平台集成之间做了很轻的平衡。

适合谁用

• 想快速搭一个个人 AI 助手
• 想研究代理系统实现，但不想一上来就看超大代码库
• 想把 Telegram、Discord、邮件等接进一个轻量网关
• 想在低资源机器上跑自托管助手

核心特性

• 超轻量：核心代码仅 ~4,000 行，启动快、资源占用低
• 易于研究：代码清晰易读，适合学习和二次开发
• 多平台支持：Telegram、Discord、WhatsApp、Feishu、Slack、Email 等
• 多模型支持：11+ LLM 提供商，包括 OpenRouter、Claude、GPT、DeepSeek、Gemini 等
• MCP 集成：支持 Model Context Protocol 工具服务器
• 定时任务：内置 Cron 和心跳机制

快速开始

安装

# 使用 uv（推荐，快速稳定）
uv pip install nanobot-ai

# 或从 PyPI 安装
pip install nanobot-ai

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

初始化

nanobot onboard

配置

编辑 ~/.nanobot/config.json：

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "model": "anthropic/claude-3.5-sonnet"
}

启动

# CLI 交互模式
nanobot agent

# 后台网关（用于聊天平台集成）
nanobot gateway

聊天平台集成

Telegram（推荐）

1. 向 @BotFather 创建机器人获取 token
2. 配置 ~/.nanobot/config.json：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-DEF...",
      "allowFrom": ["your_user_id"]
    }
  }
}

3. 启动网关：

nanobot gateway

Discord

1. 在 Discord Developer Portal 创建应用
2. 启用 Message Content Intent
3. 配置：

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "MTIzNDU2...",
      "allowFrom": ["your_user_id"]
    }
  }
}

WhatsApp

需要 Node.js ≥18：

# 终端 1：链接设备
nanobot channels login

# 终端 2：启动网关
nanobot gateway

扫描二维码完成配置。

Feishu（飞书）

使用 WebSocket 长连接，无需公网 IP：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "allowFrom": []
    }
  }
}

Email

给 nanobot 分配专用邮箱账号：

{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "nanobot@gmail.com",
      "imapPassword": "app-password",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "nanobot@gmail.com",
      "smtpPassword": "app-password",
      "fromAddress": "nanobot@gmail.com",
      "allowFrom": ["your-email@gmail.com"]
    }
  }
}

LLM 提供商配置

OpenRouter（推荐）

访问所有主流模型的统一网关：

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "model": "anthropic/claude-3.5-sonnet"
}

Anthropic Claude

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    }
  },
  "model": "claude-3.5-sonnet-20241022"
}

OpenAI Codex（OAuth）

需要 ChatGPT Plus 或 Pro 订阅：

nanobot provider login openai-codex

本地模型（vLLM）

# 启动 vLLM 服务器
vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000

配置：

{
  "providers": {
    "vllm": {
      "apiKey": "no-key",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "model": "Qwen/Qwen2.5-7B-Instruct"
}

自定义 OpenAI 兼容端点

{
  "providers": {
    "custom": {
      "apiKey": "your-key",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "model": "custom/your-model-name"
}

MCP 支持

连接外部工具服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/workspace"
      ]
    },
    "brave-search": {
      "command": "uvx",
      "args": ["mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    },
    "custom-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

定时任务

心跳任务

编辑 ~/.nanobot/workspace/HEARTBEAT.md：

# 每日任务

- 每天早上 8 点总结昨天的 GitHub 活动
- 每周一提醒本周待办事项
- 每天检查重要邮件并提醒

网关每 30 分钟检查一次，自动执行任务并发送结果到最近活跃的聊天频道。

Docker 部署

docker run -d \
  --name nanobot \
  -v ~/.nanobot:/root/.nanobot \
  ghcr.io/hkuds/nanobot:latest \
  nanobot gateway

使用 Docker Compose：

services:
  nanobot:
    image: ghcr.io/hkuds/nanobot:latest
    container_name: nanobot
    volumes:
      - ~/.nanobot:/root/.nanobot
    command: nanobot gateway
    restart: unless-stopped

Linux 系统服务

创建 ~/.config/systemd/user/nanobot-gateway.service：

[Unit]
Description=nanobot Gateway
After=network.target

[Service]
Type=simple
ExecStart=/home/user/.local/bin/nanobot gateway
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

启用服务：

systemctl --user daemon-reload
systemctl --user enable --now nanobot-gateway

安全配置

{
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "pathAppend": "/usr/sbin"
    }
  },
  "channels": {
    "telegram": {
      "allowFrom": ["123456789"]
    }
  }
}

• restrictToWorkspace：限制文件操作在工作区目录内
• allowFrom：白名单用户 ID，空数组表示允许所有人

CLI 命令参考

nanobot onboard              # 初始化配置
nanobot agent                # 交互式聊天
nanobot agent -m "任务描述"  # 单次执行
nanobot agent --logs         # 显示运行日志
nanobot gateway              # 启动网关
nanobot status               # 查看状态
nanobot provider login       # OAuth 登录
nanobot channels login       # 链接 WhatsApp
nanobot channels status      # 查看频道状态

项目结构

nanobot/
├── nanobot/
│   ├── agent/          # 核心代理逻辑
│   ├── channels/       # 聊天平台集成
│   ├── providers/      # LLM 提供商
│   ├── tools/          # 内置工具
│   ├── mcp/            # MCP 客户端
│   └── config/         # 配置管理
├── scripts/            # 辅助脚本
└── tests/              # 测试

对比 OpenClaw

推荐接入顺序

建议按这个顺序上手：

1. 先跑 CLI 模式
2. 再接一个聊天平台
3. 再接一个主力模型提供商
4. 再补 MCP 和定时任务
5. 最后再做 Docker / systemd 长期运行

常见问题

应该选 nanobot 还是 OpenClaw

如果你更看重轻量、易读、快速部署，优先 nanobot；如果你更看重多模态、浏览器控制和更复杂的自动化能力，优先 OpenClaw。

平台接好了，但体验不稳定

优先排查：

• 模型提供商是否稳定
• 消息平台 Token 和权限是否正确
• 定时任务和心跳是否配置冲突
• 运行环境是否长期在线

适不适合作为生产级团队系统

更适合作为个人助手、研究原型或轻量自托管工具；如果要承载更复杂团队级流程，建议先评估权限边界、日志和可维护性。

延伸阅读

• OpenClaw 文档
• AI 代理对比指南
• AI 代理安全配置指南

参考链接

• GitHub 仓库
• 官方网站
• 发布说明
• OpenRouter 模型列表
• MCP 协议文档