~/.codex/config.toml。接入 AIHubMix 後,你只需一個 API key 就能呼叫 GLM、Claude、Gemini、DeepSeek 等各家模型,無需綁定單一廠商。本文涵蓋兩種接入方式:基礎方式(固定單一模型,最快上手)與自訂模型方式(用 model_catalog_json 目錄檔案,在 /model 清單裡隨時切換)。
安裝
官網下載(macOS 版本)
https://openai.com/en/codex/使用命令列安裝
基礎設定
透過設定檔設定
- 修改
~/.codex/config.toml設定檔,加入以下設定:
- 把
env_key指定的環境變數設為你的 AIHubMix API Key(=兩側不要有空格):
~/.zshrc / ~/.bashrc 持久化。在 AIHubMix 主控台 取得 Key。
自訂 provider 預設不會讀取
~/.codex/auth.json 裡的 OPENAI_API_KEY。Key 必須透過 env_key 指定的環境變數傳入,否則請求不會帶上 Key,會回傳 401。model 可以換成 AIHubMix 上的其他模型 ID。換成 GLM、Claude 等非 OpenAI 模型時,Codex 會提示 Model metadata for ... not found 並改用後備參數,建議改用下文的自訂模型方式。
透過 cc-switch 設定
- 執行 CC-Switch,新增供應商。

- 在預設清單中選擇「AiHubMix」。

- 在「API Key」欄位填入你的金鑰,點選「添加」儲存設定。

- 回到首頁,在供應商清單中選擇「AiHubMix」,點選「啟用」即可使用。

使用 Codex
在終端機中使用
- 開啟終端機,切換到你的專案目錄,然後執行
codex指令。
-
依需求設定權限,之後隨時可以輸入
/permissions調整。 -
依需求選擇要使用的模型。底部狀態列會顯示目前模型,輸入
/model即可切換。

- 輸入自然語言,若正常回應,即表示設定成功。

在 Codex 桌面端使用
- 開啟 Codex 桌面端,選擇工作目錄。
- 在輸入框輸入任務,若正常回應,即表示設定成功。

實用指令參考
完整選項以codex --help 的輸出為準,常用的有:
在 Codex 中使用自訂模型
Codex 預設只在/model 清單裡顯示 OpenAI 官方模型。如果你想直接從清單中選擇 AIHubMix 上的任意模型(GLM、Claude、Gemini、DeepSeek、Kimi、Qwen……),可以用官方支援的「自訂模型」機制:透過一個本機 JSON 檔案(model_catalog_json)宣告可選模型,再用 [model_providers.aihubmix] 把請求指向 AIHubMix。
官方說明:Advanced Configuration · Custom model providers
兩種接入方式
本頁前面「基礎設定」講的是基礎方式,本節講的是自訂模型方式,差別如下,依需求選擇:
整體流程只有 4 步:產生目錄檔案 → 改
config.toml → 設環境變數 → 重啟選模型。
第 1 步:產生模型目錄檔案
目錄檔案是一個{ "models": [ ... ] } 結構,陣列裡每個元素描述一個可在 /model 裡選擇的模型。下面先用一個固定模型講清欄位,再給批次產生前 30 名的指令稿。
1.1 先理解格式:固定一個模型
下面是一份已驗證可被 Codex 解析的最小完整目錄(只含glm-5.2 一個模型)。直接存成 ~/.codex/model-catalogs/custom-models.json 就能用;想要更多模型,就往 models 陣列裡繼續追加同樣結構的條目。
關於
base_instructions:它是該模型的系統提示詞。範例裡用一句話佔位,模型能正常跑;想要最接近原生 Codex 的程式表現,把它換成 codex debug models --bundled 裡任一內建模型的完整 base_instructions(下一節的批次指令稿就是這麼做的)。
官方目錄用 snake_case 欄位(
display_name、supported_in_api、visibility)。兩類錯誤都會讓整份目錄被丟棄、/model 裡看不到模型:缺必填欄位會報 missing field ...;用了 displayName、hidden 這類 camelCase 舊格式或不認識的取值會報 unknown variant ...。以本文這套欄位為準即可避開。1.2 批次產生前 30 名
手寫多個條目容易漏欄位。要把 AIHubMix 模型列表介面 的前 30 個 LLM 一次性寫進目錄,用下面的指令稿。它以一個內建模型為範本複製,必填欄位(含正確的base_instructions)天生齊全,跨 Codex 版本都不缺。需要 curl、python3 和已安裝的 codex CLI:
slug、display_name、description、context_window 等),並把推理檔位統一為 low / medium / high,其餘必填欄位全部從內建範本複製而來,也就是 1.1 裡那套欄位,只是 base_instructions 用的是完整官方提示詞。
產生的檔案較大(每個條目都含完整base_instructions,約 1~2 MB),屬正常現象。執行後用codex debug models驗證能否被正確解析(見第 5 步)。
指令稿裡那行image_generation過濾是有意保留的:type=llm的回傳中有極少數模型同時帶image_generation標籤(如gemini-3.1-flash-image),不適合對話,指令稿會自動跳過後再取前 30。
第 2 步:修改 config.toml
編輯 ~/.codex/config.toml,在根層級加上 model_catalog_json,並定義 aihubmix provider:
wire_api 現在只支援 responses(不寫時預設也是它),chat 已不再支援。Codex 只走 OpenAI 的 Responses API(/v1/responses),AIHubMix 已原生相容 Responses API,所以直接指向 https://aihubmix.com/v1 即可,無需自建轉換代理。model 要填目錄裡有的模型。用 1.1 的手寫目錄就填 glm-5.2;用 1.2 的腳本時,目錄取的是介面目前排名前 30 的模型,名單會變,先執行 codex debug models | grep -o '"slug":"[^"]*"' 看看有哪些,再從中挑一個(本文用的是 claude-opus-5-5)。
設好後 config.toml 大致如下(紅框為本步的關鍵項:根層級的 model / model_provider / model_catalog_json,以及 [model_providers.aihubmix] 段):

