NanoBot：36K星超轻量AI助手框架深度解析

一款用不到2万行Python代码实现的个人AI Agent框架，OpenClaw的极简复刻版。

项目概况

GitHub： HKUDS/nanobot ⭐ 36,494

NanoBot 是香港大学 HKUDS 团队开发的开源个人AI助手框架，用 Python 编写，MIT 协议。它的目标是用最少的代码实现 AI Agent 的核心能力。

如果 OpenClaw 是一台功能齐全的全自动咖啡机，NanoBot 就是一个手冲咖啡壶——更简单、更透明、更容易理解和改造。

核心数据：

• 语言：Python ≥ 3.11
• 代码量：~1.9 万行（OpenClaw 约 50 万行）
• 内置 Channel：12 个（Telegram、微信、QQ、钉钉、Slack、飞书等）
• LLM Provider：20+ 个（OpenAI、Anthropic、DeepSeek、Ollama 等）
• 状态：Alpha 阶段，快速迭代中

为什么值得关注？

OpenClaw 虽然 33.7 万星、功能强大，但代码量大、依赖 Node.js 生态，对想学习 AI Agent 原理的开发者来说门槛较高。NanoBot 用 99% 更少的代码实现了核心 Agent 循环，特别适合：

• 学习研究 — 代码干净易读，核心 Agent 循环不到 600 行
• 二次开发 — 想基于 Agent 框架做自己的项目
• 快速部署 — 依赖少、启动快、资源消耗低

核心架构：事件驱动 + 消息总线

NanoBot 采用事件驱动架构，核心是一个异步消息总线（MessageBus）解耦所有组件：

聊天平台（Telegram/Discord/微信...）
         │
         ▼
    MessageBus ←── 消息分拣中心
         │
         ▼
    AgentLoop ←── 核心处理引擎
    ┌─────────────────────┐
    │ ContextBuilder      │ ← 构建上下文（记忆+技能+历史）
    │ AgentRunner         │ ← LLM调用 + 工具执行循环
    │ ToolRegistry        │ ← 工具注册表
    │ MemoryStore         │ ← 双层记忆系统
    └─────────────────────┘
         │
         ▼
    ChannelManager ←── 路由回对应平台

数据流：

1. 用户发送消息 → Channel 接收 → 封装为 InboundMessage → 发布到 MessageBus
2. AgentLoop 消费消息 → ContextBuilder 构建上下文 → LLM 生成回复
3. 如果需要工具 → ToolRegistry 执行 → 结果返回给 LLM → 继续循环
4. 最终回复 → OutboundMessage → ChannelManager 路由 → 发送

这种设计的核心优势是解耦：新增一个聊天渠道只需要实现 BaseChannel 接口，完全不影响核心逻辑。

11个核心模块详解

🤖 Agent — 大脑

Agent 是整个框架的核心，包含 5 个关键组件：

• AgentLoop（loop.py）：主循环，负责接收消息→构建上下文→调用LLM→执行工具→返回响应。最多支持 40 轮工具调用迭代。
• ContextBuilder（context.py）：上下文构建器，读取 SOUL.md、USER.md 等身份文件，加载长期记忆，组装技能列表。
• AgentRunner（runner.py）：LLM 调用执行器，处理重试、流式输出、工具调用循环。
• MemoryStore（memory.py）：双层记忆系统——MEMORY.md（长期记忆，像"人生总结"）和 HISTORY.md（可搜索的历史日志，像"日记本"）。
• SubagentManager（subagent.py）：子 Agent 管理，允许主 Agent 派生独立后台任务。

🚌 Bus — 消息总线

基于 asyncio.Queue 的异步消息队列，只有两个文件却承载了整个系统的通信。所有 Channel 把消息扔进入站队列，Agent 处理后把结果扔进出站队列。

📡 Channels — 聊天渠道

支持 12 个平台：Telegram、Discord、微信、企业微信、飞书、钉钉、Slack、WhatsApp、邮件、QQ、Matrix 等。采用自动发现机制，新增 Channel 无需手动注册。

⏰ Cron — 定时任务

支持三种调度：at（一次性定时）、every（固定间隔）、cron（Cron 表达式）。

💓 Heartbeat — 心跳服务

默认每 30 分钟唤醒 Agent 检查是否有事做。巧妙之处在于用工具调用而非文本匹配判断是否有任务，避免了不可靠的令牌解析问题。

🔌 Providers — LLM 提供商

支持 20+ 个 LLM 服务，包括 OpenAI、Anthropic、DeepSeek、Gemini、Ollama、vLLM 等。当设置为 auto 时，通过 API Key 前缀、模型名关键字自动匹配提供商。

🔒 Security — 安全模块

专注 SSRF 防护，拦截对 localhost、私有网络、云元数据服务的请求。

📝 Session — 会话管理

每个对话独立 session，消息以 JSONL 格式追加存储（append-only），对 LLM 的 prompt cache 效率至关重要。

🛠️ Skills — 技能系统

兼容 ClawHub 格式的 Markdown 技能文件，内置 8 个技能：clawhub、cron、github、memory、skill-creator、summarize、tmux、weather。

⚙️ CLI + Config — 命令行与配置

基于 typer + rich 的交互式终端，支持流式输出、代码高亮、交互式引导。

Agent 核心循环代码示例

以下是一段简化版的 Agent 主循环，展示了 NanoBot 的核心逻辑：

async def _run_agent(self, msg: InboundMessage):
    # 1. 获取或创建会话
    session = self.sessions.get_or_create(msg.session_key)
    session.add_message("user", msg.content)
    
    # 2. 构建上下文（系统提示词 + 历史 + 记忆 + 技能）
    system_prompt = self.context.build_system_prompt()
    messages = [{"role": "system", "content": system_prompt}]
    messages.extend(session.get_history())
    
    # 3. 执行 Agent 循环
    result = await self.runner.run(AgentRunSpec(
        initial_messages=messages,
        tools=self.tools,
        model=self.model,
        max_iterations=40,
    ))
    
    # 4. 保存回复并发送
    if result.final_content:
        session.add_message("assistant", result.final_content)
    await self.bus.publish_outbound(OutboundMessage(
        channel=msg.channel, chat_id=msg.chat_id,
        content=result.final_content or "",
    ))

不到 20 行代码，涵盖了会话管理、上下文构建、LLM 调用、工具执行、消息发送的完整流程。

快速上手

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

# 初始化配置（交互式引导）
nanobot onboard

# 开始聊天
nanobot chat

# 或启动服务（连接聊天平台）
nanobot start

也支持 Docker 部署：

docker-compose up

NanoBot vs OpenClaw

选型建议：

• 学习 AI Agent 原理 → NanoBot ✅
• Python 技术栈团队 → NanoBot ✅
• 快速原型验证 → NanoBot ✅
• 生产级部署 → OpenClaw ✅
• 需要丰富插件生态 → OpenClaw ✅

内置工具一览

总结

NanoBot 是一个设计精良的轻量级 Agent 框架。它的核心优势在于代码简洁和架构清晰，核心 Agent 循环不到 600 行，对于 Python 开发者来说是理解"LLM + 工具调用 + 多渠道"现代 Agent 架构的最佳入门项目之一。

虽然目前处于 Alpha 阶段，功能不如 OpenClaw 完善，但作为学习和二次开发的基础框架，NanoBot 提供了极高的可读性和可扩展性。

项目地址： https://github.com/HKUDS/nanobot