Agent Loop（OpenClaw）

Agent Loop 是 Agent 的完整"真实"运行流程：消息入队 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将一条消息转化为行动和最终回复、同时保持会话状态一致性的权威路径。

在 OpenClaw 中，一个 Loop 是每个会话中单次、串行化的运行，在模型思考、调用工具、流式输出过程中持续发出生命周期和流式事件。本文从头到尾解释这个完整流程是如何连接起来的。

入口点

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

工作原理（高层视图）

1. agent RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 { runId, acceptedAt }。
2. agentCommand 运行 Agent：
   • 解析模型 + thinking/verbose 默认值
   • 加载 Skills 快照
   • 调用 runEmbeddedPiAgent（pi-agent-core 运行时）
   • 如果嵌入式 Loop 没有发出生命周期 end/error 事件，则由此层补充发出
3. runEmbeddedPiAgent：
   • 通过每个会话队列 + 全局队列串行化运行
   • 解析模型 + 认证 profile，构建 pi 会话
   • 订阅 pi 事件，流式传输 assistant/tool 增量
   • 强制执行超时 → 超时后终止运行
   • 返回 payload + 用量元数据
4. subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 OpenClaw agent 流：
   • 工具事件 → stream: "tool"
   • Assistant 增量 → stream: "assistant"
   • 生命周期事件 → stream: "lifecycle"（phase: "start" | "end" | "error"）
5. agent.wait 使用 waitForAgentJob：
   • 等待指定 runId 的生命周期 end/error 事件
   • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

队列与并发控制

• 运行按会话 key（会话通道）串行化，可选择通过全局通道。
• 防止工具/会话竞争，保持会话历史的一致性。
• 消息渠道可选择队列模式（collect/steer/followup），这些模式会馈送到通道系统中。参见 命令队列。

会话与工作区准备

• 解析并创建工作区；沙盒化运行可能重定向到沙盒工作区根目录。
• 加载 Skills（或复用快照），注入到环境变量和 prompt 中。
• 解析 Bootstrap/上下文文件，注入到系统 prompt 报告中。
• 获取会话写锁；SessionManager 在流式传输开始前打开并准备好。

Prompt 组装与系统 Prompt

• 系统 prompt 由 OpenClaw 基础 prompt、Skills prompt、Bootstrap 上下文和每次运行的覆盖项组合构建。
• 强制执行模型特定的 token 限制和压缩预留 token。
• 模型看到的完整内容：System prompt。

Hook 点（可拦截的位置）

OpenClaw 有两套 Hook 系统：

• 内部 Hook（Gateway hooks）：事件驱动脚本，响应命令和生命周期事件。
• 插件 Hook：Agent/工具生命周期和 Gateway 管道内部的扩展点。

内部 Hook（Gateway hooks）

• agent:bootstrap：在系统 prompt 最终确定之前、构建 bootstrap 文件时运行。用于添加/删除 bootstrap 上下文文件。
• 命令 Hook：/new、/reset、/stop 等命令事件（参见 Hooks 文档）。

参见 Hooks 了解配置和示例。

插件 Hook（Agent + Gateway 生命周期）

这些 Hook 在 Agent Loop 或 Gateway 管道内运行：

• before_model_resolve：在会话前运行（无 messages），在模型解析之前确定性地覆盖 provider/model。
• before_prompt_build：在会话加载后运行（有 messages），在 prompt 提交前注入 prependContext、systemPrompt、prependSystemContext 或 appendSystemContext。用 prependContext 处理每轮动态文本，用 system-context 字段处理应位于系统 prompt 空间的稳定指导内容。
• before_agent_start：为向后兼容保留的 Hook，可能在两个阶段的任一个中运行；建议优先使用上面的明确 Hook。
• agent_end：在完成后检查最终消息列表和运行元数据。
• before_compaction / after_compaction：观察或标注压缩周期。
• before_tool_call / after_tool_call：拦截工具参数/结果。
• tool_result_persist：同步转换工具结果，在写入会话记录之前生效。
• message_received / message_sending / message_sent：入站 + 出站消息 Hook。
• session_start / session_end：会话生命周期边界。
• gateway_start / gateway_stop：Gateway 生命周期事件。

出站/工具守卫的 Hook 决策规则：

• before_tool_call：{ block: true } 是终止性的，会阻止低优先级处理器。
• before_tool_call：{ block: false } 是空操作，不会清除先前的 block。
• message_sending：{ cancel: true } 是终止性的，会阻止低优先级处理器。
• message_sending：{ cancel: false } 是空操作，不会清除先前的 cancel。

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

流式传输与部分回复

• Assistant 增量从 pi-agent-core 流式传输并作为 assistant 事件发出。
• Block streaming 可以在 text_end 或 message_end 时发出部分回复。
• Reasoning streaming 可以作为独立流或 block replies 发出。
• 分块和 block reply 行为：流式传输。

工具执行与消息工具

• 工具 start/update/end 事件在 tool 流上发出。
• 工具结果在记录/发出前会针对大小和图片 payload 进行清理。
• 消息工具的发送会被追踪，以避免重复的 Assistant 确认。

回复整形与抑制

最终 payload 由以下内容组合而成：

• Assistant 文本（以及可选的 reasoning）

• 内联工具摘要（启用 verbose 且被允许时）

• 模型出错时的 Assistant 错误文本

• NO_REPLY 被视为静默 token，从出站 payload 中过滤掉。

• 消息工具的重复项从最终 payload 列表中删除。

• 如果没有可渲染的 payload 但某个工具出错，则发出回退的工具错误回复（除非消息工具已经向用户发送了可见回复）。

压缩与重试

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

事件流（当前）

• lifecycle：由 subscribeEmbeddedPiSession 发出（agentCommand 也会作为兜底发出）
• assistant：来自 pi-agent-core 的流式增量
• tool：来自 pi-agent-core 的流式工具事件

聊天渠道处理

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

超时

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

可能提前结束的情况

• Agent 超时（abort）
• AbortSignal（取消）
• Gateway 断连或 RPC 超时
• agent.wait 超时（仅影响等待，不停止 Agent 本身）

理解 Agent Loop 的整个生命周期，是排查小龙虾"为什么没有回复"或"工具调用卡住了"等问题的关键所在。