OpenClaw 如何在提供方和模型解析之后选择 harness、失败会如何影响模型回退链,以及为什么 harness 通常随提供方插件一起发布。本文是 Agent harness 插件 参考的一部分。¶
选择策略¶
OpenClaw 在提供方/模型解析之后选择 harness:
- 模型作用域的运行时策略优先。
- 提供方作用域的运行时策略次之。
auto会询问已注册的 harness 是否支持解析出的有效路由。仅仅提供方/模型前缀绝不会选择 harness。- 如果没有已注册的 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 固定项(pin)保留其对话记录所有者;即使在模型选择被锁定时,在插件拥有的具体模型聊天中观察到的 harness 也不会成为固定项。对于具体模型执行,请求或固定项都不会使不兼容的路由变得兼容:harness 必须支持预备事实,声明精确请求的 OpenClaw 回退,否则安全失败(fail closed)。绑定原生会话所有权 会单独标识其经验证的原生连接拥有模型和认证的会话,因此不相关的外部路由元数据不会替换该连接。
下一轮次元数据使用已注册的支持判定,并保留其模型/提供方/会话来源。历史生产者观察结果不会固定下一轮次。Projection 从不加载 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 将不带提供方前缀的模型 id 发送给 Codex,并让 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 版本。它会检查初始化握手,并阻止较旧、格式错误或未版本化的服务器。准入允许启动继续;但这并不证明后续的运行时或能力操作一定会成功。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw