企业官网建设流程全解析

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

代理循环是代理的一次完整“真实”运行：输入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为动作和最终回复的权威路径，同时保持会话状态一致。在 OpenClaw 中，一个循环是每个会话的单一序列化运行，当模型思考、调用工具和流式输出时，会发出生命周期和流事件。本文档解释了该真实循环的端到端连接方式。

入口点

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

工作方式（高层视图）

1. agentRPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回{ runId, acceptedAt }
2. agentCommand运行代理：
   • 解析模型 + 思考/详细输出默认值
   • 加载技能快照
   • 调用runEmbeddedPiAgent（pi-agent-core 运行时）
   • 如果嵌入式循环未发出生命周期结束/错误，则发出lifecycle end/error
3. runEmbeddedPiAgent：
   • 通过每个会话 + 全局队列序列化运行
   • 解析模型 + 认证配置，构建 pi 会话
   • 订阅 pi 事件并流式传输助手/工具增量
   • 强制执行超时 -> 如果超时则中止运行
   • 返回负载 + 使用量元数据
4. subscribeEmbeddedPiSession将 pi-agent-core 事件桥接到 OpenClawagent流：
   • 工具事件 =>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）来供给此车道系统。参见命令队列。

会话 + 工作区准备

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

提示组装 + 系统提示

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

钩子点（可拦截的位置）

OpenClaw 有两个钩子系统：

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

内部钩子（Gateway 钩子）

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

插件钩子（代理 + 网关生命周期）

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

• before_model_resolve：在会话前运行（无messages），用于在模型解析前确定性地覆盖 provider/model。
• before_prompt_build：在加载会话后（带有messages）运行，用于在提交提示前注入prependContext、systemPrompt、prependSystemContext或appendSystemContext。使用prependContext处理每轮动态文本，使用 system-context 字段处理应位于系统提示空间中的稳定指导。
• 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流上发出。
• 在记录/发出之前，工具结果会进行大小和图像负载的清理。
• 跟踪消息工具发送以抑制重复的助手确认。

回复整形 + 抑制

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

压缩 + 重试

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

事件流（当前）

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

聊天通道处理

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

超时

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

可能提前结束的情况

• 代理超时（中止）
• AbortSignal（取消）
• Gateway 断开或 RPC 超时
• agent.wait超时（仅等待，不会停止代理）