Agent Loop

​

Agent 循环（OpenClaw）

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

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

​

入口点

• Gateway 网关 RPC: agent 和 agent.wait。
• CLI: agent 命令。

​

工作原理（高层）

1. agent RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 { runId, acceptedAt }。
2. agentCommand 运行代理：
   • 解析模型 + 思考/详细输出的默认值
   • 加载 Skills 快照
   • 调用 runEmbeddedPiAgent (pi-agent-core runtime)
   • 如果嵌入式循环未发出 lifecycle end/error 事件，则发出该事件
3. runEmbeddedPiAgent：
   • 通过每会话 + 全局队列对运行进行串行化
   • 解析模型 + 身份验证配置文件并构建 pi 会话
   • 订阅 pi 事件并流式传输助手/工具增量
   • 强制执行超时 -> 如果超时则中止运行
   • 返回负载 + 使用情况元数据
4. subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 OpenClaw agent 流：
   • 工具事件 => stream: "tool"
   • 助手增量 => stream: "assistant"
   • 生命周期事件 => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait 使用 waitForAgentJob：
   • 等待 runId 的 lifecycle end/error
   • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

​

排队 + 并发

• 运行按会话密钥（会话通道）以及可选地通过全局通道进行串行化。
• 这可以防止工具/会话竞争，并保持会话历史记录一致。
• 消息传递通道可以选择队列模式（collect/steer/followup）来馈送到此车道系统。 请参阅 Command Queue。

​

会话 + 工作区准备

• 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
• 加载 Skills（或从快照中重用）并将其注入到环境和提示中。
• 解析 Bootstrap/上下文文件并将其注入到系统提示报告中。
• 获取会话写锁；在流式传输之前打开并准备 SessionManager。

​

提示组装 + 系统提示

• 系统提示词由 OpenClaw 的基础提示词、技能提示词、引导上下文和单次运行覆盖项构建而成。
• 强制执行特定于模型的限制和压缩保留令牌。
• 请参阅 System prompt 了解模型看到的内容。

​

挂钩点（您可以拦截的位置）

OpenClaw 有两个钩子系统：

• 内部钩子 (Gateway(网关) 钩子)：用于命令和生命周期事件的事件驱动脚本。
• 插件挂钩：代理/工具生命周期和 Gateway 管道内的扩展点。

​

内部钩子 (Gateway hooks)

• agent:bootstrap：在系统提示词最终确定之前构建引导文件时运行。 使用此挂钩添加/删除引导上下文文件。
• 命令挂钩：/new、/reset、/stop 和其他命令事件（请参阅挂钩文档）。

请参阅 Hooks 了解设置和示例。

​

插件挂钩（代理 + Gateway 生命周期）

这些在代理循环或 Gateway 管道中运行：

• before_model_resolve：在会话前运行（无 messages），以便在模型解析之前确定性地覆盖提供商/模型。
• before_prompt_build：在加载会话后（包含 messages）运行，以便在提交提示词之前注入 prependContext、systemPrompt、prependSystemContext 或 appendSystemContext。使用 prependContext 处理每轮动态文本，并使用系统上下文字段处理应位于系统提示词空间的稳定指导信息。
• before_agent_start：旧版兼容性挂钩，可能在任一阶段运行；优先使用上述显式挂钩。
• agent_end：完成后检查最终消息列表和运行元数据。
• before_compaction / after_compaction：观察或注释压缩周期。
• before_tool_call / after_tool_call：拦截工具参数/结果。
• tool_result_persist：在将工具结果写入会话记录之前，同步转换这些结果。
• message_received / message_sending / message_sent：入站 + 出站消息挂钩。
• session_start / session_end：会话生命周期边界。
• gateway_start / gateway_stop：网关生命周期事件。

出站/工具拦截的 Hook 决策规则：

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

请参阅 Plugin hooks 了解 hook API 和注册详细信息。

​

流式传输 + 部分回复

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

​

工具执行 + 消息传递工具

• 工具开始/更新/结束事件在 tool 流上发出。
• 工具结果在记录/发出之前会针对大小和图像负载进行清理。
• 消息工具发送会被跟踪，以抑制重复的助手确认。

​

回复塑形 + 抑制

• 最终负载由以下部分组装而成：
  • 助手文本（以及可选的推理）
  • 内联工具摘要（当详细模式 + 允许时）
  • 模型出错时的助手错误文本
• NO_REPLY 被视为静默令牌，并从传出负载中过滤掉。
• 消息工具重复项会从最终负载列表中删除。
• 如果没有剩余可渲染的负载且工具出错，则会发出回退工具错误回复 （除非消息工具已发送用户可见的回复）。

​

压缩 + 重试

• 自动压缩会发出 compaction 流事件，并可以触发重试。
• 重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。
• 有关压缩管道，请参阅 Compaction。

​

事件流（目前）

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

​

聊天渠道处理

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

​

超时

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

​

提前结束的情况

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

---

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议 发布。