OpenClaw Agent Runner 深度解析：一次 Agent 运行的完整生命周期

1. 引言：Agent Runner 是什么？

在 OpenClaw 的架构中，Agent Runner（或称 Agent Runtime）是真正“干活”的核心引擎。如果用一座工厂来比喻 OpenClaw：

• Gateway是“前台接待”——接消息、做路由、控制权限
• Agent Runner是“生产车间”——把用户指令变成实际操作，再把结果送回来

一句话定义：Agent Runner 是拥有一个已准备模型循环的组件——它接收提示词，驱动模型输出，处理原生工具调用，并将完成的轮次返回给 OpenClaw。

本文将完整拆解 Agent Runner 的工作过程，从触发到结束，逐一剖析每个阶段的职责、机制和设计考量。

2. Runner 与 Provider、Model、Channel 的区别

首先需要理清一个常见的混淆点。在 OpenClaw 中，Runner（执行环境）、Provider（提供商）、Model（模型）和 Channel（渠道）是四个不同层级的概念：

简单来说：Provider 解决“找谁认证”，Model 解决“用哪个大脑”，Runtime 解决“怎么跑这个大脑”，Channel 解决“从哪里接消息”。

Runtime 又有两个家族：

• 嵌入式 Harness：在 OpenClaw 已准备的 Agent 循环内运行，包括内置的openclaw运行时和插件注册的codex等
• CLI 后端：运行本地 CLI 进程，保持模型引用为标准形式，如anthropic/claude-opus-4-7配合agentRuntime.id: "claude-cli"

3. 一次 Agent 运行的完整阶段

一次 Agent 运行经历五个核心阶段。以下将逐一展开。

3.1 阶段一：参数校验与会话解析

Agent 运行的触发方式有两种：

1. Gateway RPC：agent和agent.wait
2. CLI 命令：openclaw agent --message "..."

当用户消息抵达后，agentRPC 执行以下步骤：

1. 参数校验：检查消息格式、权限、Token 限额等
2. 会话解析：根据sessionKey或sessionId定位到具体会话
   • 私聊消息 → 映射到主会话（main）
   • 群组/频道消息 → 按频道隔离，每个群组拥有独立会话键
3. 会话元数据持久化：记录会话状态
4. 立即返回：返回{ runId, acceptedAt }，不等待运行完成。这个设计让 Gateway 可以快速响应，而 Agent 在后台继续处理。

关键设计：agentRPC 是异步的——它只负责“接下这个任务”，真正的执行由agentCommand和runEmbeddedAgent完成。

3.2 阶段二：上下文组装

agentCommand开始真正执行前，需要完成上下文组装。这是 Agent 能够“有记忆、有身份、有工具”的基础。

3.2.1 工作区引导文件加载

OpenClaw 在agents.defaults.workspace目录下加载一系列引导文件，注入到系统提示词中：

这些文件在新会话的第一轮中会被注入到系统提示词的“项目上下文”中。空白文件会被略过；大文件会被修剪截断以保证提示词精炼。

3.2.2 Skills 加载

Agent 会加载 Skills 快照。Skills 通过SKILL.md文件描述，采用渐进式披露机制：启动时只加载技能的名称和描述摘要，详细的指令文本只有被选中时才加载。这种设计有效控制了上下文窗口的占用。

3.2.3 模型与认证解析

系统解析：

• 模型引用（如openai/gpt-5.5）
• 认证配置文件（如 OAuth 或 API Key）
• 运行时策略（决定使用哪个 Runtime）

运行时选择有明确的优先级：

1. 模型级运行时策略（最高优先级）
2. Provider 级运行时策略
3. auto 模式：注册的插件 Runtime 可以声明支持的 Provider/Model 组合
4. 兜底：如果没有运行时声明该轮次，使用openclaw作为兼容性运行时

OpenAI Agent 模型是一个特例：未设置运行时和auto模式都会解析到Codex harness。

3.3 阶段三：执行循环（Agent Loop）

这是 Agent Runner 最核心的部分——ReAct 循环。

3.3.1 排队与并发控制

运行按会话键串行化，并可选择经过全局通道。这个设计防止了工具/会话竞争，保持会话历史一致性。

会话转录写入受文件锁保护。锁是进程感知且基于文件的，能捕获绕过进程内队列或来自其他进程的写入者。会话转录写入者最多等待session.writeLock.acquireTimeoutMs（默认 60,000ms），之后报告会话忙。

