OpenClaw Agent Loop 教程

Agent Loop 是 OpenClaw 智能体的核心执行闭环，负责将用户输入转化为模型推理、工具执行、流式回复与状态持久化的全流程。它以单会话串行执行为核心原则，保证会话历史一致性、避免状态竞争，是智能体从 "接收消息" 到 "给出最终响应" 的权威执行路径。本文基于官方架构文档，完整拆解 Agent Loop 的执行入口、工作流程、拦截机制、流式输出与异常处理。

一、Agent Loop 核心定义

Agent Loop 是 OpenClaw 智能体的一次完整运行周期，标准流程为：
消息接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 状态持久化。
每个会话同一时间仅运行一个 Loop，全程推送生命周期与流式事件，确保会话状态始终一致。

二、执行入口

Agent Loop 支持两种触发方式，均由 Gateway 统一调度：

1. Gateway RPC 调用

   • agent：异步触发，立即返回 runId 与接受时间，不等待执行完成

   • agent.wait：同步等待，阻塞至 Loop 结束 / 异常 / 超时，返回最终状态

2. CLI 命令

   • 直接执行 openclaw agent 命令，触发本地智能体 Loop 运行

三、高层执行流程

Agent Loop 从触发到结束的完整链路如下：

1. 参数校验与会话解析
   agent RPC 校验入参，定位 sessionKey/sessionId，持久化会话元数据，立即返回 { runId, acceptedAt }。

2. 智能体执行调度
   agentCommand 加载技能快照、解析模型与默认配置，调用 runEmbeddedPiAgent 启动 Pi 嵌入式运行时。

3. 嵌入式运行时执行

   • 按会话 + 全局队列串行执行

   • 解析模型与认证配置，创建 Pi 会话

   • 订阅 Pi 事件，流式推送回复与工具状态

   • 超时强制终止，返回执行结果与用量元数据

4. 事件桥接转发
   subscribeEmbeddedPiSession 将 Pi 底层事件转换为 OpenClaw 标准事件流：

   • 工具事件 → stream: "tool"

   • 回复增量 → stream: "assistant"

   • 生命周期 → stream: "lifecycle"

5. 同步等待结果
   agent.wait 监听 runId 的结束 / 异常事件，返回最终执行状态。

四、队列与并发控制

为避免工具 / 会话竞争、保证历史一致性，Agent Loop 采用严格串行队列机制：

1. 会话级串行：同一 sessionKey 的所有运行任务排队执行，不并发

2. 全局队列（可选）：可配置全局队列，统一管控所有会话的执行顺序

3. 消息队列模式：聊天渠道支持三种队列模式，适配不同交互场景

   • collect：缓存消息，当前 Loop 结束后批量执行

   • followup：缓存消息，当前 Loop 结束后依次执行

   • steer：将消息注入当前 Loop，在下一次模型调用前生效

五、会话与工作区准备

Loop 执行前，系统完成会话与环境初始化：

1. 工作区解析
   定位主工作区；沙箱任务自动重定向至沙箱工作区根目录

2. 技能加载
   加载技能快照并注入环境变量与提示词上下文

3. 引导文件注入
   读取 AGENTS.md/SOUL.md/TOOLS.md 等引导文件，加入系统提示

4. 会话加锁
   获取会话写入锁，初始化 SessionManager，为流式输出做准备

六、提示词组装与系统提示

系统提示词是 Loop 执行的核心指令来源，组装规则：

1. 多层级拼接
   基础提示词 + 技能提示词 + 引导上下文 + 单次运行覆盖配置

2. 模型适配限制
   按模型上下文窗口大小预留压缩令牌，避免溢出

3. 动态注入
   支持通过钩子在提示词构建阶段增删上下文内容

七、拦截钩子：自定义扩展入口

OpenClaw 提供两类钩子，支持在 Loop 全生命周期拦截与修改执行逻辑：

1. 内部钩子（Gateway 钩子）

• agent:bootstrap：系统提示词最终确定前，增删引导上下文文件

• 命令钩子：拦截 /new//reset//stop 等命令事件

2. 插件钩子（智能体 + 网关生命周期）

覆盖 Loop 全阶段，支持拦截、修改、阻断执行：

钩子名称	执行时机	核心用途
before_model_resolve	会话创建前	覆盖模型 / 提供商
before_prompt_build	会话加载后、提示提交前	注入动态上下文、修改系统提示
before_agent_reply	工具执行后、LLM 调用前	拦截回复、返回合成响应
agent_end	执行完成后	查看最终消息与元数据
before_tool_call	工具调用前	阻断 / 修改工具参数
after_tool_call	工具调用后	处理工具结果
message_received	消息接收时	拦截入站消息
message_sending	消息发送前	取消 / 修改出站消息

钩子阻断规则

• before_tool_call/before_install：{ block: true } 终止执行

• message_sending：{ cancel: true } 取消消息发送

• 阻断指令为终态，低优先级钩子不会覆盖阻断结果

八、流式输出与部分回复

Agent Loop 原生支持流式输出，提升交互体验：

1. 增量推送：Pi 运行时的回复增量实时转为 assistant 事件推送

2. 分块发送策略

   • text_end：文本块完成即发送（默认）

   • message_end：整段消息生成完成后发送

3. 推理流分离：思考过程可单独推送，不混入最终回复

4. 分块合并：合并小分块，减少消息投递频次，避免刷屏

九、工具执行与消息工具

1. 工具事件流：工具启动 / 更新 / 结束事件实时推送至 tool 流

2. 结果清洗：工具结果自动裁剪大小、处理图片载荷，避免溢出

3. 消息去重：追踪消息工具发送记录，抑制重复确认回复

十、回复塑形与抑制

最终回复由系统自动组装与清洗：

1. 内容来源
   助手文本 + 推理内容 + 工具摘要（开启 verbose 时）+ 错误信息

2. 静默指令过滤
   自动过滤 NO_REPLY/no_reply 静默令牌，不发送空回复

3. 异常兜底
   无有效内容且工具异常时，自动发送工具错误兜底提示

十一、压缩与重试

1. 自动压缩
   上下文溢出时触发压缩，推送 compaction 事件，可自动重试 Loop

2. 重试重置
   重试时清空内存缓存与工具摘要，避免重复输出

3. 压缩观察
   通过 before_compaction/after_compaction 钩子监听压缩周期

十二、标准事件流

Loop 执行过程中推送三类核心事件，供客户端监听：

1. lifecycle：生命周期事件（start/end/error）

2. assistant：回复增量流式事件

3. tool：工具执行状态事件

十三、聊天渠道处理

1. 增量缓冲：助手增量内容缓冲为聊天 delta 消息

2. 最终消息：生命周期结束 / 异常时推送 final 最终消息

3. 渠道适配：按渠道特性自动调整分块大小与发送策略

十四、超时机制

Agent Loop 支持多层级超时控制，避免无限阻塞：

1. agent.wait 等待超时：默认 30s，仅等待不终止 Loop

2. 智能体运行超时：默认 48 小时，超时强制终止 Loop

3. LLM 空闲超时：无增量返回时自动终止，默认 120s；本地模型可调大或关闭

4. 定时任务例外：Cron 触发的任务关闭空闲监听，依赖外层超时

十五、提前终止场景

Loop 可能在以下情况提前结束：

1. 智能体执行超时（强制 abort）

2. 接收到 AbortSignal 取消指令

3. Gateway 断开连接或 RPC 超时

4. agent.wait 等待超时（仅停止等待，不终止 Loop）

十六、总结

Agent Loop 是 OpenClaw 智能体的执行引擎核心，以串行队列保障会话一致性、以钩子系统支持高度定制、以流式输出提升交互体验、以超时与压缩机制保证稳定运行。无论是客户端 RPC 调用、CLI 执行还是定时任务触发，所有智能体行为均遵循这套统一的执行闭环，是 OpenClaw 实现可靠、可控、可扩展智能体能力的底层基础。