选择策略

OpenClaw 在提供商和模型解析之后如何选择 harness，失败会对模型回退链产生什么影响，以及为什么 harness 通常随提供商插件一起提供。这是 Agent harness 插件 参考的一部分。

选择策略¶

OpenClaw 在提供商/模型解析之后选择 harness：

1. 模型范围的运行时策略优先。
2. 提供商范围的运行时策略次之。
3. auto 会询问已注册的 harness 是否支持解析后的有效路由。仅凭提供商/模型前缀永远不会选择 harness。
4. 如果没有已注册的 harness 匹配，OpenClaw 使用其内置运行时。

对于已配置的模型，传输细节和请求覆盖来自同一选中的模型行。精确模型 ID 优先于旧版提供商前缀行，即使精确行继承提供商默认值也是如此。

插件 harness 失败会表现为运行失败。在 auto 模式下，内置回退仅在没有已注册的插件 harness 支持解析后的提供商/模型时适用。一旦某个插件 harness 已认领一次运行，OpenClaw 不会通过另一个运行时重放同一轮次，因为这可能会改变认证/运行时语义或重复副作用。

在 harness 开始任何模型工作之前发生的失败可以使用来自 openclaw/plugin-sdk/agent-harness-runtime 的 AgentHarnessPreflightError。默认错误对整个模型回退链仍然是终止性的。仅当失败局限于所选 harness，并且在同一 harness 上重试另一个模型会重复该失败时，才传递 { scope: "harness" }。OpenClaw 在尝试边界记录实际选择的 harness，仅跳过已被证明使用该 harness 的后续候选项，并让任何不同归属的候选项通过其常规运行时和策略检查。插件选择加入该范围，但不会在错误中命名 harness 所有者。在请求或工具操作可能已产生副作用之后，不要使用 harness 范围。

已配置的运行时策略仍然是期望运行时的权威来源。持久的原生 harness 固定会保留其转录所有者；在插件拥有的具体模型聊天中观察到的 harness 不会成为固定，即使模型选择已锁定也是如此。对于具体模型执行，请求或固定都不会使不兼容的路由变得兼容：harness 必须支持准备好的事实，声明精确请求的 OpenClaw 回退，或失败关闭。绑定的原生会话所有权 单独识别那些经过验证的原生连接拥有模型和认证的会话，因此无关的外部路由元数据不会替换该连接。

下一轮元数据使用已注册的支持决定，并保留其模型/提供商/会话来源。历史生产者观察不会固定下一轮。投影永远不会加载 harness 或读取凭据。准备状态是显式的：缺失的 runtimePolicy 保持未声明，而不是根据碰巧存在的任何传输字段进行推断。当 harness 拥有的认证使多个物理路由未解析时，准备好的支持事实是它们兼容运行时 ID 的交集，并在任何候选项具有请求覆盖时报告请求覆盖。因此，一个未声明的候选项会使原生兼容性为空；preparedAuth.source: "harness" 是认证所有者，而不是推断路由支持的权限。

如果所选 harness 出乎意料，请启用 agents/harness 调试日志，并检查网关的结构化 agent harness selected 记录：它包括所选 harness ID、选择原因、运行时/回退策略，以及在 auto 模式下每个插件候选项的支持结果。

捆绑的 Codex 插件将 codex 注册为其 harness ID。核心将其视为普通插件 harness ID；Codex 特定别名应放在插件或操作员配置中，而不是共享运行时选择器中。

提供商与 harness 配对¶

大多数 harness 还应注册一个提供商。提供商使模型引用、认证状态、模型元数据和 /model 选择对 OpenClaw 的其他部分可见。然后 harness 在 supports(...) 中认领该提供商。

捆绑的 Codex 插件遵循此模式：

• 首选用户模型引用：openai/gpt-6-astra
• 兼容性引用：旧版 codex/gpt-* 引用仍被接受，但新配置不应将它们用作常规提供商/模型引用
• harness ID：codex
• 认证：针对具体请求的已准备 OpenAI 路由/配置文件策略；经过验证的原生认证绑定使用其原生连接
• app-server 请求：OpenClaw 向 Codex 发送裸模型 ID，并让 harness 与原生 app-server 协议通信

Codex 插件是附加性的。在运行时策略未设置或为 auto 时，OpenAI 仅在其提供商拥有的路由契约声明 codex 兼容时才可能选择 Codex：一个精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且没有已编写的请求覆盖。仅 openai/* 前缀永远不会选择 Codex。自定义端点、Completions 适配器和已编写的请求行为保留在 OpenClaw 上。明文官方 HTTP 端点会被拒绝。旧版 codex/gpt-* 引用仍作为兼容性输入。参见 OpenAI 隐式 agent 运行时。

有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参见 Codex Harness。

Codex 插件强制实施 Codex Harness 中记录的最低 app-server 版本。它会检查初始化握手，并阻止较旧、格式错误或无版本的服务器。准入允许启动继续；它并不证明后续运行时或能力操作会成功。