从 43 万行到 4000 行，港大团队如何把“贾维斯”塞进你的笔记本电脑？

如果你关注 AI Agent 领域，一定听说过 OpenClaw（或称 Clawdbot）—— 那个能写代码、上网冲浪、操作电脑、定时提醒的“个人贾维斯”。它功能强大，但当你兴致勃勃地克隆源码准备学习时，43 万行代码扑面而来，瞬间让人望而却步。

就在最近，香港大学数据科学实验室（HKUDS）开源了一个名为 nanobot 的项目，彻底改变了这个局面。它将 OpenClaw 的核心能力压缩到 仅 4000 行 Python 代码，砍掉了 99% 的体量，却保留了完整的 AI Agent 核心功能。

本系列文章将深入 nanobot 的源码，带你逐行解析这个轻量级 AI Agent 框架的设计精髓。作为开篇，我们先来认识 nanobot 是什么、为什么值得学习，以及如何快速上手体验。

---

1. 什么是 nanobot？

nanobot 是一个超轻量级的个人 AI 助手框架，由香港大学数据科学实验室开源发布。它受 OpenClaw 启发，目标是提供一个易于理解、快速部署、灵活扩展的 Agent 开发底座。

核心特点

• 极致轻量：核心代码仅约 4000 行，是 OpenClaw 的 1%
• 纯 Python 实现：无需复杂的编译环境，pip 安装即可使用
• 功能完备：支持 Agent 循环、工具调用、多轮记忆、定时任务、多渠道接入
• 模型无关：支持 OpenAI、Anthropic、DeepSeek、Gemini 以及本地 vLLM 等主流 LLM
• 易于学习：代码结构清晰，是学习 AI Agent 原理的绝佳范本

维度	OpenClaw / Clawdbot	nanobot
代码量	43 万+ 行	约 4000 行
部署复杂度	较高，依赖多	pip install 即可
二次开发门槛	代码量大，模块耦合	源码可读，改造成本低
启动时间	分钟级	2 分钟上线
资源占用	高	极低

---

2. 为什么 nanobot 值得学习？

如果你是一名对 AI Agent 感兴趣的开发者、学生或研究者，nanobot 可能是目前最适合入门的开源项目。

2.1 极简架构，一眼看懂核心逻辑

港大团队洞察到一个关键事实：OpenClaw 的本质其实是一个经典的消息处理循环。

while True:
    # 1. 接收输入（用户消息 + 上下文）
    # 2. LLM 分析：回复 or 调用工具
    # 3. 执行动作（工具调用 → 获取结果 → 反馈）
    # 4. 输出响应

这就是 Agent 最核心的 “思考→行动→观察”循环。nanobot 用不到 4000 行代码清晰地实现了这个模式，你不需要在复杂的类继承和接口抽象中迷失，代码结构就像搭积木一样直观。

2.2 麻雀虽小，五脏俱全

尽管代码量极少，nanobot 却实现了生产级 Agent 应有的核心模块：

• Agent Loop：核心循环，管理推理与工具执行的交替
• 工具系统：内置 Shell 执行、文件读写、目录浏览，支持通过装饰器自定义工具
• 记忆管理：跨会话持久化记忆，Agent 能记住之前的交互内容
• 多模型支持：通过 LiteLLM 统一路由，支持 20+ 种 LLM 提供商
• 多渠道接入：Telegram、飞书、钉钉、微信等 9 种渠道
• 定时任务：支持 cron 表达式，定期执行 Agent 指令
• MCP 协议兼容：可直接复用 Claude Desktop 的 MCP Server 配置

2.3 学术界与工业界的新宠

项目上线后反响热烈，三天内在 GitHub 上获得 5000+ 星标，两周突破 19000+ 星标。 为什么这么火？

“开发者厌倦黑盒式的大型框架，想要一个自己能完全看懂并掌控的代码库。对于学术界，一个干净的基座比一个臃肿的产品更适合做实验。而且它证明了构建一个功能强大的 AI Agent 不需要复杂的微服务架构，单体 Python 脚本依然能打。”

---

3. 快速上手：2 分钟拥有你的第一个 Agent

光说不练假把式。让我们动手体验一下 nanobot 的极简部署流程。

3.1 安装

# 使用 pip 直接安装
pip install nanobot-ai

# 或使用 uv 安装（更快）
uv tool install nanobot-ai

3.2 初始化配置

nanobot onboard

这条命令会在 ~/.nanobot/ 目录下生成配置文件模板。

3.3 配置 API Key

编辑 ~/.nanobot/config.json，填入你的 LLM API Key。最快的方式是使用 OpenRouter（一个 Key 可调所有主流模型）：

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

