Agent Loop (OpenClaw)

Agent 循环是 Agent 完整的”真实”运行过程：接收输入 → 组装上下文 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为操作和最终回复的权威路径，同时保持 Session 状态一致。

在 OpenClaw 中，循环是每个 Session 的单次序列化运行，会在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个完整循环是如何端到端连接的。

入口点

  • Gateway RPC：agent 和 agent.wait。
  • CLI：agent 命令。

工作原理（高层视角）

  1. agent RPC 验证参数，解析 Session（sessionKey/sessionId），持久化 Session 元数据，立即返回 { runId, acceptedAt }。
  2. agentCommand 运行 Agent：
    • 解析模型 + thinking/verbose 默认值
    • 加载 Skill 快照
    • 调用 runEmbeddedPiAgent（pi-agent-core Runtime）
    • 如果嵌入式循环没有发出生命周期结束/错误事件，则发出该事件
  3. runEmbeddedPiAgent：
    • 通过每个 Session 队列 + 全局队列序列化运行
    • 解析模型 + 认证配置并构建 pi Session
    • 订阅 pi 事件并流式传输 assistant/tool 增量
    • 强制执行超时 → 超时后中止运行
    • 返回负载 + 使用元数据
  4. subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 OpenClaw agent 流：
    • tool 事件 => stream: "tool"
    • assistant 增量 => stream: "assistant"
    • 生命周期事件 => stream: "lifecycle"（phase: "start" | "end" | "error"）
  5. agent.wait 使用 waitForAgentJob：
    • 等待 runId 的生命周期结束/错误事件
    • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

队列 + 并发

  • 运行按 Session key（Session 通道）序列化，可选通过全局通道。
  • 这可以防止工具/Session 竞争，保持 Session 历史一致。
  • 消息 Channel 可以选择队列模式（collect/steer/followup）来配合这个通道系统。 参见 Command Queue。

Session + Workspace 准备

  • Workspace 被解析和创建；沙箱运行可能会重定向到沙箱 Workspace 根目录。
  • Skill 被加载（或从快照重用）并注入到环境和 Prompt 中。
  • Bootstrap/Context 文件被解析并注入到系统 Prompt 报告中。
  • 获取 Session 写锁；在流式传输前打开并准备 SessionManager。

Prompt 组装 + 系统 Prompt

  • 系统 Prompt 由 OpenClaw 的基础 Prompt、Skill Prompt、Bootstrap Context 和每次运行的覆盖组成。
  • 强制执行模型特定的限制和 Compaction 保留 Token。
  • 参见 System prompt 了解模型看到的内容。

Hook 点（你可以拦截的地方）

OpenClaw 有两个 Hook 系统：

  • Internal hooks（Gateway hooks）：用于命令和生命周期事件的事件驱动脚本。
  • Plugin hooks：Agent/工具生命周期和 Gateway 管道内的扩展点。

Internal hooks（Gateway hooks）

  • agent:bootstrap：在系统 Prompt 最终确定之前构建 Bootstrap 文件时运行。 用它来添加/删除 Bootstrap Context 文件。
  • Command hooks：/new、/reset、/stop 和其他命令事件（参见 Hooks 文档）。

参见 Hooks 了解设置和示例。

Plugin hooks（Agent + Gateway 生命周期）

这些在 Agent 循环或 Gateway 管道内运行：

  • before_agent_start：在运行开始前注入 Context 或覆盖系统 Prompt。
  • agent_end：在完成后检查最终消息列表和运行元数据。
  • before_compaction / after_compaction：观察或注释 Compaction 周期。
  • before_tool_call / after_tool_call：拦截工具参数/结果。
  • tool_result_persist：在工具结果写入 Session 记录前同步转换它们。
  • message_received / message_sending / message_sent：入站 + 出站消息 Hook。
  • session_start / session_end：Session 生命周期边界。
  • gateway_start / gateway_stop：Gateway 生命周期事件。

参见 Plugins 了解 Hook API 和注册详情。

Streaming + 部分回复

  • Assistant 增量从 pi-agent-core 流式传输并作为 assistant 事件发出。
  • 块 Streaming 可以在 text_end 或 message_end 时发出部分回复。
  • 推理 Streaming 可以作为单独的流或块回复发出。
  • 参见 Streaming 了解分块和块回复行为。

工具执行 + 消息工具

  • 工具 start/update/end 事件在 tool 流上发出。
  • 工具结果在记录/发出前会对大小和图像负载进行清理。
  • 消息工具发送被跟踪以抑制重复的 assistant 确认。

回复塑形 + 抑制

  • 最终负载由以下内容组装：
    • assistant 文本（和可选的推理）
    • 内联工具摘要（当 verbose + 允许时）
    • 模型错误时的 assistant 错误文本
  • NO_REPLY 被视为静默 Token 并从传出负载中过滤。
  • 消息工具重复项从最终负载列表中删除。
  • 如果没有可渲染的负载且工具出错，会发出回退工具错误回复 （除非消息工具已经发送了用户可见的回复）。

Compaction + 重试

  • 自动 Compaction 发出 compaction 流事件并可以触发重试。
  • 重试时，内存缓冲区和工具摘要会重置以避免重复输出。
  • 参见 Compaction 了解 Compaction 管道。

事件流（当前）

  • lifecycle：由 subscribeEmbeddedPiSession 发出（以及作为 agentCommand 的回退）
  • assistant：从 pi-agent-core 流式传输的增量
  • tool：从 pi-agent-core 流式传输的工具事件

Chat Channel 处理

  • Assistant 增量被缓冲到聊天 delta 消息中。
  • 在生命周期结束/错误时发出聊天 final。

超时

  • agent.wait 默认：30 秒（仅等待）。timeoutMs 参数可覆盖。
  • Agent Runtime：agents.defaults.timeoutSeconds 默认 600 秒；在 runEmbeddedPiAgent 中止计时器中强制执行。

可能提前结束的地方

  • Agent 超时（中止）
  • AbortSignal（取消）
  • Gateway 断开连接或 RPC 超时
  • agent.wait 超时（仅等待，不会停止 Agent）