入口点
- Gateway 网关 RPC：
agent和agent.wait。 - CLI：
openclaw agent。
运行序列
agentRPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回{ runId, acceptedAt }。agentCommand运行该轮次：解析模型 + thinking/verbose/trace 默认值，加载 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），并将其送入这一通道系统；参见 Command Queue。 转录写入还会受到会话文件上的会话写锁保护。该锁感知进程且基于文件，因此可以捕获绕过进程内队列或来自另一个进程的写入者。写入者最多等待session.writeLock.acquireTimeoutMs（默认 60000 毫秒；环境变量覆盖 OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS），然后报告会话忙碌。
会话写锁默认不可重入。若某个辅助函数有意嵌套获取同一把锁，同时保留一个逻辑写入者，则必须使用 allowReentrant: true 显式启用。
会话和工作区准备
- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
- 加载 Skills（或从快照复用）并注入到环境变量和提示词中。
- 解析 bootstrap/上下文文件并注入到系统提示词中。
- 在流式传输开始前，获取会话写锁并打开和准备
SessionManager。任何后续转录重写、压缩或截断路径，都必须在打开或变更转录文件之前获取同一把锁。
提示词组装
系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和按运行覆盖项构建。会强制执行特定模型的限制和压缩预留 token。参见 系统提示词 了解模型会看到什么。Hooks
OpenClaw 有两套钩子系统：- 内部钩子（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
- 插件钩子：智能体/工具生命周期和 Gateway 网关流水线中的扩展点。
内部钩子（Gateway 网关钩子）
agent:bootstrap：在系统提示词最终确定之前构建 bootstrap 文件时运行。可用于添加或移除 bootstrap 上下文文件。- 命令钩子：
/new、/reset、/stop和其他命令事件（参见 Hooks 文档）。
插件钩子
这些钩子在智能体循环或 Gateway 网关流水线中运行：| 钩子 | 运行时机 |
|---|---|
before_model_resolve | 会话前（无 messages），用于在解析前确定性地覆盖提供商/模型。 |
before_prompt_build | 会话加载后（带 messages），用于在提交前注入 prependContext、systemPrompt、prependSystemContext 或 appendSystemContext。将 prependContext 用于按轮次动态文本，将系统上下文字段用于属于系统提示词空间的稳定指导。 |
before_agent_start | 旧版兼容钩子，可能在任一阶段运行；优先使用上面的显式钩子。 |
before_agent_reply | 在线操作之后、LLM 调用之前。允许插件接管该轮次并返回合成回复，或完全静默。 |
agent_end | 完成后运行，携带最终消息列表和运行元数据。 |
before_compaction / after_compaction | 观察或标注压缩周期。 |
before_tool_call / after_tool_call | 拦截工具参数/结果。 |
before_install | 操作员安装策略运行后，在暂存的 Skills/插件安装材料上运行，前提是当前进程中已加载插件钩子。 |
tool_result_persist | 在工具结果写入 OpenClaw 拥有的会话转录之前同步转换这些结果。 |
message_received / message_sending / message_sent | 入站和出站消息钩子。 |
session_start / session_end | 会话生命周期边界。 |
gateway_start / gateway_stop | 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流上发出。 - 工具结果在记录/发出之前，会针对大小和图片载荷进行清理。
- 消息工具发送会被跟踪，以抑制重复的助手确认。
回复成形
最终载荷由助手文本（加上可选推理）、内联工具摘要（在 verbose 且允许时）以及模型出错时的助手错误文本组装而成。- 精确的静默 token
NO_REPLY会从出站载荷中过滤掉。 - 消息工具重复项会从最终载荷列表中移除。
- 如果没有剩余可渲染载荷且某个工具出错，除非消息工具已经发送了用户可见回复，否则会发出回退工具错误回复。
压缩和重试
自动压缩会发出compaction 流事件，并可能触发重试。重试时，内存缓冲区和工具摘要会重置，以避免重复输出。参见 压缩。
事件流
lifecycle：由subscribeEmbeddedAgentSession发出（并由agentCommand作为回退发出）。assistant：来自智能体运行时的流式增量。tool：来自智能体运行时的流式工具事件。
聊天渠道处理
助手增量会缓冲为聊天delta 消息。聊天 final 会在 生命周期结束/错误 时发出。
超时
| 超时 | 默认值 | 说明 |
|---|---|---|
agent.wait | 30s | 仅等待；timeoutMs 参数会覆盖。不会停止底层运行。 |
Agent runtime (agents.defaults.timeoutSeconds) | 172800s（48h） | 由 runEmbeddedAgent 的中止计时器强制执行。 |
| Cron 隔离的 Agent 轮次 | 由 cron 拥有 | 调度器在执行开始时启动自己的计时器，在配置的截止时间中止运行，然后在记录超时前运行有界清理，避免陈旧的子会话让通道一直卡住。 |
| 模型空闲超时 | agents.defaults.timeoutSeconds，默认上限为 120s | 当空闲窗口内没有响应块到达时，OpenClaw 会中止模型请求。models.providers.<id>.timeoutSeconds 会为较慢的本地/自托管提供商扩展此空闲看门狗，但仍受任何更低的 agents.defaults.timeoutSeconds 或特定运行超时约束，因为它们控制整个智能体运行。没有显式模型/智能体超时的 cron 触发云模型运行使用相同默认值；如果有显式 cron 运行超时，云模型流停滞的上限为 60s，以便配置的模型回退仍可在外层 cron 截止时间前运行。cron 触发的本地/自托管模型运行会禁用隐式看门狗，除非配置了显式超时；请为较慢的本地提供商设置 models.providers.<id>.timeoutSeconds。 |
| 提供商 HTTP 请求超时 | models.providers.<id>.timeoutSeconds | 覆盖连接、标头、正文、SDK 请求超时、受保护的 fetch 中止处理，以及该提供商的模型流空闲看门狗。对于较慢的本地/自托管提供商（例如 Ollama），请先使用它，再提高整个 Agent runtime 超时；当模型请求需要运行更久时，请保持智能体/运行时超时至少同样高。 |
卡住会话诊断
启用诊断后，diagnostics.stuckSessionWarnMs（默认 120000 ms）会将长时间处于 processing 且未观察到回复、工具、状态、分块或 ACP 进度的会话分类：
- 活跃的嵌入式运行、模型调用和工具调用会报告为
session.long_running。有归属的静默模型调用会保持为session.long_running，直到达到diagnostics.stuckSessionAbortMs，这样较慢或非流式提供商不会过早被标记为停滞。 - 没有近期进度的活跃工作会报告为
session.stalled。有归属的模型调用会在达到或超过中止阈值时切换为session.stalled；无归属的陈旧模型/工具活动不会被隐藏为长时间运行。 session.stuck保留用于可恢复的陈旧会话记账，包括带有陈旧无归属模型/工具活动的空闲排队会话。
diagnostics.stuckSessionAbortMs 默认为至少 5 分钟且为警告阈值的 3 倍。陈旧会话记账会在恢复门槛通过后立即释放受影响的会话通道；停滞的嵌入式运行只有在达到中止阈值后才会中止并排空，因此排队工作会恢复，而不会切断只是较慢的运行。恢复会发出结构化的 requested/completed 结果；只有当同一个 processing 生成仍是当前生成时，诊断状态才会标记为空闲，并且重复的 session.stuck 诊断会在会话保持不变时退避。
可能提前结束的位置
- 智能体超时（中止）
- AbortSignal（取消）
- Gateway 网关断开连接或 RPC 超时
agent.wait超时（仅等待，不会停止智能体）