English | 中文 | 日本語

claw0

从零到一：构建 AI Agent 网关

10 个循序渐进的章节 —— 每一章都是一个独立、可运行的 Python 文件。 3 种语言（英语、中文、日语）—— 代码与文档同步更新。

---

这是什么？

大多数 Agent 教程止步于“调用一次 API”。本仓库从那个 while 循环出发，带你一步步构建出一个生产级别的 Agent 网关。

我们将从零开始，分章节构建一个最小化的 AI Agent 网关。共 10 个章节，涵盖 10 个核心概念，约 7,000 行 Python 代码。每一章只引入一个新概念，并完整保留之前的所有代码。学完这 10 章后，你将能够自信地阅读 OpenClaw 的生产级源码。

s01: Agent Loop           -- 基础：while 循环 + stop_reason
s02: Tool Use             -- 工具调用：让模型使用工具，使用分发表（dispatch table）
s03: Sessions & Context   -- 会话与上下文：持久化对话，处理溢出
s04: Channels             -- 渠道：Telegram + 飞书，真正的渠道管道
s05: Gateway & Routing    -- 网关与路由：5 层绑定，会话隔离
s06: Intelligence         -- 智能：灵魂、记忆、技能与提示词组装
s07: Heartbeat & Cron     -- 心跳与定时任务：主动型 Agent + 计划任务
s08: Delivery             -- 交付：带退避机制的可靠消息队列
s09: Resilience           -- 韧性：3 层重试机制 + 认证配置轮询
s10: Concurrency          -- 并发：命名通道（Named lanes）解决混乱

架构

+------------------- claw0 layers -------------------+
|                                                     |
|  s10: Concurrency  (命名通道, 生成跟踪)            |
|  s09: Resilience   (认证轮询, 溢出压缩)            |
|  s08: Delivery     (预写式队列, 退避机制)          |
|  s07: Heartbeat    (通道锁, 定时调度器)            |
|  s06: Intelligence (8 层提示词, 混合记忆)          |
|  s05: Gateway      (WebSocket, 5 层路由)           |
|  s04: Channels     (Telegram 管道, 飞书 Hook)      |
|  s03: Sessions     (JSONL 持久化, 3 阶段重试)      |
|  s02: Tools        (分发表, 4 种工具)              |
|  s01: Agent Loop   (while True + stop_reason)      |
|                                                     |
+-----------------------------------------------------+

章节依赖关系

s01 --> s02 --> s03 --> s04 --> s05
                 |               |
                 v               v
                s06 ----------> s07 --> s08
                 |               |
                 v               v
                s09 ----------> s10

• s01-s02: 基础（无依赖）
• s03: 基于 s02 构建（为工具循环添加持久化）
• s04: 基于 s03 构建（渠道为会话生成 InboundMessages）
• s05: 基于 s04 构建（将渠道消息路由至 Agent）
• s06: 基于 s03 构建（利用会话处理上下文，添加提示词层级）
• s07: 基于 s06 构建（心跳机制利用灵魂/记忆进行提示词组装）
• s08: 基于 s07 构建（心跳输出流经交付队列）
• s09: 基于 s03+s06 构建（重用 ContextGuard 处理溢出和模型配置）
• s10: 基于 s07 构建（使用命名通道系统替代单一锁）

快速开始

# 1. 克隆并进入目录
git clone https://github.com/shareAI-lab/claw0.git && cd claw0

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件：设置 ANTHROPIC_API_KEY 和 MODEL_ID

# 4. 运行任意章节（选择你熟悉的语言）
python sessions/en/s01_agent_loop.py    # 英语
python sessions/zh/s01_agent_loop.py    # 中文
python sessions/ja/s01_agent_loop.py    # 日语

学习路径

每一章恰好引入一个新概念，之前所有的代码保持不变：

第一阶段：基础          第二阶段：连接            第三阶段：大脑         第四阶段：自主性       第五阶段：生产环境
+----------------+      +-------------------+     +-----------------+   +-----------------+   +-----------------+
| s01: 循环      |      | s03: 会话         |     | s06: 智能       |  | s07: 心跳       |   | s09: 韧性       |
| s02: 工具      | ---> | s04: 渠道         | --> |   灵魂、记忆、  | ->|   & 定时任务    |-->|   & 并发        |
|                |      | s05: 网关         |     |   技能、提示词  |  | s08: 交付       |   | s10: 通道       |
+----------------+      +-------------------+     +-----------------+   +-----------------+   +-----------------+
 while + 分发          持久化 + 路由            个性化 + 回忆        主动性 + 可靠性      重试 + 序列化

章节详情

#	章节	核心概念	代码行数
01	Agent Loop	while True + stop_reason -- 这就是 Agent	~175
02	Tool Use	工具 = Schema 字典 + 处理程序映射。模型指定名称，你负责查询执行	~445
03	Sessions	JSONL: 追加写入，读取时重放。如果太长？汇总旧片段	~890
04	Channels	每个平台各不相同，但它们最终都会产生统一的 InboundMessage	~780
05	Gateway	绑定表将（渠道，对端）映射到对应的 Agent。匹配度最高者胜出	~625
06	Intelligence	系统提示词分层与记忆管理	-