模型发现

Codex 模型目录的发现方式，以及发现失败时会发生什么。本文是 Codex harness 参考 的一部分；各章节迁移位置 列出了所有章节。

模型发现¶

默认情况下，Codex 插件会向 app-server 请求可用模型。模型可用性由 Codex app-server 拥有，因此当 OpenClaw 升级捆绑的 @openai/codex 版本，或部署将 appServer.command 指向不同的 Codex 二进制文件时，列表可能会变化。可用性也可以按账户范围划分。在运行中的网关上使用 /codex models 可查看该 harness 和账户的实时目录。

自动发现和托管搜索模型选择使用可见的选择器条目。具有显式模型选择的有界轮次（包括图像理解、结构化提取、隔离补全和已确定轮次最终化）也会查找 model/list 返回的隐藏条目。模型仍必须被列出并支持所需的输入模态。列出并不证明账户授权。

原生发现从同一作用域的 app-server 客户端读取 model/list 和 account/read。API-key 账户仍保持 API-key 认证；模型列表并不意味着 ChatGPT 传输或端点。选择器就绪状态仅在该原生所有者及其账户/配置观察保持最新时有效。账户缺失、刷新失败、账户/配置变更或已退役客户端都会使原生模型不可用，直到发现再次成功。

使用 Models 页面的 Refresh 操作（models.list 且 view: "all" 和 refresh: true）为所选 agent 发布完整目录。仅 prepared 读取不会启动发现。OpenClaw 之外的原生配置变更需要原生所有者支持的重新加载/重启以及目录刷新；OpenClaw 不会轮询原生 home 文件以检查就绪状态。已创建的 host 路由和显式 profile 选择保留其现有认证和兼容性检查。

原生目录标识符是运行时标识符，而不是隐私标签。使用 broker 拥有的别名的部署必须在启动 app-server 之前提供别名安全的原生目录：model/list 中的 id 和 model 都必须是该别名，并带有所需的 displayName。不同的原生运行时标识符会保留在 OpenClaw 模型参数中。重命名选择器标签不会从请求或会话状态中隐藏这些标识符。

Codex 的启动 model_catalog_json 设置可以提供原生目录；按线程覆盖不会重新加载它。保留完整的模型能力、指令、压缩和审阅者元数据。目录成员资格不会拒绝任意模型覆盖，因此 broker 必须在每个请求上强制允许的 selector。当不应导入任何原生历史时，使用 sessionCatalog.enabled: false 禁用原生会话发现。

自定义端点并不自动成为受支持的 Codex 路由。显式 agentRuntime.id: "codex" 不会绕过 prepared 路由兼容性，也不会绕过模型支持的审批审查所需的受信任端点要求。工作负载 API 密钥也不会提供 ChatGPT 账户身份或订阅刷新。在使用 broker 配合原生 harness 之前，请验证这些契约；不要替换为自定义 provider、移除安全元数据或弱化审查，以使推理冒烟测试通过。

如果发现暂时不可用或超时，订阅路由会使用从捆绑的 OpenAI 模型清单派生的离线提示，并为 gpt-5.5 和 gpt-5.5-pro 的推理强度提供 Codex 插件回退：

离线提示永远不会证明账户授权。已认证发现响应即使不包含可见模型，仍然保持权威；HTTP 401 和 403 会返回空目录，而不是暴露回退模型。

在 plugins.entries.codex.config.discovery 下调整发现设置：

默认预算为 10 秒。它允许 Codex 的五秒远程目录刷新完成，或返回其原生缓存/捆绑目录，同时为传输和账户读取留出时间。设置更短的预算可能会取消该原生回退，导致原生模型在发现成功之前不可用。

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

禁用发现机制，当你希望启动时避免探测 Codex，并且仅使用回退目录时：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}