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 有什麼變化：為什麼它現在更像一個開發環境。