智能体循环（OpenClaw）

智能体循环是智能体的完整"真实"运行：接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态一致。

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

入口点

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

它如何工作（高级别）

1. agent RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 { runId, acceptedAt }。
2. agentCommand 运行智能体：
   • 解析模型 + thinking/verbose 默认值
   • 加载技能快照
   • 调用 runEmbeddedPiAgent（pi-agent-core 运行时）
   • 如果嵌入式循环没有发出，则发出生命周期结束/错误
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：
   • 等待 lifecycle end/error 对应 runId
   • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

队列 + 并发

• 运行按会话键（会话车道）序列化，可选地通过全局车道。
• 这可以防止工具/会话竞态并保持会话历史一致。
• 消息通道可以选择队列模式（收集/引导/跟进），这些模式馈入这个车道系统。 见命令队列。

会话 + 工作区准备

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

提示组装 + 系统提示

• 系统提示从 OpenClaw 的基础提示、技能提示、引导上下文和每次运行覆盖构建。
• 强制执行模型特定限制和压缩保留令牌。
• 见系统提示 了解模型看到的内容。

钩子点（你可以拦截的地方）

OpenClaw 有两个钩子系统：

• 内部钩子（网关钩子）：命令和生命周期事件的事件驱动脚本。
• 插件钩子：智能体/工具生命周期和网关管道内的扩展点。

内部钩子（网关钩子）

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

见钩子 了解设置和示例。

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

这些在智能体循环或网关管道内运行：

• 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：网关生命周期事件。

见插件 了解钩子 API 和注册详情。

流式传输 + 部分回复

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

工具执行 + 消息工具

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

回复塑造 + 抑制

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

压缩 + 重试

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

事件流（当前）

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

聊天通道处理

• 助手增量缓冲到聊天 delta 消息。
• 聊天 final 在 lifecycle end/error 上发出。

超时

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

事情可能提前结束的地方

• 智能体超时（中止）
• 中止信号（取消）
• 网关断开或 RPC 超时
• agent.wait 超时（仅等待，不停止智能体）