入口点
- Gateway 网关 RPC：
agent和agent.wait。 - CLI：
openclaw agent。
运行顺序
agentRPC 验证参数、解析会话（sessionKey/sessionId）、持久化会话元数据，并立即返回{ runId, acceptedAt }。agentCommand执行本轮：解析模型及思考/详细/追踪默认值、加载 Skills 快照、调用runEmbeddedAgent；如果嵌入式循环尚未发出 生命周期结束/错误 事件，则发出一个后备事件。runEmbeddedAgent：通过按会话队列和全局队列串行执行运行、解析模型及身份验证配置文件、构建 OpenClaw 会话、订阅运行时事件、流式传输助手/工具增量、强制执行运行超时（到期时中止），并返回有效载荷及用量元数据。对于 Codex app-server 轮次，如果已接受的轮次在终止事件前停止产生 app-server 进度，也会将其中止。subscribeEmbeddedAgentSession将运行时事件桥接到agent流：工具事件传到stream: "tool"，助手增量传到stream: "assistant"，生命周期事件传到stream: "lifecycle"（phase: "start" | "end" | "error"）。agent.wait（waitForAgentRun）在runId上等待 生命周期结束/错误，然后返回{ status: ok|error|timeout, startedAt, endedAt, error? }。
排队与并发
运行按会话键（会话通道）串行执行，并可选择再经过一个全局通道，从而防止工具/会话竞态。消息渠道选择一种队列模式（steer/followup/collect/interrupt）以将消息送入此通道系统；请参阅命令队列。 会话文件上的会话写入锁还会额外保护对话记录写入。该锁可感知进程且基于文件，因此能捕获绕过进程内队列或来自其他进程的写入方。写入方默认最多等待 60 秒（可通过环境变量OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS 覆盖），之后将会话报告为忙碌状态。
默认情况下，会话写入锁不可重入。如果辅助函数在维持单一逻辑写入方的同时有意嵌套获取同一把锁，则必须通过 allowReentrant: true 明确启用。
会话与工作区准备
- 解析并创建工作区；沙箱隔离的运行可能会重定向到沙箱工作区根目录。
- 加载 Skills（或从快照复用），并将其注入环境和提示词。
- 解析引导/上下文文件，并将其注入系统提示词。
- 在流式传输开始前获取会话写入锁并准备会话对话记录目标。之后任何对话记录重写、压缩或截断路径都必须在修改 SQLite 对话记录行之前获取同一把锁。
提示词组装
系统提示词由 OpenClaw 的基础提示词、Skills 提示词、引导上下文和按运行覆盖项构建。系统会强制执行特定于模型的限制和压缩预留 token。有关模型所见内容，请参阅系统提示词。Hooks
OpenClaw 有两套 Hook 系统：- 内部钩子（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
- 插件钩子：智能体/工具生命周期和 Gateway 网关管线中的扩展点。
内部钩子（Gateway 网关钩子）
agent:bootstrap：在系统提示词最终确定之前构建引导文件时运行。使用它添加或移除引导上下文文件。- 命令钩子：
/new、/reset、/stop以及其他命令事件（请参阅 Hooks 文档）。
插件钩子
这些钩子在智能体循环或 Gateway 网关管线中运行：
出站/工具防护钩子的决策规则：
before_tool_call：{ block: true }是终止决策，并会阻止优先级较低的处理程序。{ block: false }不执行任何操作，也不会清除之前的阻止决策。before_install：终止/无操作语义与上文相同。对于必须覆盖 CLI 安装和更新路径、由操作员所有的安装允许/阻止决策，请使用security.installPolicy，而不是before_install。message_sending：{ cancel: true }是终止决策，并会阻止优先级较低的处理程序。{ cancel: false }不执行任何操作，也不会清除之前的取消决策。
流式传输
- 助手增量从智能体运行时以
assistant事件形式流式传输。 - 分块流式传输可在
text_end或message_end时发出部分回复。 - 推理流式传输可以作为独立流，也可以阻止回复。
- 有关分块和分块回复行为，请参阅流式传输。
工具执行
- 工具开始/更新/结束事件在
tool流上发出。 - 在记录日志/发出事件之前，会按大小和图像有效载荷对工具结果进行清理。
- 系统会跟踪消息工具的发送操作，以抑制重复的助手确认消息。
回复成形
最终有效载荷由助手文本（加上可选的推理内容）、内联工具摘要（启用详细模式且允许时），以及模型出错时的助手错误文本组装而成。- 输出有效载荷会过滤完全匹配的静默 token
NO_REPLY。 - 最终有效载荷列表会移除消息工具产生的重复项。
- 如果没有剩余的可渲染有效载荷且工具发生错误，则会发出后备工具错误回复，除非消息工具已经发送了用户可见的回复。
压缩与重试
自动压缩会发出compaction 流事件，并可能触发重试。重试时，内存缓冲区和工具摘要会重置，以避免重复输出。请参阅压缩。
事件流
lifecycle：由subscribeEmbeddedAgentSession发出（也会由agentCommand作为后备发出）。assistant：来自智能体运行时的流式增量。tool：来自智能体运行时的流式工具事件。
聊天渠道处理
助手增量会缓冲到聊天delta 消息中。发生 生命周期结束/错误 时，会发出聊天 final。
超时
卡住的会话诊断
启用诊断后，内置的两分钟阈值会对长时间没有观察到回复、工具、状态、分块或 ACP 进度的processing 会话进行分类：
- 活跃的嵌入式运行、模型调用和工具调用报告为
session.long_running。由所有者管理但静默的模型调用会保持session.long_running状态，直至达到中止阈值，以免过早将缓慢或非流式提供商标记为停滞。 - 没有近期进度的活跃工作报告为
session.stalled。由所有者管理的模型调用在达到或超过中止阈值时切换为session.stalled；无所有者的陈旧模型/工具活动不会被隐藏为长时间运行。 session.stuck专用于可恢复的陈旧会话记录，包括存在陈旧无所有者模型/工具活动的空闲排队会话。
session.stuck 诊断会进行退避。
可能提前结束的情况
- Agent 超时（中止）
- AbortSignal（取消）
- Gateway 网关断开连接或 RPC 超时
agent.wait超时（仅等待，不会停止 Agent）