# Codex 新模型不顯示怎麼辦：同步官方 Model Catalog + Sub2API 原名透傳

> Canonical: https://vxi.me/zh-tw/posts/codex-new-model-catalog-sub2api/
> Locale: zh-tw
> Published: 2026-10-05
> Updated: 2026-10-05
> Markdown: https://vxi.me/zh-tw/posts/codex-new-model-catalog-sub2api.md

Codex 釋出新模型以後，我現在已經不太會先去改客戶端設定了。更穩的做法是先確認官方模型目錄裡到底有沒有這個 slug，再看本地 catalog、客戶端版本門檻，最後才檢查 Sub2API 有沒有把模型繼續原樣送到上游。

這幾個層級很容易混在一起。模型沒出現在選擇器裡，不一定是 Sub2API 的問題；模型能選但請求失敗，也不一定是 Codex 本地設定的問題。只要把“顯示”“路由”“上游呼叫”拆開，排查會輕很多。

我現在把這套流程固定成：

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

以目前官方目錄裡的 `gpt-6.1-sol` 為例，官方條目已經明確包含：

```text
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` 會指向一個本地模型目錄：

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

每次新模型出現，我先備份：

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

再拉官方最新 catalog：

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

假設這次要同步的是：

```bash
MODEL="gpt-6.1-sol"
```

先確認官方真的存在：

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

能查到以後，我不會自己手寫一個簡化條目，而是直接把官方完整物件合併進本地 catalog：

```bash
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 裡，為什麼還是不顯示

這時候先看本地條目：

```bash
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`。這類欄位本質上就是客戶端側的相容性門檻：模型後設資料已經存在，但低於門檻的客戶端不一定應該把它正常暴露出來。

我現在的優先順序是：

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

如果只是為了判斷“到底是不是本地版本門檻導致隱藏”，可以在備份後臨時把單個模型的門檻設成 `null`：

```bash
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 有沒有允許它透過。

在我的這套設定裡，官方真實模型優先走原名透傳：

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

我會依次檢查四個地方：

- OpenAI 分組模型白名單裡是否允許新模型。
- 帳號級模型白名單是否也有限制。
- 模型對映裡有沒有把新 slug 強制改成舊模型。
- “未知模型預設對映”有沒有把新模型兜底到其他 slug。

只要官方已經有真實 slug，我一般就不額外做別名。對映越少，日誌越容易看懂，以後排錯也越簡單。

Codex provider 這裡繼續保持 Responses API：

```toml
wire_api = "responses"
```

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

```text
gpt-6 → gpt-6.1-sol
```

那就把它當作一條明確的 Sub2API 路由規則來維護，不要讓預設兜底規則偷偷替你完成。

## 最後的驗收不是“能看到”，而是上下游模型一致

本地先確認模型存在：

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

然後實際發一次請求，再看 Sub2API 日誌。

我希望看到的是：

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

只要這三個值能對上，整個鏈路才算真正完成：

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

如果前面能看到，後面卻失敗，就按層排：

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

能选择但 Sub2API 拒绝
→ 白名单

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

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

這套方法對我最大的價值，是以後 OpenAI 再發新的 Codex 模型，不需要重新想一遍“到底該改哪裡”。先相信官方 catalog，再把本地可見性和 Sub2API 路由分開驗證，通常十幾分鍾就能定位問題。

如果你也在把 Codex 接到自己控制的代理入口，可以繼續看 [Codex 怎麼透過 CLIProxyAPI 反代：Docker 部署、OAuth 登入和客戶端設定](/posts/cliproxyapi-codex-docker-proxy/)；如果你想先理解 Codex 現在為什麼越來越像一個完整開發環境，可以接著看 [新版 Codex 有什麼變化：為什麼它現在更像一個開發環境](/posts/what-changed-in-the-new-codex/)。