ClawCN - OpenClaw 中文版

主题

Agent Loop (OpenClaw) ​

agentic loop 是 agent 的完整"真实"运行过程：接收输入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为操作和最终回复的权威路径,同时保持会话状态的一致性。

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

入口点 ​

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

工作原理(高层级) ​

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

队列 + 并发 ​

  • 运行按会话键(会话通道)串行化,并可选择通过全局通道。
  • 这防止了工具/会话竞争并保持会话历史的一致性。
  • 消息通道可以选择队列模式(collect/steer/followup),这些模式会馈送到通道系统。 参见 Command Queue。

会话 + 工作区准备 ​

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

提示组装 + 系统提示 ​

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

钩子点(可以拦截的位置) ​

OpenClaw 有两个钩子系统:

  • 内部钩子 (Gateway 钩子): 用于命令和生命周期事件的事件驱动脚本。
  • 插件钩子: agent/工具生命周期和 gateway 管道内的扩展点。

内部钩子(Gateway 钩子) ​

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

参见 Hooks 了解设置和示例。

插件钩子(agent + gateway 生命周期) ​

这些在 agent 循环或 gateway 管道内运行:

  • 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: gateway 生命周期事件。

参见 Plugins 了解钩子 API 和注册细节。

流式传输 + 部分回复 ​

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

工具执行 + 消息工具 ​

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

回复塑形 + 抑制 ​

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

压缩 + 重试 ​

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

事件流(当前) ​

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

聊天通道处理 ​

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

超时 ​

  • agent.wait 默认值: 30秒(仅等待)。timeoutMs 参数覆盖。
  • Agent 运行时: agents.defaults.timeoutSeconds 默认 600秒;在 runEmbeddedPiAgent 中止计时器中强制执行。

可能提前结束的情况 ​

  • Agent 超时(中止)
  • AbortSignal(取消)
  • Gateway 断开连接或 RPC 超时
  • agent.wait 超时(仅等待,不停止 agent)