OpenClaw系列第7课：Agent Loop 解析 - 每条消息是怎么被处理的

这是「OpenClaw 教程课程」第 7 课。
前一课我们讲清楚了 Session，这一课继续往前走一步：一条消息在 OpenClaw 里到底是怎么被处理的？

图：Agent Loop 是 OpenClaw 里“消息变成动作和回复”的完整运行路径。

很多人第一次接触 OpenClaw 时，天然会用一种聊天产品的直觉去理解它：

  • 我发一句话
  • 模型想一下
  • 它回一句话

这套理解在普通聊天产品里勉强够用，但放到 OpenClaw 里就太浅了。

因为在 OpenClaw 里，一条消息真正经历的过程通常是：

  • 进入 Gateway
  • 找到对应 Session
  • 组装上下文
  • 解析系统提示词
  • 调模型
  • 模型决定是否调用工具
  • 工具执行
  • 结果回流
  • 流式输出
  • 持久化状态

这一整条链，OpenClaw 里有一个专门的名字：

Agent Loop

今天这课，我们就把它拆开讲清楚。

一、什么是 Agent Loop？

先给一个最简定义：

Agent Loop 是一次完整的 Agent 运行过程。

文档里的核心意思非常明确：

它不是“模型回了一句话”这么简单，而是一次真实的、完整的运行周期：

intake → context assembly → model inference → tool execution → streaming replies → persistence

翻成更好懂的话，就是：

  1. 接收输入
  2. 组装上下文
  3. 模型推理
  4. 工具执行
  5. 流式输出
  6. 结果和状态更新

所以以后你不要再把一次交互只理解成“发消息 → 得回答”。

更准确的理解应该是：

你发出去的是一条消息，但系统内部跑起来的是一轮 Agent Loop。

二、为什么 OpenClaw 必须有 Agent Loop？

因为 OpenClaw 不是纯聊天模型，而是一个真正能处理工具、状态和上下文的运行系统。

如果没有 Agent Loop，这些能力几乎不可能稳定协同：

  • Session 怎么接住这条消息？
  • 模型看见的上下文从哪来？
  • 工具调用什么时候触发？
  • 流式输出怎么组织？
  • 最终状态写回哪里？

也就是说，Agent Loop 的作用并不是“让流程更复杂”，而是：

把一次真实交互所需要的全部阶段组织成一条可运行、可观察、可持续化的链路。

三、一条消息进入 OpenClaw 后，第一步发生了什么？

你可以先把入口理解成两种常见来源：

  • Gateway RPC 里的 agent / agent.wait
  • CLI 发起的 agent 命令

对大多数普通用户来说，虽然你表面上是在 Telegram、Discord、Dashboard 里发消息，但在更底层，它最终都会进入这类统一的 Agent 处理入口。

这意味着：

不同聊天入口，最终会汇入同一套 Agent Loop。

这就是为什么 OpenClaw 能保持一致行为。

四、Agent Loop 的高层流程，到底长什么样？

先给你一个最值得记住的简化版：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
用户消息进入系统
        ↓
定位 Session
        ↓
组装上下文和系统提示
        ↓
进入模型推理
        ↓
如有需要，调用工具
        ↓
工具结果回流给模型
        ↓
生成最终回复
        ↓
流式输出 / 最终输出
        ↓
写入状态与记录

图：从用户消息进入，到最终回复发出，OpenClaw 跑的是一整轮 Agent Loop，而不是一次单点“模型回答”。

如果你想更专业一点地看，它其实包含几个关键层次：

  • 接入层：消息进系统
  • 准备层：Session、上下文、提示词
  • 推理层：模型思考
  • 执行层：工具调用
  • 输出层：流式回复和最终回复
  • 持久化层：记录和状态保存

五、为什么 Session 会在 Agent Loop 里这么重要？

因为 Agent Loop 并不是对“裸消息”直接处理。

它处理的是：

某个 Session 中的一次新输入。

这意味着在真正开始模型推理之前，系统要先知道：

  • 这条消息属于哪个 Session
  • 当前 Session 里已经有什么历史
  • 这次应该继承哪些上下文
  • 会不会触发新的会话边界

所以 Session 不是独立存在的概念，它和 Agent Loop 是强绑定的。

换句话说：

Session 负责决定“这次对话站在哪个上下文里”，Agent Loop 负责决定“在这个上下文里怎么跑完整个过程”。

六、上下文组装到底是在干什么？

这是很多新手最容易忽略的一段。

你以为模型只是“看你刚发的那句话”，其实不是。

在进入推理前，OpenClaw 会做大量准备工作，比如：

  • 读取 Session 里的历史对话
  • 装配系统提示词
  • 加载技能（skills）相关上下文
  • 引入 bootstrap / 工作区上下文
  • 应用模型和运行时设置

也就是说，模型真正“看见”的，不是你眼前输入框里的那一句，而是：

一整份经过系统拼装过的上下文包。

这也是为什么你经常会觉得：

  • 它好像知道前面发生了什么
  • 它好像带着某种风格或角色设定在说话
  • 它有时候能直接接着前面工具执行的结果往下说

这些都不是巧合，而是上下文组装的结果。

七、模型推理只是 Agent Loop 的中段，不是全部

很多人天然会把“模型推理”当成整件事的主体。

