OpenClaw Runtime 选型:Codex、Session 与配置排障(下)

原文：https://docs.openclaw.ai/concepts/agent-runtimes

三篇阅读顺序：

• 上篇：Runtime、Model、Tool 与 Prompt
• 中篇：Harness、完整执行链与 Context Engine
• 下篇：Runtime 选择、Session 与配置排障（当前篇）

前篇回顾： Harness 把统一调用接到底层 Runner；Agent Run 管理 Attempt，Attempt 内运行多次 Model Call。Context Engine 在调用前组装历史，并在溢出恢复时参与压缩。本篇比较不同 Runtime 的状态所有权，再介绍配置、绑定、认证与排障。

1. 同一个任务，使用两种 Runtime 有什么区别？

仍然使用“读 README 并总结”这个任务，也保持 Model 不变。以下是职责示意，不是实测结果；某个 Model 能否走某条路径，还要满足该路径的支持条件。

1.1 使用 OpenClaw Runtime

OpenClaw 平台把准备好的任务交给 OpenClaw Runtime。它调用 Model、处理读文件请求、继续调用 Model，最后把结果交回平台。

落实到代码层，就是 Harness 选择层取得内置 openclaw Harness，由其 runAttempt() 委托 Embedded Agent Runner。

在这条路径中，Agent Loop 由 OpenClaw 自己控制，用于继续对话的主要 Transcript（执行记录） 也由 OpenClaw 维护。

1.2 使用 Codex Runtime

OpenClaw 平台把准备好的任务和 Context 交给 Codex app-server。Codex 负责调用 Model、使用其 Tool 执行路径并继续这一轮循环，最后把结果交回 OpenClaw 平台。

落实到代码层，就是 Harness 选择层取得 Codex Plugin Harness，由它适配 Codex app-server 的原生执行语义。

在这条路径中，Codex 维护自己的 Thread（线程）。Thread 可以先理解为一段可继续执行的对话记录及相关状态。OpenClaw 同时保存 Transcript Mirror（执行记录镜像），用于平台侧展示和同步；镜像与 Codex 内部状态的职责不同。

1.3 换 Runtime，主要换的是执行方式

上表中的 Compaction（上下文压缩），就是把太长的对话整理成较短、可继续使用的内容。它由谁负责，会影响后续对话如何恢复和继续。

因此，即使 Model 相同，换 Runtime 也可能改变 Tool 行为、Thread 管理方式和插件能观察到的执行过程。原文没有性能对照实验，不能据此判断哪一种更快或任务完成率更高。

2. Model、Provider、Agent Runtime、Channel 各回答什么？

现在再看配置附近的几个名称，就容易分开了：

配置中的 openai/<model> 是 provider/model 的组合写法。这里的 <model> 是占位符，实际配置需要填入可用的 Model 名称。

看到 openai/<model>，只能据此识别 Model 选择；还要看 Runtime Policy（运行时策略）和路由兼容性，才能确定是否使用 Codex。

例如，下面两种组合在职责上都成立，实际执行需要满足对应路由、认证和工具支持条件：

Codex OAuth Authentication（Codex OAuth 认证） 解决如何获得访问资格；使用 Codex Runtime 解决由谁驱动这一轮。二者经常一起出现，但不能仅凭 Model 前缀或登录方式判断 Runtime 和计费方式。

3. OpenClaw 如何选择 Agent Runtime？

对于普通、未被特殊会话绑定覆盖的执行路径，可以按下面的顺序理解：

