跳轉到主要內容
Codex 是 OpenAI 官方的程式設計智慧體,提供 CLI(終端機)和桌面端,兩者共用同一份 ~/.codex/config.toml。接入 AIHubMix 後,你只需一個 API key 就能呼叫 GLM、Claude、Gemini、DeepSeek 等各家模型,無需綁定單一廠商。本文涵蓋兩種接入方式:基礎方式(固定單一模型,最快上手)與自訂模型方式(用 model_catalog_json 目錄檔案,在 /model 清單裡隨時切換)。

安裝

官網下載(macOS 版本)

https://openai.com/en/codex/

使用命令列安裝

基礎設定

透過設定檔設定

  1. 修改 ~/.codex/config.toml 設定檔,加入以下設定:
  1. 把 env_key 指定的環境變數設為你的 AIHubMix API Key(= 兩側不要有空格):
建議寫進 ~/.zshrc / ~/.bashrc 持久化。在 AIHubMix 主控台 取得 Key。
自訂 provider 預設不會讀取 ~/.codex/auth.json 裡的 OPENAI_API_KEY。Key 必須透過 env_key 指定的環境變數傳入,否則請求不會帶上 Key,會回傳 401。
Codex 0.134.0 起不再支援 profile = "..." 和 [profiles.xxx] 寫法,舊設定在啟動時會報 legacy profile = "..." config is no longer supported。如果你曾依照本文舊版設定過,請刪掉這兩部分,改成上面的寫法。需要多套設定時,把不同的項目寫進 ~/.codex/<名稱>.config.toml(直接寫頂層鍵,不要再套 [profiles.xxx]),再用 codex --profile <名稱> 啟動。
model 可以換成 AIHubMix 上的其他模型 ID。換成 GLM、Claude 等非 OpenAI 模型時,Codex 會提示 Model metadata for ... not found 並改用後備參數,建議改用下文的自訂模型方式。

透過 cc-switch 設定

  1. 執行 CC-Switch,新增供應商。
CC-Switch 新增供應商介面
  1. 在預設清單中選擇「AiHubMix」。
在 CC-Switch 預設清單選擇 AiHubMix
  1. 在「API Key」欄位填入你的金鑰,點選「添加」儲存設定。
在 CC-Switch 填寫 API Key 並儲存
  1. 回到首頁,在供應商清單中選擇「AiHubMix」,點選「啟用」即可使用。
在 CC-Switch 啟用 AiHubMix 供應商

使用 Codex

在終端機中使用

  1. 開啟終端機,切換到你的專案目錄,然後執行 codex 指令。
  1. 依需求設定權限,之後隨時可以輸入 /permissions 調整。
  2. 依需求選擇要使用的模型。底部狀態列會顯示目前模型,輸入 /model 即可切換。
Codex 啟動後底部狀態列顯示目前模型
  1. 輸入自然語言,若正常回應,即表示設定成功。
在 Codex CLI 中以自然語言輸入任務指令

在 Codex 桌面端使用

  1. 開啟 Codex 桌面端,選擇工作目錄。
  2. 在輸入框輸入任務,若正常回應,即表示設定成功。
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、availability_nux、upgrade、supports_reasoning_summaries、support_verbosity、default_verbosity、apply_patch_tool_type、truncation_policy、supports_parallel_tool_calls、experimental_supported_tools。新版 Codex(codex-cli 0.130.0 起,已在 0.162.1 上重新驗證)嚴格解析,少任何一個,整份目錄都會被丟棄並回退到內建目錄,報錯形如 missing field base_instructions,表現就是「/model 裡一個自訂模型都看不到」。所以上面這份範例不能再刪欄位。
關於 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] 段): config.toml 中 model_catalog_json 與 aihubmix provider 設定

第 3 步:設定環境變數

把上面 env_key 指定的環境變數設好(注意 = 兩側不要有空格):
建議寫進 ~/.zshrc / ~/.bashrc 持久化。在 AIHubMix 主控台 取得 Key。

第 4 步:重啟並選擇模型

重啟 Codex App / TUI 讓目錄檔案生效,然後:
輸入 /model 後會列出目錄裡宣告的全部模型,方向鍵選中、Enter 確認: Codex /model 選擇器顯示 AIHubMix 自訂模型清單 選中模型後,/model 還會讓你選推理檔位(effort),依需求選 low / medium / high 即可。 為 claude-opus-5-5 選擇推理檔位

第 5 步:驗證是否生效

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

自訂模型常見問題

  • 啟動時報 legacy profile = "..." config is no longer supported。 Codex 0.134.0 起不再支援 profile = 和 [profiles.xxx]。刪掉這兩部分,依上文「基礎設定」改寫即可。
  • 用舊版指令稿產生過目錄。 舊版指令稿沒有關掉內建範本的 code mode。Codex 更新後排在第一位的內建模型變成了 gpt-6 系列,複製出的目錄能正常解析,但請求裡不帶標準工具清單。請用第 1 步的新指令稿重新產生。
  • /model 裡看不到自訂模型? 按先後順序排查:
    1. 先跑 codex debug models。若報 missing field ...(最常見,缺必填欄位)或 unknown variant ...(欄位名/取值不對),說明整份目錄解析失敗被丟棄,用第 1 步「複製內建範本」指令稿重新產生即可。
    2. 確認 model_catalog_json 寫在 config.toml 根層級,不在 [model_providers.*] 段裡;
    3. 確認 JSON 用的是 snake_case 官方欄位、visibility 為 list;
    4. 如果 codex debug models 已經能看到全部模型,但**桌面端(Desktop App)**裡只剩一兩個、目前模型顯示為「自訂」,這是桌面端的已知 bug。它會在本機目錄之上再按官方模型名單過濾一遍,把非官方模型從選擇器裡刪掉(見 GitHub Issue #19694、#15138)。此時模型其實仍按 config.toml 裡的 model = "..." 正常呼叫(去 AIHubMix 日誌可證實),只是名字顯示不出來。要正確顯示就用終端機 codex CLI / 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 欄位集即可。

參考文章


最後更新:2026-10-15