核心设计原则：OpenClaw 采用“串行优先”的队列模型——每个会话独立排队，默认串行执行，优先保证状态稳定。并发越多，状态越容易失控。

3.3.2runEmbeddedAgent的核心循环

runEmbeddedAgent是执行循环的实际承载者：

1. 建立 Pi 会话：构建 pi-agent-core 运行时所需的对象
2. 订阅 Pi 事件：将 pi-agent-core 的事件桥接到 OpenClaw Agent 流
   • 工具事件 →stream: "tool"
   • Assistant 增量 →stream: "assistant"
   • 生命周期事件 →stream: "lifecycle"（phase:start/end/error）
3. 强制执行超时：通过中止计时器控制运行时长
4. 对于 Codex app-server 轮次：如果已接受的轮次在终端事件前停止产生进度，则中止该轮次

3.3.3 超时机制

OpenClaw 设置了多层超时，防止 Agent“死循环”或卡住：

3.4 阶段四：流式回复与事件投递

OpenClaw 支持在模型生成过程中流式输出，而不是等全部生成完再一次性返回。

3.4.1 事件流

Agent 运行过程中发出的流事件包括：

• lifecycle：start→end/error
• assistant：来自模型的流式增量文本
• tool：工具调用的 start/update/end 事件
• compaction：压缩周期事件

3.4.2 分块流式传输

通过配置blockStreamingDefault可以开启分块流式传输，在模型生成文本块时发送部分回复，而不是等待完整回复。关键设置包括blockStreamingBreak（在text_end或message_end处分块）和humanDelay（分块回复之间的类人暂停）。

3.4.3 静默回复

精确的静默 TokenNO_REPLY/no_reply表示“不要投递用户可见的回复”。系统会将其从出站负载中剥离，但工具媒体附件仍会投递。

3.5 阶段五：持久化与生命周期结束

3.5.1 持久化

循环完成后，整个会话和工具结果被持久化。会话转录以 JSONL 格式存储在：

~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

会话 ID 是稳定的，由 OpenClaw 选定。

3.5.2agent.wait等待完成

agent.wait使用waitForAgentRun等待特定runId的生命周期 end/error，返回{ status: ok|error|timeout, startedAt, endedAt, error? }。

4. 运行时选择策略（Runtime Selection）

OpenClaw 在 Provider 和模型解析之后选择嵌入式运行时。选择优先级如下：

1. 模型级运行时策略（最高优先级）：位于已配置的 Provider 模型条目中，或agents.defaults.models["provider/model"].agentRuntime
2. Provider 级运行时策略：位于models.providers.<provider>.agentRuntime
3. auto 模式：已注册的插件 Runtime 可以声明支持的 Provider/Model 组合
4. 兜底：如果没有运行时声明，使用openclaw作为兼容性运行时

特别注意：整会话和整 Agent 运行时固定项（如OPENCLAW_AGENT_RUNTIME）会被忽略。运行openclaw doctor --fix可以移除过期的配置并转换旧版模型引用。

5. 运行时所有权：谁拥有循环的哪部分？

不同运行时拥有循环中不同范围的内容。以 OpenClaw 内置 Runtime 和 Codex app-server 为例：

这个所有权拆分是主要设计规则：

• 如果 OpenClaw 拥有该表面 → 提供正常的插件钩子行为
• 如果原生运行时拥有该表面 → OpenClaw 需要运行时事件或原生钩子
• 如果原生运行时拥有规范线程状态 → OpenClaw 应镜像和投影上下文，不重写不受支持的内部实现

6. 架构速览：代码在哪里？

OpenClaw 的 Agent Runtime 代码分布如下：

7. 结语

Agent Runner 是 OpenClaw 从“能说会道”到“真刀真枪干活”的关键转化器。一次 Agent 运行的生命周期可以概括为：

1. 参数校验与会话解析→ 接单
2. 上下文组装→ 准备工作
3. 执行循环（模型推理 ↔ 工具执行）→ 核心干活
4. 流式回复与事件投递→ 边干边汇报
5. 持久化与生命周期结束→ 收工存档

理解 Agent Runner 的工作方式，是深入掌握 OpenClaw 工程原理的必修课。它融合了队列管理、会话锁、运行时选择、超时控制、事件流分发等多个系统工程的关键设计，值得仔细品味。