OpenClaw从入门到应用——Agent：Agent循环（Agent Loop）

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》代理循环是代理的一次完整“真实”运行输入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为动作和最终回复的权威路径同时保持会话状态一致。在 OpenClaw 中一个循环是每个会话的单一序列化运行当模型思考、调用工具和流式输出时会发出生命周期和流事件。本文档解释了该真实循环的端到端连接方式。入口点Gateway RPCagent和agent.waitCLIagent命令工作方式高层视图agentRPC 验证参数解析会话sessionKey/sessionId持久化会话元数据立即返回{ runId, acceptedAt }agentCommand运行代理解析模型 思考/详细输出默认值加载技能快照调用runEmbeddedPiAgentpi-agent-core 运行时如果嵌入式循环未发出生命周期结束/错误则发出lifecycle end/errorrunEmbeddedPiAgent通过每个会话 全局队列序列化运行解析模型 认证配置构建 pi 会话订阅 pi 事件并流式传输助手/工具增量强制执行超时 - 如果超时则中止运行返回负载 使用量元数据subscribeEmbeddedPiSession将 pi-agent-core 事件桥接到 OpenClawagent流工具事件 stream: tool助手增量 stream: assistant生命周期事件 stream: lifecyclephase: start | end | erroragent.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超时仅等待不会停止代理