服务商	Purpose	Get API Key
custom	Any OpenAI-compatible endpoint	—
openrouter	LLM (recommended, access to all models)	openrouter.ai
anthropic	LLM (Claude direct)	console.anthropic.com
openai	LLM (GPT direct)	platform.openai.com
deepseek	LLM (DeepSeek direct)	platform.deepseek.com
groq	LLM + Voice transcription (Whisper)	console.groq.com
gemini	LLM (Gemini direct)	aistudio.google.com
minimax	LLM (MiniMax direct)	platform.minimax.io
aihubmix	LLM (API gateway, access to all models)	aihubmix.com
dashscope	LLM (Qwen)	dashscope.console.aliyun.com
moonshot	LLM (Moonshot/Kimi)	platform.moonshot.cn
zhipu	LLM (Zhipu GLM)	open.bigmodel.cn
vllm	LLM (local, any OpenAI-compatible server)	—

3.4 运行你的第一个 Agent

nanobot agent -m "二加二等于几？"

如果一切顺利，你将看到 Agent 返回答案。恭喜！两分钟内你已经拥有了一个可以工作的 AI 助手。

---

4. nanobot 架构初窥

在深入源码之前，我们先从宏观上了解 nanobot 的架构设计。

4.1 整体架构图

下图展示了 nanobot 的核心模块及其关系：

┌─────────────────────────────────────────────────────────────┐
│                        Chat Applications                     │
│  (Telegram / 飞书 / 钉钉 / Slack / Email / QQ / 命令行)      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Gateway (消息路由)                        │
│                     nanobot gateway                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Agent Core                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   Agent Loop                          │    │
│  │  ┌─────────┐    ┌─────────┐    ┌─────────┐         │    │
│  │  │  LLM    │ → │  Tool   │ → │  Memory │         │    │
│  │  │  Call   │    │ Execute │    │  Update │         │    │
│  │  └─────────┘    └─────────┘    └─────────┘         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 Tool System                           │    │
│  │  • Built-in tools (shell, file, dir)                 │    │
│  │  • MCP Servers (filesystem, fetch, etc.)             │    │
│  │  • Custom tools (via @tool decorator)                │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   Memory System                       │    │
│  │  • Short-term (conversation context)                 │    │
│  │  • Long-term (persistent storage)                    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       LLM Providers                           │
│  OpenAI / Anthropic / DeepSeek / Gemini / vLLM / OpenRouter  │
└─────────────────────────────────────────────────────────────┘

4.2 核心模块职责

模块	职责	源码位置（参考）
Agent Loop	核心循环，管理推理与工具执行的交替	agent/loop.py
Tool System	工具注册、发现、执行	agent/tools/
Memory	短期对话上下文与长期记忆存储	agent/memory.py
LLM Client	统一模型调用接口，支持多提供商	llm/
Gateway	多渠道消息路由	gateway/

---

5. 适用场景与未来展望

5.1 nanobot 适合谁？

• 个人开发者：想快速搭建一个自托管的 AI 助手，接入 Telegram 或飞书
• 学生/研究者：想学习 Agent 核心原理，需要一个干净可读的代码库做实验
• 小团队：需要一个轻量级的 Agent 底座，在上面按业务需求快速搭建

5.2 nanobot 能做什么？

• 7×24 小时实时市场分析：定时抓取数据、生成分析报告
• 代码开发助手：理解代码库、协助开发、部署
• 智能日程管理：管理日程、自动执行重复任务
• 个人知识助手：学习你的资料，进行长期记忆和推理

5.3 项目当前状态

目前 nanobot 仍处于 Alpha 阶段，官方明确表示“正在积极开发中，预计会有重大的破坏性变更、架构调整和 API 演进”。 这意味着：

• ✅ 核心功能已可用，适合学习和实验
• ⚠️ 生产环境使用需谨慎，关注版本更新
• 👍 社区活跃，欢迎贡献代码和反馈

---

6. 系列预告

在接下来的文章中，我们将深入 nanobot 的源码，逐一解析每个核心模块的设计与实现：

篇次	标题	核心内容
第 2 篇	俯瞰全局 —— 源码结构与启动流程	目录结构、main 入口、配置加载
第 3 篇	Agent 的大脑 —— 核心循环与消息处理	Agent Loop 实现、事件驱动模型
第 4 篇	万能接口 —— 插件系统设计与实现	工具注册、装饰器原理、MCP 集成
第 5 篇	与 LLM 对话 —— 模型接口封装	LiteLLM 集成、多提供商适配
…	…	…

---

写在最后

nanobot 的出现，让我们看到了 AI Agent 框架的另一种可能 —— 不是越复杂越好，而是越清晰越好。它用 4000 行代码证明：Agent 的核心思想可以很简单，简单到每个开发者都能掌握。

如果你对 AI Agent 的原理感兴趣，不妨从这个项目开始。克隆源码，跑起来，改一改，你会在过程中收获远超预期的理解。

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

下篇预告：我们将深入 nanobot 的源码目录，从 main() 函数开始，追踪一个消息从接收到响应的完整旅程。

---

本文基于 nanobot v0.1.3 版本撰写，实际代码可能随项目迭代有所变化，建议结合最新源码阅读。