Nanobot：超轻量级 AI Agent 框架，4000 行代码实现智能助手

导语

在 AI Agent 框架领域，现有的解决方案往往功能强大但代码量巨大，动辄数十万行代码让初学者难以理解和修改。

香港大学数据科学实验室（HKUDS）开源了一个名为 Nanobot 的项目——用约 4,000 行代码实现了完整的 AI Agent 功能，核心代理代码仅约 3,800 行。

"大道至简——最强大的工具往往拥有最简单的接口。"

这篇文章将带你深入了解 Nanobot，从架构设计到应用实践，全面解析这个超轻量级 AI Agent 框架。

一、Nanobot 是什么？

一句话概括

Nanobot 是一个超轻量级的个人 AI 助手，核心代码仅约 4,000 行，具备完整的 Agent 能力。

项目信息

项目	信息
来源	香港大学数据科学实验室 (HKUDS)
代码量	~3,800 行核心代码
协议	MIT License
Stars	23.1k+

核心特点

✅ 超轻量级：核心代理代码仅约 4,000 行
✅ 易于研究：代码结构清晰、可读性强
✅ 高性能：极小的占用空间，更快的启动速度
✅ 易于使用：一键部署，快速上手

核心能力

能力维度	具体功能
多渠道通信	接入 Telegram、Discord、WhatsApp、飞书、钉钉、Slack、Email、QQ 等平台
多模型支持	OpenRouter、Anthropic、OpenAI、DeepSeek、Groq、Gemini、MiniMax、vLLM
系统级操作	执行终端命令、读写文件、网页搜索
智能调度	定时任务、自动化工作流、持久记忆
MCP 支持	连接外部工具服务器作为原生代理工具
Agent 社交	连接 Moltbook、ClawdChat 等 Agent 社区

二、核心架构

Nanobot 的架构设计注重模块化和简洁性，整体可以分为以下模块：

nanobot/
├──  agent/                    # 核心代理逻辑
│   ├── loop.py                 # 代理循环 (LLM ↔ 工具执行)
│   ├── context.py              # 提示词构建器
│   ├── memory.py               # 持久化记忆
│   ├── skills.py               # 技能加载器
│   ├── subagent.py             # 后台任务执行
│   └── tools/                  # 内置工具集
│       └── spawn.py            # 进程生成
│
├──  skills/                   # 捆绑的技能包
│
├──  channels/                 # 聊天渠道集成
│   ├── telegram.py             # Telegram 集成
│   ├── discord.py              # Discord 集成
│   ├── whatsapp.py             # WhatsApp 集成
│   ├── feishu.py               # 飞书集成
│   ├── dingtalk.py             # 钉钉集成
│   └── ...
│
├──  bus/                      # 消息路由
│
├── ⏰ cron/                     # 定时任务
│
├──  heartbeat/                # 主动唤醒机制
│
├──  providers/                # LLM 提供商
│   ├── openrouter.py
│   ├── anthropic.py
│   ├── openai.py
│   ├── deepseek.py
│   └── ...
│
├──  session/                  # 对话会话管理
│
├── ⚙️  config/                  # 配置管理
│
└── ️  cli/                     # 命令行界面

2.1 架构详解

核心代理层 (agent/)

这是 Nanobot 的心脏：

loop.py: 代理循环，负责 LLM 与工具之间的调用流转
context.py: 构建发送给 LLM 的上下文，包含系统提示和历史对话
memory.py: 持久化记忆，让代理记住之前的交互
skills.py: 技能加载器，动态加载扩展功能
subagent.py: 后台任务执行，支持异步处理

消息通道层 (channels/)

支持多平台消息接入：

平台	特点	适用场景
Telegram	移动端友好，免费 API	个人助手
Discord	社区活跃，功能丰富	游戏社区、团队协作
WhatsApp	用户基数大	国际用户
飞书	企业级集成	企业内部助手
钉钉	国内企业	中国企业
Slack	工作流集成	团队协作

LLM 提供商层 (providers/)

支持多种 LLM 后端：

云端模型: OpenAI、Anthropic Claude、Google Gemini、DeepSeek
聚合服务: OpenRouter（一站式接入多模型）
本地模型: vLLM、Ollama
高性能推理: Groq

调度系统

bus/: 消息路由，负责消息在各个组件间的流转
cron/: 定时任务，支持周期性自动化工作流
heartbeat/: 主动唤醒机制，让 Agent 能主动发起交互

