Agent 系统性学习

claw0：从零构建 AI Agent 网关

12 min read

claw0: 从零到一构建 AI Agent 网关

shareAI-lab 出品的 10 章渐进式 Agent 网关教程，约 7000 行 Python，支持中/英/日三种语言。与 learn-claude-code 组成姊妹教程——一个关注 Agent Harness 内核（循环、规划、团队、隔离），一个关注网关路由与主动行为（心跳、Cron、IM 通道、记忆、Soul）。

一句话摘要

从 while True 循环出发，逐层叠加工具调用 → 会话持久化 → 多通道接入 → 网关路由 → 智能层（8 层提示词 + 记忆）→ 心跳 + Cron → 可靠投递 → 弹性重试 → 并发序列化。学完全部 10 节，可以直接阅读 OpenClaw 的生产代码。

五阶段学习路径

每节只引入一个核心概念，前一节的代码原样保留。这种”不改旧代码、只叠新逻辑”的方式让每一步的增量都清晰可见。

阶段章节核心概念代码量
基础s01 Agent Loopwhile True + stop_reason——这就是一个 Agent，不需要框架~175 行
s02 Tool Use工具 = schema dict + handler map。模型选名字，你查表执行~445 行
连接s03 SessionsJSONL 持久化：写入追加，读取重放。太大了就总结旧消息~890 行
s04 ChannelsTelegram / 飞书等平台实现不同，但最终都产出同一个 InboundMessage~780 行
s05 Gateway5 级绑定表将 (channel, peer) 映射到 Agent，最具体的匹配胜出~625 行
智能s06 Intelligence8 层提示词（系统 → 身份 → 工具 → 记忆 → 技能 → 心跳 → 用户 → 摘要）+ 混合记忆检索~750 行
自治s07 Heartbeat定时线程 + Cron 调度。Agent 从被动（等人发消息）变成主动（自检 + 定时任务）~660 行
s08 Delivery预写投递：先写磁盘再发消息，崩溃也不丢。附带退避机制~870 行
生产s09 Resilience3 层重试洋葱：认证轮换 → 溢出压缩 → 工具循环重试~1130 行
s10 Concurrency命名车道 + FIFO 队列 + generation 追踪。同车道不乱序，跨车道真并发~900 行

章节依赖关系

s01 → s02 → s03 → s04 → s05
                |         |
                v         v
               s06 ──→ s07 → s08
                |         |
                v         v
               s09 ──→ s10
  • s01-s02：基础，无依赖
  • s03：基于 s02，为工具循环添加持久化
  • s04：基于 s03，通道产出 InboundMessage 给会话
  • s05：基于 s04，将通道消息路由到 Agent
  • s06：基于 s03，使用会话做上下文，叠加提示词层
  • s07：基于 s06，心跳使用 Soul + 记忆构建提示词
  • s08：基于 s07，心跳输出经由投递队列
  • s09：基于 s03+s06，复用 ContextGuard 做溢出层和模型配置
  • s10：基于 s07，将单一 Lock 替换为命名车道系统

依赖图揭示了一个重要事实：s06（Intelligence）是整个架构的分水岭。 从 s06 开始，Agent 不再只是一个”循环 + 工具”的骨架，而是有了人格、记忆和上下文组装能力——这恰好对应了 Harness工程 中”Harness 的核心是对上下文的精确控制”这一命题。

各阶段深入

阶段一：基础——比想象中更少的代码就能跑起来

s01 只有约 175 行 Python，核心就是一个 while True 循环 + stop_reason 判断。很多 Agent 教程在介绍概念之前先让你装框架——claw0 的思路相反：先让你看到最裸的 Agent Loop 长什么样，然后每一节只加一个新东西。Agent 概念笔记中讨论的”Agent 的本质是循环”在这里得到了最直接的代码演示。

s02 引入工具调用。设计极简：工具 = schema dict（定义给模型看）+ handler map（定义给程序执行）。模型从 schema 中选了哪个工具名字，程序就查表调用对应的 handler。不需要 MCP 协议、不需要工具注册中心。这一点与 pi-coding-agent 的 4 工具设计思路一致——工具是查表分发，不是框架功能。

阶段二：连接——让 Agent 活在你的日常聊天软件里

s03 用 JSONL 格式做会话持久化——追加写、顺序读，简单到不需要任何数据库依赖。溢出处理也很直接：消息太多？把旧消息发给模型做一次总结，用摘要替代原文。这是 上下文工程 中”上下文压缩”的基础形态。

s04 引入了一个关键的抽象——通道（Channel）。Telegram 的长轮询管线和飞书的 Webhook 回调实现完全不同，但它们最终都产出同一个数据结构 InboundMessage。网关的下游代码完全不关心消息是从哪个平台来的。这种”统一入站消息”的设计是 claw0 架构中最优雅的抽象之一。