第 3 步:設定環境變數
把上面env_key 指定的環境變數設好(注意 = 兩側不要有空格):
~/.zshrc / ~/.bashrc 持久化。在 AIHubMix 主控台 取得 Key。
第 4 步:重啟並選擇模型
重啟 Codex App / TUI 讓目錄檔案生效,然後:/model 後會列出目錄裡宣告的全部模型,方向鍵選中、Enter 確認:

/model 還會讓你選推理檔位(effort),依需求選 low / medium / high 即可。

第 5 步:驗證是否生效
- 進入 Codex 後輸入
/model,確認能看到目錄裡宣告的模型,並切到其中一個(如claude-opus-5-5)。 - 隨便提一個問題驗證鏈路打通。注意:不要靠「你是哪個模型」來判斷:
base_instructions裡寫著「You are Codex… based on GPT-5」,所有模型都會照此自稱 GPT-5,問了也分辨不出真實模型。要確認實際呼叫的模型,登入 AIHubMix 主控台「日誌」頁看那條請求記錄的model_id,這才是真相。
Model changed to ...,底部狀態列也會顯示目前模型與上下文視窗(下圖切到了 claude-opus-5-5,視窗 950K):

自訂模型常見問題
-
啟動時報
legacy profile = "..." config is no longer supported。 Codex 0.134.0 起不再支援profile =和[profiles.xxx]。刪掉這兩部分,依上文「基礎設定」改寫即可。 - 用舊版指令稿產生過目錄。 舊版指令稿沒有關掉內建範本的 code mode。Codex 更新後排在第一位的內建模型變成了 gpt-6 系列,複製出的目錄能正常解析,但請求裡不帶標準工具清單。請用第 1 步的新指令稿重新產生。
-
/model裡看不到自訂模型? 按先後順序排查:- 先跑
codex debug models。若報missing field ...(最常見,缺必填欄位)或unknown variant ...(欄位名/取值不對),說明整份目錄解析失敗被丟棄,用第 1 步「複製內建範本」指令稿重新產生即可。 - 確認
model_catalog_json寫在config.toml根層級,不在[model_providers.*]段裡; - 確認 JSON 用的是 snake_case 官方欄位、
visibility為list; - 如果
codex debug models已經能看到全部模型,但**桌面端(Desktop App)**裡只剩一兩個、目前模型顯示為「自訂」,這是桌面端的已知 bug。它會在本機目錄之上再按官方模型名單過濾一遍,把非官方模型從選擇器裡刪掉(見 GitHub Issue #19694、#15138)。此時模型其實仍按config.toml裡的model = "..."正常呼叫(去 AIHubMix 日誌可證實),只是名字顯示不出來。要正確顯示就用終端機codexCLI / TUI;桌面端只能直接在config.toml裡寫死model = "你要的模型",等官方修復。
- 先跑
-
目錄是「替換」不是「合併」。
model_catalog_json會替換整個模型清單,而不是追加(實測:目錄裡只放 2 個模型,codex debug models就只剩這 2 個,內建的gpt-5.x全部消失)。如果你兩類都想要,就把它們一併寫進自訂目錄。 -
請求報協定錯誤 / 連不上。 多半是 provider 的
base_url或wire_api沒配對。AIHubMix 必須wire_api = "responses"+base_url = "https://aihubmix.com/v1"。若你接的是只支援 Chat Completions 的第三方,則需要本機轉換代理,AIHubMix 用戶無需此步。 -
一直 “Reconnecting”,最後報錯。 先看最後一行報錯。
401 Unauthorized表示請求沒帶上 Key:確認 provider 段寫了env_key,且對應的環境變數在啟動 Codex 的終端機裡已生效(開新的終端機或執行source ~/.zshrc)。Key 只寫在auth.json裡不會被自訂 provider 使用。 -
解析報
missing field ...(如missing field base_instructions)。 條目缺了必填欄位。新版 Codex 嚴格解析,base_instructions、availability_nux、upgrade、supports_reasoning_summaries、support_verbosity、default_verbosity、apply_patch_tool_type、truncation_policy、supports_parallel_tool_calls、experimental_supported_tools等都必須存在。用第 1 步「複製內建範本」指令稿可一次性補齊。 -
解析報
unknown variant。 目錄 JSON 裡有 Codex 不認識的欄位名或取值(常見於displayName/hidden等 camelCase 舊格式)。改用本文的 snake_case 欄位集即可。
參考文章
- 官方文件:Advanced Configuration | Configuration Reference
- 官方內建目錄格式參考:codex-rs/models-manager/models.json
- 社群指南:Codex config.toml:6 行接入任意自訂 provider
最後更新:2026-10-15