代理循环
代理循环生命周期、流和等待语义
代理循环是代理的完整"真实"运行：摄入→上下文组装→模型推理→
工具执行→流式回复→持久化。这是传递消息的权威路径
转化为操作和最终答复，同时保持会话状态一致。
在 OpenClaw 中，循环是每个会话的单个序列化运行，它发出生命周期和流事件
正如模型所思考的那样，调用工具并流输出。该文档解释了真实的循环是如何进行的
端到端有线连接。
入口点
- 网关 RPC：''agent'' 和 ''agent.wait''。
- CLI：''agent'' 命令。
它是如何工作的（高级）
1. ''agent'' RPC 验证参数，解析会话（sessionKey/sessionId），保存会话元数据，立即返回 ''{ runId, acceptedAt }''。
2. ''agentCommand'' 运行代理：
- 解决模型+思考/详细默认值
- 加载技能快照
- 调用 ''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''：
- 等待 ''runId'' 的''生命周期结束/错误''
- 返回 ''{ status: ok|error|timeout, startedAt, endedAt, error? }''
队列+并发
- 运行按会话密钥（会话通道）进行序列化，并且可以选择通过全局通道进行序列化。
- 这可以防止工具/会话竞争并保持会话历史记录一致。
- 消息传递通道可以选择为该通道系统提供数据的队列模式（收集/引导/跟进）。
请参阅''命令队列''。
会议 + 工作区准备
- 工作空间被解析并创建；沙盒运行可能会重定向到沙盒工作空间根目录。
- 技能被加载（或从快照中重用）并注入到环境和提示中。
- 引导程序/上下文文件被解析并注入到系统提示报告中。
- 获取会话写锁； ''SessionManager'' 在流式传输之前打开并准备好。
提示汇编+系统提示
钩子点（可以拦截的地方）
OpenClaw 有两个钩子系统：
- 内部挂钩（网关挂钩）：用于命令和生命周期事件的事件驱动脚本。
- 插件挂钩：代理/工具生命周期和网关管道内的扩展点。
#
内部挂钩（网关挂钩）
- ''''agent:bootstrap''''：在系统提示完成之前构建引导文件时运行。
使用它来添加/删除引导上下文文件。
- ''命令挂钩''：''/new''、''/reset''、''/stop'' 和其他命令事件（请参阅 Hooks 文档）。
请参阅 ''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'' 上发出部分回复。
- 推理流可以作为单独的流或块回复发出。
- 请参阅 ''Streaming'' 了解分块和块回复行为。
工具执行+消息传递工具
- 工具启动/更新/结束事件在 ''tool'' 流上发出。
- 在记录/发送之前，工具结果会根据大小和图像有效负载进行清理。
- 跟踪消息传递工具发送以抑制重复的助理确认。
回复整形+压制
- 最终有效负载由以下组件组装而成：
- 辅助文本（和可选推理）
- 内联工具摘要（当详细+允许时）
- 模型错误时助手错误文本
- ''NO_REPLY'' 被视为静默令牌并从传出的有效负载中过滤掉。
- 消息传递工具重复项已从最终有效负载列表中删除。
- 如果没有剩余可渲染的有效负载并且工具出错，则会发出后备工具错误回复
（除非消息传递工具已经发送了用户可见的回复）。
压缩+重试
事件流（今天）
- ''lifecycle''：由 ''subscribeEmbeddedPiSession'' 发出（并作为 ''agentCommand'' 的后备）
- ''assistant''：来自 pi-agent-core 的流式增量
- ''tool''：来自 pi-agent-core 的流式工具事件
聊天频道处理
- 助理增量被缓冲到聊天 ''delta'' 消息中。
- 在 ''生命周期结束/错误'' 时发出聊天 ''final''。
超时
- ''agent.wait'' 默认值：30 秒（只需等待）。 ''timeoutMs'' 参数覆盖。
- 代理运行时间：''agents.defaults.timeoutSeconds'' 默认 600 秒；在 ''runEmbeddedPiAgent'' 中止计时器中强制执行。
事情可以提前结束的地方
- 代理超时（中止）
- AbortSignal（取消）
- 网关断开或RPC超时
- ''agent.wait'' 超时（仅等待，不停止代理）