Codex 发布新模型以后，我现在已经不太会先去改客户端配置了。更稳的做法是先确认官方模型目录里到底有没有这个 slug，再看本地 catalog、客户端版本门槛，最后才检查 Sub2API 有没有把模型继续原样送到上游。

这几个层级很容易混在一起。模型没出现在选择器里，不一定是 Sub2API 的问题；模型能选但请求失败，也不一定是 Codex 本地配置的问题。只要把“显示”“路由”“上游调用”拆开，排查会轻很多。

我现在把这套流程固定成：

OpenAI 官方 models.json
        ↓
确认真实模型 slug
        ↓
同步到本地 codex-models.json
        ↓
检查 minimal_client_version
        ↓
重启 Codex / Desktop
        ↓
Sub2API 白名单与模型映射
        ↓
Responses API 原名透传
        ↓
检查请求模型 / 上游模型

以目前官方目录里的 gpt-6.1-sol 为例，官方条目已经明确包含：

slug: gpt-6.1-sol
display_name: GPT-6.1-Sol
minimal_client_version: 0.153.0
supported_in_api: true

所以第一步永远不是“自己造一个模型名”，而是先确认官方 catalog。

先同步官方完整条目，不要手工只补一个 slug

我的 ~/.codex/config.toml 会指向一个本地模型目录：

model_catalog_json = "~/.codex/codex-models.json"

每次新模型出现，我先备份：

cp ~/.codex/codex-models.json \
  ~/.codex/codex-models.json.bak.$(date +%Y%m%d-%H%M%S)

再拉官方最新 catalog：

curl -fsSL \
  https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json \
  -o /tmp/codex-models-official.json

假设这次要同步的是：

MODEL="gpt-6.1-sol"

先确认官方真的存在：

jq --arg MODEL "$MODEL" '
  .models[]
  | select(.slug == $MODEL)
  | {slug, display_name, minimal_client_version, supported_in_api}
' /tmp/codex-models-official.json

能查到以后，我不会自己手写一个简化条目，而是直接把官方完整对象合并进本地 catalog：

jq --arg MODEL "$MODEL" \
   --slurpfile official /tmp/codex-models-official.json '
  .models = (
    [.models[] | select(.slug != $MODEL)]
    +
    [$official[0].models[] | select(.slug == $MODEL)]
  )
' ~/.codex/codex-models.json > ~/.codex/codex-models.json.new

jq empty ~/.codex/codex-models.json.new &&
mv ~/.codex/codex-models.json.new ~/.codex/codex-models.json

这样保留下来的不只是 slug，还包括 display name、reasoning level、上下文限制、工具能力、版本门槛等元数据。以后官方改字段时，也不需要自己维护一套越来越偏离真实配置的副本。

改完以后要完全退出 Codex / ChatGPT Desktop 再打开。macOS 上我一般直接 ⌘ + Q，确保旧进程和旧 catalog 都被清掉。

模型已经在 catalog 里，为什么还是不显示

这时候先看本地条目：

jq --arg MODEL "$MODEL" '
  .models[]
  | select(.slug == $MODEL)
  | {slug, display_name, minimal_client_version}
' ~/.codex/codex-models.json

如果条目已经存在，重点就变成当前客户端版本和 minimal_client_version。

例如当前官方 gpt-6.1-sol 的 minimal_client_version 是 0.153.0。这类字段本质上就是客户端侧的兼容性门槛：模型元数据已经存在，但低于门槛的客户端不一定应该把它正常暴露出来。

我现在的优先顺序是：

先升级 Codex
    ↓
重启客户端
    ↓
确认模型是否出现
    ↓
仍需兼容性排查时，再临时检查本地门槛

如果只是为了判断“到底是不是本地版本门槛导致隐藏”，可以在备份后临时把单个模型的门槛设成 null：

jq --arg MODEL "$MODEL" '
  (.models[]
    | select(.slug == $MODEL)
    | .minimal_client_version
  ) = null
' ~/.codex/codex-models.json > ~/.codex/codex-models.json.new &&
jq empty ~/.codex/codex-models.json.new &&
mv ~/.codex/codex-models.json.new ~/.codex/codex-models.json

但我不会把这一步当成默认操作。让模型“出现在选择器里”和“当前客户端真的兼容这个模型”是两回事；它更适合排查 UI 隐藏问题，而不是拿来绕过真实兼容性要求。

Codex 能看到模型以后，Sub2API 还要单独过一遍

这也是我以前最容易漏的一层。

本地 Codex 能选中 gpt-6.1-sol，只说明客户端已经知道这个模型名。真正发请求时，还要看 Sub2API 有没有允许它通过。

在我的这套配置里，官方真实模型优先走原名透传：

Codex:    gpt-6.1-sol
             ↓
Sub2API:  gpt-6.1-sol
             ↓
OpenAI:   gpt-6.1-sol

我会依次检查四个地方：

• OpenAI 分组模型白名单里是否允许新模型。
• 账号级模型白名单是否也有限制。
• 模型映射里有没有把新 slug 强制改成旧模型。
• “未知模型默认映射”有没有把新模型兜底到其他 slug。

只要官方已经有真实 slug，我一般就不额外做别名。映射越少，日志越容易看懂，以后排错也越简单。

Codex provider 这里继续保持 Responses API：

wire_api = "responses"

如果你自己真的需要别名，比如：

gpt-6 → gpt-6.1-sol

那就把它当作一条明确的 Sub2API 路由规则来维护，不要让默认兜底规则偷偷替你完成。

最后的验收不是“能看到”，而是上下游模型一致

本地先确认模型存在：

jq -r '.models[].slug' ~/.codex/codex-models.json | grep "$MODEL"

然后实际发一次请求，再看 Sub2API 日志。

我希望看到的是：

请求模型 = gpt-6.1-sol
上游模型 = gpt-6.1-sol
请求成功

只要这三个值能对上，整个链路才算真正完成：

Codex 选择器能看到
        +
请求模型正确
        +
Sub2API 上游模型正确
        +
实际调用成功

如果前面能看到，后面却失败，就按层排：

选择器里没有
→ catalog / 客户端版本

能选择但 Sub2API 拒绝
→ 白名单

请求模型正确，上游模型错误
→ 映射 / 默认兜底

上游模型正确仍失败
→ 上游权限、账号能力或接口兼容

这套方法对我最大的价值，是以后 OpenAI 再发新的 Codex 模型，不需要重新想一遍“到底该改哪里”。先相信官方 catalog，再把本地可见性和 Sub2API 路由分开验证，通常十几分钟就能定位问题。

如果你也在把 Codex 接到自己控制的代理入口，可以继续看 Codex 怎么通过 CLIProxyAPI 反代：Docker 部署、OAuth 登录和客户端配置；如果你想先理解 Codex 现在为什么越来越像一个完整开发环境，可以接着看 新版 Codex 有什么变化：为什么它现在更像一个开发环境。