三、核心特性

3.1 极简代码

指标	数据
核心代码行数	~3,800 行
启动时间	秒级
内存占用	极低
学习成本	低

极简代码带来的优势：

易于理解：新人可以快速阅读源码，理解工作原理
易于修改：小代码量意味着修改成本低
快速迭代：开发周期短，反馈迅速
教学友好：适合作为 AI Agent 入门学习材料

3.2 多 LLM 支持

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    },
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    },
    "openai": {
      "apiKey": "sk-xxx"
    },
    "deepseek": {
      "apiKey": "sk-xxx"
    }
  }
}

支持的模型提供商：

OpenRouter: 一站式接入 Claude、GPT、Gemini 等主流模型
Anthropic: 直接调用 Claude 系列
OpenAI: 直接调用 GPT 系列
DeepSeek: 国产大模型，性价比高
Groq: 超快推理速度
vLLM: 本地部署大模型

3.3 多平台接入

Nanobot 支持一键接入多个聊天平台：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    },
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    },
    "feishu": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET"
    }
  }
}

3.4 MCP 协议支持

Nanobot 支持 MCP (Model Context Protocol)，可以连接外部工具服务器并将其作为原生代理工具使用：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

3.5 Agent 社交网络

Nanobot 能够连接到 Agent 社区（如 Moltbook、ClawdChat），实现 Agent 间的社交互动：

Moltbook: Agent 社交平台
ClawdChat: Agent 聊天社区

只需发送一条消息即可自动加入社区。

3.6 持久记忆

# memory.py 核心逻辑
class Memory:
    def __init__(self, db_path: str):
        self.db = SQLite(db_path)

    def save_message(self, session_id: str, role: str, content: str):
        """保存消息到数据库"""
        self.db.execute(
            "INSERT INTO messages VALUES (?, ?, ?, ?)",
            (session_id, role, content, datetime.now())
        )

    def get_context(self, session_id: str, limit: int = 10):
        """获取最近的对话上下文"""
        return self.db.query(
            "SELECT * FROM messages WHERE session_id=? ORDER BY created_at DESC LIMIT ?",
            (session_id, limit)
        )

四、关键流程

4.1 代理循环流程

Nanobot 的核心工作流程是一个 LLM ↔ 工具 的循环：

┌──────────────────────────────────────────────────────────────┐
│                        用户输入                               │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                    Context Builder                          │
│         构建系统提示词 + 历史对话 + 可用工具列表              │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                      LLM 推理                                │
│              分析用户意图，决定是否调用工具                    │
└──────────────────────────┬───────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
        ┌──────────┐            ┌────────────────┐
        │ 不需要工具 │            │ 需要调用工具    │
        │ (直接回复) │            │                │
        └────┬─────┘            └────────┬───────┘
             │                           │
             ▼                           ▼
        ┌──────────┐            ┌────────────────┐
        │ 返回结果  │            │ 执行工具调用    │
        └────┬─────┘            └────────┬───────┘
             │                           │
             └───────────┬───────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   工具返回结果注入   │
              │   回到 Context      │
              │   Builder 继续循环  │
              └─────────────────────┘

4.2 消息路由流程

用户 (Telegram/Discord/飞书...)
        │
        ▼
┌──────────────────┐
│  Channel Handler │  消息渠道处理器
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Message Bus    │  消息路由总线
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Session Mgr    │  会话管理
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Agent Loop     │  核心代理循环
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Response Build │  构建响应消息
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Channel Output │  返回给对应渠道
└──────────────────┘

4.3 定时任务流程

# 添加定时任务
nanobot cron add "0 9 * * *" "每天早上9点提醒我开会"

# 查看定时任务
nanobot cron list

# 删除定时任务
nanobot cron remove <task_id>

定时任务工作流程：

cron 模块监听系统时间
到达设定时间时，触发任务
任务消息注入到消息总线
Agent 执行相应操作

4.4 主动唤醒机制

heartbeat 模块让 Agent 可以主动发起交互：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Heartbeat  │────▶│   Agent     │────▶│   Channel   │
│   Timer     │     │   Action    │     │   Output    │
└─────────────┘     └─────────────┘     └─────────────┘
      │
      │ 定时触发
      ▼
┌─────────────────────────────────────────────────────────┐
│  示例：                                                  │
│  • 每小时检查邮件并提醒                                  │
│  • 监控服务器状态并报警                                  │
│  • 定期生成日报/周报                                     │
└─────────────────────────────────────────────────────────┘

五、应用场景

5.1 个人 AI 助手

最基础的用法——一个 7×24 小时在线的个人助手：

# 启动交互模式
nanobot agent

# 发送单条消息
nanobot agent -m "帮我整理一下今天的待办事项"

典型任务：

日程管理和提醒
邮件摘要和回复建议
数据分析和报告生成
信息搜索和整理

5.2 市场分析助手

24/7 实时市场分析与洞察：

# 添加定时任务监控市场
nanobot cron add "0 */4 * * *" "分析最近4小时的市场动态"

5.3 全栈开发助手

辅助开发、部署和扩展：

代码生成和审查
调试和问题排查
项目脚手架生成
部署脚本编写

5.4 知识管理助手

个人知识库的学习、记忆和推理：

文档整理和摘要
知识图谱构建
❓ 智能问答
笔记关联

5.5 企业内部助手

通过飞书/钉钉集成，搭建企业级 AI 助手：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET"
    }
  }
}

六、快速上手

6.1 安装

方式一：pip 安装（推荐）

pip install nanobot-ai

方式二：uv 安装（更快）

uv tool install nanobot-ai

方式三：源码安装（开发者）

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

6.2 初始化配置

nanobot onboard

按提示填入 API Key 等配置信息。

6.3 配置文件

配置文件位于 ~/.nanobot/config.json：

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

6.4 开始使用

# 交互模式
nanobot agent

# 单条消息
nanobot agent -m "你好，介绍一下你自己"

6.5 连接 Telegram

在 Telegram 中通过 @BotFather 创建 Bot 并获取 Token
在配置文件中添加：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

运行网关：

nanobot gateway

6.6 Docker 部署

# 初始化配置
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# 启动网关
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

七、常用命令

命令	说明
`nanobot onboard`	初始化配置和工作区
`nanobot agent`	交互式聊天模式
`nanobot agent -m "..."`	发送单条消息
`nanobot gateway`	启动网关服务（连接聊天平台）
`nanobot status`	查看状态
`nanobot cron add`	添加定时任务
`nanobot cron list`	列出定时任务
`nanobot cron remove`	删除定时任务

八、总结

Nanobot 代表了 AI Agent 领域的一种新思路：不是功能的堆砌，而是极致的简约。

核心价值

极简代码: 4000 行实现核心功能，易于理解和修改
快速上手: 一键安装，两分钟部署
多平台支持: 覆盖主流聊天应用和 LLM 提供商
MCP 兼容: 支持外部工具服务器扩展
教学友好: 适合作为 AI Agent 入门学习材料

适用人群

AI 初学者: 想理解 AI Agent 工作原理
‍ 开发者: 需要快速原型或定制化开发
小团队: 需要轻量级 AI 助手解决方案
研究者: 需要可修改的实验平台

局限性

功能相对基础，不适合复杂场景
Skills 生态仍在发展中
文档和社区资源相对较少

如果你追求的是简单、易懂、可定制的 AI Agent 框架，Nanobot 是一个绝佳的选择。

warm3snow

Nanobot：超轻量级 AI Agent 框架，4000 行代码实现智能助手

Nanobot：超轻量级 AI Agent 框架，4000 行代码实现智能助手

导语

一、Nanobot 是什么？

一句话概括

项目信息

核心特点

核心能力

二、核心架构

2.1 架构详解

核心代理层 (agent/)

消息通道层 (channels/)

LLM 提供商层 (providers/)

调度系统

三、核心特性

3.1 极简代码

3.2 多 LLM 支持

3.3 多平台接入

3.4 MCP 协议支持

3.5 Agent 社交网络

3.6 持久记忆

四、关键流程

4.1 代理循环流程

4.2 消息路由流程

4.3 定时任务流程

4.4 主动唤醒机制

五、应用场景

5.1 个人 AI 助手

5.2 市场分析助手

5.3 全栈开发助手

5.4 知识管理助手

5.5 企业内部助手

六、快速上手

6.1 安装

6.2 初始化配置

6.3 配置文件

6.4 开始使用

6.5 连接 Telegram

6.6 Docker 部署

七、常用命令

八、总结

核心价值

适用人群

局限性

相关资源

公告