1. 看 Model 有没有指定 Runtime。 精确 Model 的配置优先于 provider/* 这样的 Wildcard（通配）配置。
2. 再看 Provider 有没有指定 Runtime。 例如给某个 Provider 设置统一执行方式。
3. 没有指定时，进行 Auto Selection（自动选择）。 已注册的 Runtime 根据支持条件决定是否接手。
4. 自动选择中无人接手时，使用 OpenClaw Runtime。

公开配置字段叫 agentRuntime.id。实际配置路径放在本篇第 4 节，此处只需要理解：越具体的 Model 配置，优先级越高。

自动选择 Codex 需要可用的 Codex Harness，以及受支持的有效请求路由。原文要求兼容的官方 HTTPS Responses Endpoint，并且请求中没有破坏兼容性的自定义覆盖。因此，openai/* 本身不足以触发 Codex。

明确指定 Runtime 后，不兼容通常会报错。 文档另有一个执行前的例外：如果 Runtime 声明 OpenClaw Runtime 能够完整保留这次请求的含义，可以在选择阶段交给 OpenClaw Runtime 处理。已经开始执行后的失败，不会换一个 Runtime 从头重放，因为此前可能已经写过文件或产生其他副作用。

到这里，主线已经完整：OpenClaw 平台收到任务 → 选择 Model 和 Runtime → Harness 选择层取得实现 → Harness 接入 Runner → Runner 驱动 Model 与 Tool → 平台发回结果。 后面的内容可以按需查阅。

4. 配置与排障查阅区

4.1 配置究竟写在哪里？

原文也支持 Provider 的 Model 条目，以及 agents.entries.*.models 中的 Model Policy。普通选择顺序是：精确 Model → Model Wildcard → Provider → Auto Selection → OpenClaw Runtime 回退。

下面是一个 JSON5 配置片段示意，含义是“为这个 OpenAI Model 指定 OpenClaw Runtime”。<model> 必须替换为实际可用的 Model 名称；该片段不包含认证等完整配置：

{  agents: {    defaults: {      model: "openai/<model>",      models: {        "openai/<model>": {          agentRuntime: { id: "openclaw" },        },      },    },  },}

把 Runtime 值改为 codex，表达的就是选择 Codex Runtime 的意图；它仍需通过实现可用性、路由和认证检查。

4.2 Codex 的几个入口分别用于什么？

ACP（Agent Client Protocol） 在这里先理解为连接外部 Agent Harness 的协议。Codex 的 ACP 路径使用 runtime: "acp" 和 agentId: "codex"；它与普通 Model 条目上的 agentRuntime.id 属于不同配置语境。

原文对普通 Codex Thread 控制推荐捆绑插件提供的 /codex bind、/codex threads、/codex resume、/codex steer、/codex stop。只有明确需要 ACP/acpx 或测试该 Adapter 路径时，才需要处理 Codex ACP 配置。

OpenAI 的图片、嵌入、语音等直接 API 也可能使用 openai/* 名称，但不等于它们都通过本文的 Agent Loop 运行。

4.3 Harness、CLI Backend 和 Copilot 是什么关系？

Harness 是遵守统一 Harness Contract、为某个 Runtime 提供执行能力的代码实现。使用配置时主要关心 Runtime ID；开发插件或阅读源码时，才需要进一步研究 Harness Contract。内置实现、选择层与 Runner 的具体关系见中篇第 1–3 节。

原文区分两类执行方式：一类是接入准备好的一轮任务的 Embedded Harness（内嵌实现），包括 OpenClaw Runtime 和 Codex 等插件实现；另一类是启动本地命令行进程的 CLI Backend（命令行后端）。

例如，Claude CLI 路径仍使用 anthropic/<model> 作为 Model Ref（模型引用），通过 Model Policy 中的 agentRuntime.id: "claude-cli" 指定 CLI Backend。claude-cli 不是可传给内嵌 AgentHarness 选择器的 Harness ID。

Copilot Runtime 是额外的可选插件 Runtime，配置值为 copilot。它需要显式启用和选择，原文明确说明它不会被 auto 自动选中。

4.4 为什么绑定过的会话可能不按普通顺序选择？

本篇第 3 节讲的是普通配置选择。已有 Session（会话） 还可能保留原生连接或明确指定的 Runtime，所以排障时需要检查 Session 状态。

如果原生 Model 仍使用 OpenClaw 平台准备的认证，就必须按实际使用的 provider/model 选择凭证。恢复 Thread 后，若实际 Model 发生变化，而凭证已按旧 Model 准备，本轮会在推理前停止并保留新观察到的状态。

Codex 的 Native Authentication（原生连接认证） 有更窄的边界：原文把它限定在单独的 Supervision Connection；保留原生 Model 的 Managed Connection 仍使用平台准备的认证。Native-auth Connection 保持自己的连接策略，不接收平台转发的 Auth Profile，并拒绝显式的逐轮 Provider Stream 参数。遇到这类场景需要查原文的 Runtime Ownership 段落。

4.5 Tool Hooks 和 Context Lifecycle 为什么会受影响？

先把两个相近概念分开：Context Window（上下文窗口） 是 Model 单次推理可接收的容量限制；Context Engine（上下文引擎） 是宿主侧管理有效历史的机制，负责或参与 assemble、ingest、after-turn 与 compact 等生命周期。它决定“哪些记录以什么形态进入下一次 Model Call”，但它不替代 Model 的语义理解。

Tool Hook（工具钩子） 是 Tool 执行前后留给插件的通知、检查入口。例如，一个插件可能希望在文件修改前检查路径，或在 Tool 执行后保存记录。

OpenClaw Runtime 直接控制的步骤，可以提供相应 OpenClaw 插件接口。Codex 自己控制的步骤，则需要 Codex Native Event 或受支持的 Hook，才能让平台观察和介入。

所以，“能完成一次回答”不足以说明所有插件功能都可用。评估其他 Runtime 时，应检查：

• Agent Loop 和主要 Thread 状态由谁维护。
• OpenClaw 自有 Tool 是否可用，其执行前后 Hook 是否可用。
• Runtime 原生 Shell、Patch 等 Tool 是否暴露所需 Hook。
• assemble、ingest 和 after-turn 等 Context Lifecycle 阶段是否运行。
• Compaction 只提供通知，还是也提供保留、丢弃了哪些内容的信息。
• 哪些能力明确不支持。

Context（上下文） 是本轮交给 Model 的指令、历史和项目材料。在 Codex 路径下，OpenClaw 仍把组装好的 Context 传入 Codex Turn（单轮执行）；这不等于所有内置 Context Plugin 生命周期都自动具有相同行为。谁拥有 Compaction，也要以所选 Context Engine 与 Harness 能力为准，不能只凭 Runtime 名称推断。

4.6 旧配置、推理参数与状态显示

Legacy Configuration Migration（旧配置迁移）： 原文说旧的整 Agent Runtime 配置和 OPENCLAW_AGENT_RUNTIME 已被忽略；openclaw doctor --fix 用于修复过时配置、旧 Model Ref 和残留 Session Pin。这个命令会修改配置，使用前应理解其迁移内容。

旧 claude-cli/* 引用迁移为标准 Anthropic Model Ref 加 Model-scoped CLI Policy。旧 codex-cli/* 引用则迁移为 openai/* 与 Codex app-server 路径；原文记载捆绑 Codex CLI Backend 已在 v2026.5.14 移除。

Reasoning Controls（推理参数）：supportsReasoningEffort、supportedReasoningEfforts 描述 Model 支持的推理强度；合法的 fastMode、thinking 值也不等于切换 Runtime。自定义请求参数、Header、Timeout 和兼容开关则可能影响路由兼容性，应结合有效请求检查。

Status Labels（状态显示）： Model 名称、Runtime 和 Channel 名称分别说明 Model、执行组件和消息入口。下一轮的 Runtime 预览不会启动 Runtime 或探测凭证，最终认证准备仍可能失败；完成结果记录实际执行的 Runtime。

发现 Runtime 与预期不符时，依次检查 Model Policy、Provider Policy、Session Binding、插件可用性、有效路由和认证准备，再核对执行结果。

5. 常见疑问

深入探讨：openai/* 是否就等于 Codex Runtime？

不等于。它只标识 Provider 与 Model。Runtime 还取决于 Model Policy、Provider Policy、插件可用性以及有效路由的支持条件。同一个 OpenAI Model 可以由 OpenClaw Runtime 执行，也可能由 Codex Runtime 执行。

深入探讨：OpenClaw 已经镜像了 Codex Transcript，为什么不能把镜像当原件编辑？

因为继续 Codex 对话时，以 Codex 维护的 Thread 状态为准。OpenClaw 的 Transcript Mirror 服务于展示和同步，可能没有 Codex 内部的完整状态。修改镜像不代表 Codex 会接受同样的修改，操作应通过它支持的 Thread Control 接口完成。

深入探讨：为什么 Harness 运行失败后不自动换 Runtime 重试？

执行过程中可能已经修改文件或发送消息。换一个 Runtime 从头执行，可能重复这些操作。文档允许的 Lossless Fallback（无损回退）发生在执行开始之前；Runtime 一旦开始执行，其失败不会经另一 Runtime 重放。

深入探讨：Model Lock 为什么不能证明 Runtime 和认证也被锁住？

Model Lock 只表达“保持这个 Model 选择”。由谁执行、如何认证以及是否绑定原生 Thread，是另外的状态。排障时应分别核对这些信息，不能把 Model Lock 理解为整个执行配置都固定了。

深入探讨：auto 回退到 OpenClaw 会不会掩盖配置错误？

如果原本期望使用某个 Plugin Runtime，却没有明确指定，只看回答成功确实可能忽略自动回退。必须使用某 Runtime 时应显式配置，并检查实际执行结果；不兼容通常会报错，只有 Runtime 声明能够完整保留请求的执行前回退属于文档规定的例外。

深入探讨：这篇文档能否证明 Codex Runtime 比 OpenClaw Runtime 更快或更强？

不能。它解释的是执行职责、状态管理和兼容规则，没有对延迟、成本或任务完成率做对照实验。文中的 README 示例也只是帮助理解流程；Runtime 选型效果需要在真实任务上验证。

6. 三篇总结与来源

读完后，先能回答八个问题就够了：

1. OpenClaw 与 Codex 的关系？ OpenClaw 是平台，Codex Runtime 是它可选择的 Runtime 之一。
2. Model 与 Runtime 的关系？ Model 生成回答或 Tool Call，Runtime 组织多次 Model 调用与 Tool 执行。
3. 自然语言、Tool 和路径由谁处理？ Runtime 提供 Context 与 Tool Schema，Model 理解意图并生成 Tool Call，Runtime 解析、校验和执行；路径未知时通过 Tool 逐步发现。
4. Runtime 与 Harness 的关系？ Runtime 是执行语义和配置选择，Harness 是遵守统一 Contract、提供这种执行能力的代码实现。
5. Harness 选择层与内置 Harness 的关系？ 前者选择执行入口，后者把 openclaw Runtime 接到 Embedded Agent Runner。
6. 完整执行链怎样分层？ 一个 Agent Run 可以有多个 Attempt，一个 Attempt 可以有多个 Model Call；Harness 只在 Attempt 边界接入执行器。
7. Prompt 与 Context Engine 在哪里？ System Prompt、Messages、Tool Definitions 等共同形成 Model Input；Context Engine 在 Model Call 前组装历史，并在溢出后参与压缩恢复。
8. 关键动作由谁执行？ Model 负责理解和决策，Runtime 与 Tool Executor 负责真实动作，Run 外层负责选择、重试、压缩协调与最终投递。

本文依据 OpenClaw 官方 Agent runtimes 文档、Agent runtime architecture、Agent loop、System prompt、Agent workspace 和 Agent harness plugins，于 2026-09-15 核对在线内容并重组讲解。代码关系按 OpenClaw 提交 f1957d9 核对，关键入口包括 builtin-openclaw.ts、run-loop.ts、attempt.ts、attempt-history-prepare.ts 和 attempt-execution-phase.ts。职责图、README 示例、缩写伪代码和“OpenClaw 平台”“Harness 选择层”等本文称呼，是为解释机制而整理，不是官方测试结果或新的配置字段。