s05 的网关路由机制用了一张绑定表（Binding Table），支持 5 级路由精度：从”一个 Agent 处理所有”到”每个用户有自己的 Agent”。规则是最具体的匹配优先（/channel/account/peer），找不到匹配则依次回退——最终保证每条消息一定有一个 Agent 来处理。

阶段三：智能——8 层提示词的组装艺术

s06 是整个教程最核心的章节。它把 System Prompt 拆成了 8 层，在每次对话开始前按规则逐层组装：

  1. System：全局规则（永远不变的底座）
  2. Identity：Agent 的身份定义（Soul）
  3. Tools：当前可用的工具列表
  4. Memory：从记忆库中检索出的相关记忆
  5. Skills：已安装的 Skill 说明
  6. Heartbeat：心跳/定时任务的指令
  7. User：用户自定义的偏好和规则
  8. Summary：对话历史的摘要

这种分层设计的关键好处是：换文件就换人格，不需要改代码。 要换一个 Agent 的性格？替换 IDENTITY.md。要加新记忆？写进 MEMORY.md。这与 [Agent Skill](Agent Skill.md) 的设计理念完全一致——能力是文件，不是代码。

记忆检索采用混合策略：语义搜索（向量相似度）+ 全文搜索（关键词匹配），两者结果取并集。既不会漏掉语义相关的记忆，也不会错过精确的关键词命中。

阶段四：自治——Agent 不再等你

s07 和 s08 让 Agent 从一个”等人@它”的被动工具变成”自己会动”的主动服务。

s07 Heartbeat 的核心是一个定时线程，每 N 秒问自己一个问题：“有没有什么该做的事？” 该做的事通过 Cron 表达式和心跳提示词定义。心跳产出的消息和用户消息走完全相同的管线——网关不区分”主动触发”和”被动响应”，统一路由到同一个 Agent。

s08 Delivery 解决了”消息发出去了但对面没收到”的问题。方案是预写投递（Write-Ahead Delivery）：先把消息写入磁盘（JSONL），再尝试发送。如果在发送过程中崩溃，重启后从磁盘重新加载队列，继续发送。附带指数退避——发送失败后不等长间隔重试，越失败等越久，避免打爆下游。

阶段五：生产——三层洋葱和命名车道

s09 Resilience 是”让网关扛得住真实世界”的最后一层。3 层重试洋葱（从外到内）：

  1. 认证轮换：API Key 过期或限流？自动切换到下一个 Key
  2. 溢出压缩：上下文超过模型窗口？自动触发总结压缩，腾出空间
  3. 工具循环：工具调用失败了？捕获异常、告知模型、让它重新选择工具

每层独立，不会互相干扰——认证问题不会触发上下文压缩，工具失败不会去换 API Key。

s10 Concurrency 解决多用户并发的终极问题。方案是命名车道（Named Lanes）：每个用户分配一条车道（Lane），车道内部是 FIFO 队列——同车道的消息严格有序处理，不同车道之间真并发。这保证了两个用户同时发消息不会串，同一用户的两条消息不会乱序。逻辑从简单的”一把全局 Lock”演进到命名车道系统，性能随用户数线性扩展。

与 learn-claude-code 的姊妹关系

claw0 和 learn-claude-code（LCC）是 shareAI-lab 刻意设计的一对互补教程：

维度claw0learn-claude-code
核心关注网关路由 + 主动行为Agent Harness 内核
架构层次网关层（Gateway）执行层（Harness）
关键机制心跳、Cron、IM 通道、记忆、Soul循环、规划、团队、worktree 隔离、三层 compact
Agent 角色常驻服务（daemon）单次任务执行器
产物一个可以跑在群聊里的 Agent一个可复现的编程 Agent 框架

两个教程一起学，覆盖了 Harness工程 和 三层架构（Gateway → Harness → Sandbox）的上两层——网关层和执行层。sandbox（隔离层）在 LCC 的 worktree 隔离中有所涉及，但尚未独立成章。

技术环境

前置要求：Python 3.11+、Anthropic API Key（或兼容服务商）

关键依赖：anthropic（模型调用）、websockets（实时通道）、croniter（Cron 解析）、python-telegram-bot（Telegram 接入）、httpx（HTTP 客户端）

仓库结构：每个语言文件夹自包含——sessions/{en,zh,ja}/ 下各自 10 个 .py + 10 个 .md，代码逻辑跨语言一致，注释和文档因语言而异。

重要引用

“逐章节构建一个最小化 AI Agent 网关。10 个章节，10 个核心概念，约 7,000 行 Python。”

“每节只引入一个新概念，前一节的代码原样保留。”

“大多数 Agent 教程停在’调一次 API’就结束了。这个仓库从那个 while 循环开始，一路带你到生产级网关。”

Graph View

Backlinks