跳转至

模型发现

Codex 模型目录如何被发现,以及发现失败时会发生什么。本文是 Codex harness 参考 的一部分;每个章节迁移到了哪里 列出了所有章节。

模型发现

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

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

原生发现是按需驱动的。网关启动时会发布已配置的模型提示,而不会为每个 agent 启动 app-server。打开某个 agent 的模型选择器或目录、创建 Codex 会话、运行轮次,或请求原生 auth/status 信息时,会在需要时启动该 agent 的 client。在发现之前,原生账户就绪状态未知;已配置的提示并不是已登录的证明。首次使用空闲 agent 可能需要几秒钟进行冷启动。

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

没有拥有工作的 client 会在 30 秒空闲后退役。该宽限期内到达的请求会复用它。活动请求、轮次、保留中或正在释放的线程、原生子进程、后台终端和临时历史会保留其 client,直到其所有者释放它。现有的 warm-session executor 和线程保留策略仍然有效。Client 和账户按 agent home 保持隔离。

使用模型页面的 刷新 操作(models.list,其中 view: "all" 且 refresh: true)为所选 agent 发布完整目录。仅 Prepared 的读取不会启动发现。OpenClaw 之外的原生配置变更需要原生所有者支持的 reload/restart 以及目录刷新;OpenClaw 不会轮询原生 home 文件以检查就绪状态。已编写的 host 路由和显式 profile 选择保留其现有 auth 和兼容性检查。

对于 Codex runtime,composer 仅在已认证账户发现为所选模型、账户、路由和 runtime 宣传该服务层级时显示 Ultrafast。 OpenAI provider 现有的按账户范围划分的发现提供此观察;静态目录提示和原生 app-server 的回退列表不会建立访问权限。选择托管个人账户会通过相同的 provider 发现路径准备该账户的目录,而不改变共享 auth 顺序。仅 Prepared 的读取不会启动发现。账户变更、发现失败和已退役 generation 不能复用其他账户的层级支持。

没有托管发现凭据的仅原生账户、无法使用模型发现的 token-sharing auth,以及没有显式服务层级元数据的目录,都会使此能力处于未知状态。在这些情况下,composer 会隐藏 Ultrafast,而不是提供一个禁用选项。发现支持描述的是可用性,并不保证上游请求会获得该层级。

嵌入式 OpenClaw runtime 使用可用的 API-key OpenAI Responses 路由来提供 Ultrafast,无需目录元数据,无论密钥来自 auth profile、环境变量还是 provider 配置(包括 SecretRefs)。这仍然受所选凭据和路由观察到的 provider 降级影响;参见 Fast mode。 使用 API-key 认证的 Codex-runtime Ultrafast 仍需要原生目录(包括固定的 model_catalog_json)列出该模型的层级。

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

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

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

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

模型 ID 显示名称 推理强度
gpt-5.6-sol GPT-5.6 Sol low, medium, high, xhigh, max
gpt-5.5 GPT-5.5 low, medium, high, xhigh
gpt-5.5-pro gpt-5.5-pro medium, high, xhigh

离线提示永远不会证明账户权限。经过身份验证的发现响应仍然具有权威性,即使其中没有可见模型;HTTP 401 和 403 会返回空目录,而不是暴露回退模型。

Note

当前捆绑的测试框架是 @openai/codex 0.160.0。在 2026 年 10 月 2 日,针对该 app-server 在隔离的、未身份验证的 Codex 主目录中执行 model/list 检查,返回了以下可见的捆绑目录条目:

模型 ID 输入模态 推理强度 默认强度
gpt-6.1-sol text, image low, medium, high, xhigh, max, ultra low
gpt-6-astra text, image low, medium, high, xhigh, max, ultra low
gpt-6-sol text, image low, medium, high, xhigh, max, ultra medium
gpt-6-luna text, image low, medium, high, xhigh, max medium
gpt-5.6-sol text, image low, medium, high, xhigh, max, ultra low
gpt-5.6-terra text, image low, medium, high, xhigh, max, ultra medium
gpt-5.6-luna text, image low, medium, high, xhigh, max medium
gpt-5.5 text, image low, medium, high, xhigh medium

gpt-6.1-sol 条目还将 priority 服务层级声明为 Fast。此捆绑 快照不会确立账户访问权限:经过身份验证的目录可能不同, 并且原生发现仍需要当前账户。在启动或升级网关后运行 /codex models, 以查看您账户的实际公开选择器。 现有已配置的模型选择保持不变。

OpenClaw 推理控件会保留受支持的原生级别,包括 ultra。 Codex 负责 Ultra 的主动委托和特定于模型的推理强度; Platform API 强度元数据不会降级所选运行时模式。 隐藏模型也可能出现在 app-server 目录中,用于内部或 专用流程,而无需成为常规模型选择器选项。

在 plugins.entries.codex.config.discovery 下调整发现:

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

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

禁用发现,以避免即使在按需时也进行原生模型/账户目录检查:

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw