Agent Loop（openclaw）

Agentic loop（代理循环）指的是一次代理的完整“真实”运行：输入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将一条消息变成一系列动作与最终回复的权威路径，同时保证会话状态一致。

在 openclaw 中，一个 loop 表示每个会话（session）中一次独立、串行化的运行；当模型思考、调用工具并流式输出时，它会持续发出生命周期事件与流事件。本文档解释这条“真实循环”在端到端上是如何串起来的。

入口点（Entry points）

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

工作方式（高层概览）

1. agent RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 { runId, acceptedAt }。
2. agentCommand 执行 agent：
   • 解析模型与 thinking/verbose 的默认值
   • 加载 skills 快照
   • 调用 runEmbeddedPiAgent（pi-agent-core 运行时）
   • 如果嵌入式循环没有发出 lifecycle end/error，则由它补发 lifecycle end/error
3. runEmbeddedPiAgent：
   • 通过“按会话队列 + 全局队列”对运行进行串行化
   • 解析模型 + auth profile，并构建 pi session
   • 订阅 pi 事件并流式转发 assistant/tool 的增量输出（delta）
   • 强制超时：超过阈值则中止（abort）本次运行
   • 返回 payload 与 usage 元数据
4. subscribeEmbeddedPiSession 将 pi-agent-core 的事件桥接到 openclaw 的 agent stream：
   • tool 事件 => stream: "tool"
   • assistant 的 delta => stream: "assistant"
   • lifecycle 事件 => stream: "lifecycle"（phase: "start" | "end" | "error"）
5. agent.wait 使用 waitForAgentJob：
   • 等待该 runId 的 lifecycle end/error
   • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

排队 + 并发

• 运行会按 session key（会话车道 / session lane）串行化，必要时还会再经过一条全局车道。
• 这能避免 tool/session 的竞态，并保持会话历史一致。
• 消息渠道（messaging channels）可以选择不同的队列模式（collect/steer/followup），它们都会进入这套车道系统。 参见 Command Queue。

Session + workspace 准备

• 解析并创建 workspace；沙箱（sandboxed）运行可能会重定向到一个沙箱 workspace root。
• 加载 skills（或复用某个快照），并注入到 env 与 prompt 中。
• 解析 bootstrap/context 文件，并把它们注入到 system prompt report。
• 获取会话写锁；在开始 streaming 之前打开并准备 SessionManager。

Prompt 组装 + system prompt

• system prompt 由 openclaw 的 base prompt、skills prompt、bootstrap context 以及每次运行的 overrides 组成。
• 会强制执行模型特定的限制与压缩（compaction）预留 token。
• 模型实际看到什么，参见 System prompt。

Hook 点（你可以拦截的位置）

openclaw 有两套 hook 系统：

• Internal hooks（Gateway hooks）：面向命令与生命周期事件的事件驱动脚本。
• Plugin hooks：位于 agent/tool 生命周期与 gateway pipeline 内的扩展点。

Internal hooks（Gateway hooks）

• agent:bootstrap：在 system prompt 最终确定之前、构建 bootstrap 文件时运行。 用于添加/移除 bootstrap context 文件。
• Command hooks：/new、/reset、/stop 以及其他命令事件（见 Hooks 文档）。

配置与示例参见 Hooks。

Plugin hooks（agent + gateway lifecycle）

这些 hook 运行在 agent loop 或 gateway pipeline 内：

• before_agent_start：在运行开始前注入上下文或覆盖 system prompt。
• agent_end：运行完成后检查最终消息列表与运行元数据。
• before_compaction / after_compaction：观察或标注 compaction 周期。
• before_tool_call / after_tool_call：拦截 tool 参数/结果。
• tool_result_persist：在 tool 结果写入会话转录（transcript）之前，同步转换结果。
• message_received / message_sending / message_sent：入站 + 出站消息 hook。
• session_start / session_end：会话生命周期边界。
• gateway_start / gateway_stop：gateway 生命周期事件。

hook API 与注册细节参见 Plugins。

Streaming + 部分回复

• assistant 的 delta 从 pi-agent-core 流式输出，并以 assistant 事件形式发出。
• Block streaming 可以在 text_end 或 message_end 时发出部分回复。
• Reasoning streaming 可以作为独立流输出，或作为 block 回复的一部分输出。
• 分块与 block 回复行为参见 Streaming。

工具执行 + 消息工具（messaging tools）

• tool 的 start/update/end 事件会在 tool stream 上发出。
• tool 结果在记录/发出前会进行大小与图片 payload 的净化（sanitized）。
• messaging tool 的发送会被跟踪，用于抑制重复的 assistant 确认消息。

回复整形 + 抑制

• 最终 payload 由以下内容组装：
  • assistant 文本（以及可选的 reasoning）
  • 内联 tool 摘要（当 verbose 且允许时）
  • 当模型出错时的 assistant 错误文本
• NO_REPLY 会被当作“静默 token”，并从对外 payload 中过滤。
• 最终 payload 列表会移除 messaging tool 产生的重复项。
• 如果最终没有任何可渲染的 payload 且某个 tool 出错，会发出一个兜底的 tool 错误回复 （除非某个 messaging tool 已经发出了用户可见的回复）。

Compaction + 重试

• 自动 compaction 会发出 compaction stream 事件，并可能触发一次重试。
• 重试时会重置内存缓冲区与 tool 摘要，以避免重复输出。
• compaction pipeline 参见 Compaction。

事件流（当前）

• lifecycle：由 subscribeEmbeddedPiSession 发出（兜底时由 agentCommand 发出）
• assistant：来自 pi-agent-core 的 delta 流
• tool：来自 pi-agent-core 的 tool 事件流

聊天渠道处理

• assistant 的 delta 会被缓冲为 chat delta 消息。
• 在 lifecycle end/error 时会发出 chat final。

超时（Timeouts）

• agent.wait 默认：30s（仅等待本身）。可用 timeoutMs 参数覆盖。
• Agent 运行时：agents.defaults.timeoutSeconds 默认 600s；由 runEmbeddedPiAgent 的 abort timer 强制执行。

可能提前结束的情况

• Agent 超时（abort）
• AbortSignal（cancel）
• Gateway 断开或 RPC 超时
• agent.wait 超时（仅等待，不会停止 agent）