其实在 OpenClaw 里，模型推理只是 Agent Loop 的一个阶段。

它负责的是：

  • 理解当前输入
  • 结合上下文做判断
  • 生成文本
  • 决定是否调用工具

但它并不负责：

  • 直接执行工具
  • 管理会话状态
  • 保存结果
  • 控制整个生命周期

所以你以后看到 Agent Loop，不要只把注意力放在模型上。

更完整的理解应该是：

模型是 Agent Loop 里的“大脑阶段”，但不是整个系统本身。

八、工具调用在 Agent Loop 里是怎么发生的？

这是 OpenClaw 和普通聊天 AI 差异最大的地方之一。

在 Agent Loop 里，模型不会自己直接去执行命令、读文件、开浏览器。

模型做的是：

  • 判断现在要不要调工具
  • 说明该调哪个工具
  • 提供参数或意图

然后真正执行这些事情的，是 OpenClaw 的工具层。

也就是说，流程是：

第一步：模型判断需要工具

第二步：发出工具调用请求

第三步：OpenClaw 执行工具

第四步：工具结果回流到当前这轮 Agent Loop

第五步：模型继续基于工具结果生成输出

所以你看到的是“AI 会用工具”，本质上其实是：

Agent Loop 把模型推理和工具执行组织成了一个可往返的过程。

图：模型并不直接执行工具，而是在 Agent Loop 中由系统接管工具调用，再把结果回流给模型继续处理。

九、为什么 OpenClaw 会流式输出？

文档里明确提到，Agent Loop 会处理 streaming replies。

这意味着很多时候你看到的不是“憋半天，一次性吐一大段”，而是：

  • 它可以一边生成一边输出
  • 工具事件也可以被流式呈现
  • 整个生命周期中会有不同 stream

这就解释了为什么有时候你在 UI 里会看到：

  • 文本一点点出现
  • 工具过程被展示出来
  • 生命周期状态有开始、结束、错误这些阶段

这不是额外 UI 花样，而是因为 Agent Loop 本身就是按流处理的。

十、为什么 Agent Loop 强调“单 Session 串行”？

当前文档里有一个非常关键的点：

同一个 Session 内的运行是串行化的。

这意味着：

  • 同一个 Session 不会同时乱跑多轮互相抢状态
  • 可以避免工具调用和会话写入打架
  • 能保持历史一致性

这点特别重要。

因为如果一个 Session 里允许多轮完全并发乱跑，结果很容易出现：

  • 工具结果串台
  • 状态写入覆盖
  • 回复顺序混乱
  • Session 历史失真

所以你可以把这个机制理解成：

Agent Loop 在每个 Session 里都像一条排队运行的单车道。

十一、Agent Loop 结束后，为什么还要“持久化”？

因为如果一轮运行结束后什么都不保存，那下一轮就无法正确延续。

所以在 Agent Loop 最后，系统通常还会做：

  • 写入消息记录
  • 保存工具结果摘要或相关信息
  • 更新 Session 状态
  • 为下一轮继续运行做准备

这一步非常关键，因为它决定了：

  • 下次还能不能接上
  • /new 前后的边界如何体现
  • 日后回看记录时有没有依据

所以你要把“持久化”理解成：

Agent Loop 不是回答完就结束，而是还要把这一轮运行的后果写回系统。

十二、为什么理解 Agent Loop 后，很多现象 suddenly 就解释通了？

因为很多你之前觉得“它怎么这样”的地方，其实都是 Agent Loop 的自然结果。

比如：

现象 1：为什么它不是立刻回复，而是像经历了一串步骤？

因为它真的经历了一串步骤。

现象 2：为什么有时能看到工具过程？

因为工具事件本来就在 Agent Loop 的流里。

现象 3：为什么同一个 Session 里不会无限乱并发？

因为它按 Session 串行化。

现象 4：为什么上下文和系统提示会明显影响回答？

因为模型看到的是“组装后的上下文”，不是你眼前那一句裸消息。

所以理解 Agent Loop 的价值在于：

你开始真正从系统视角理解 OpenClaw，而不是只从聊天窗口视角理解它。

十三、这节课最重要的一句话

如果你今天只记一句话，那我建议你记这句：

Agent Loop 是 OpenClaw 把“一条消息”变成“一次完整可执行运行”的全过程。

它不是聊天的装饰层，而是消息处理的真实主干。

十四、总结

这节课你只要真正记住下面 5 句话，就已经够用了：

  1. Agent Loop 不是单纯模型回复，而是一整轮完整运行。
  2. 它包含消息进入、上下文组装、模型推理、工具执行、流式输出和状态持久化。
  3. Session 决定上下文归属，Agent Loop 决定这轮处理怎么跑。
  4. 模型会决定是否调用工具，但真正执行工具的是系统工具层。
  5. 理解 Agent Loop，才能真正理解 OpenClaw 为什么不像普通聊天 AI。

下一课预告

下一课我们会学：

第 8 课：Context Engine——模型“看到了什么”

也就是继续往 Agent Loop 的内部再走一步：

  • 模型到底看到了哪些信息
  • 系统提示词怎么拼出来
  • bootstrap、skills、session 历史是怎么共同作用的

🦞 本文由八条撰写，持续更新中。