> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Codex CLI 接入 AIHubMix 教學 > 在 Codex CLI 中接入 AIHubMix：用單一 API key 在 /model 清單自由切換 GLM、Claude、Gemini、DeepSeek 等模型。含 config.toml 設定、model_catalog_json 模型目錄產生指令稿與常見問題排查。 [Codex CLI](https://openai.com/codex/) 是 OpenAI 官方的終端程式設計工具。接入 AIHubMix 後，你只需一個 API key 就能在終端裡呼叫並自由切換 GLM、Claude、Gemini、DeepSeek 等各家模型，無需綁定單一廠商。本文涵蓋兩種接入方式：**基礎方式**（profile + 固定單一模型，最快上手）與**自訂模型方式**（用 `model_catalog_json` 目錄檔案，在 `/model` 清單裡隨時切換）。 # OpenAI Codex CLI 集成 AiHubMix 提供了與 OpenAI [Codex CLI](https://github.com/openai/codex) 的無縫集成，讓你可以在命令列環境中利用先進的 AI 程式助手。透過簡單的配置步驟，即可在終端機中直接使用自然語言執行各種程式和系統操作任務。 使用之前，請先執行以下指令安裝或更新： ```bash theme={null} npm install -g @openai/codex ``` ## 配置步驟 ### 1. 環境變數設定 打開你的 Shell 配置檔（例如 `.zshrc` 或 `.bashrc`），新增以下環境變數： ```bash theme={null} export OPENAI_BASE_URL="https://aihubmix.com/v1" export OPENAI_API_KEY="sk-***" # 替換為你的 AiHubMix API 密鑰 ``` 這裡的 `OPENAI_API_KEY` 應該使用 AiHubMix 的[密鑰](https://aihubmix.com/token)，變數名稱保持為 `OPENAI_API_KEY` 是為了相容 OpenAI 原生客戶端。 ### 2. 套用配置變更 在終端機中執行以下指令，使環境變數生效： ```bash theme={null} source ~/.zshrc # 如果使用 zsh # 或 source ~/.bashrc # 如果使用 bash ``` ### 3. 啟動 Codex CLI 定位到你的專案目錄，然後執行 `codex` 指令： ```bash theme={null} cd /你的專案路徑 codex ``` 在專案目錄執行 codex 指令啟動 Codex CLI ### 4. 使用自然語言執行任務 現在你可以透過自然語言向 Codex CLI 輸入指令，例如： ```bash theme={null} # 範例輸入 講解一下 AnimatedText ``` 在 Codex CLI 中以自然語言輸入任務指令 ## 進階配置 * 預設模型為 `codex-mini-latest`，一個專為編碼任務微調過的 `o4-mini`，可以在 `~/.codex/config.json`修改 * 目前僅支援 OpenAI 家的模型，模型列表可在 [Responses API 文件](https://platform.openai.com/docs/api-reference/responses) 中查看 * 你可以透過編輯 `~/.codex/instructions.md` 檔案來自訂系統提示詞，定制 AI 助手的行為 ## 實用指令參考 ### 幫助指令 ```bash theme={null} codex -h ``` ### 完整指令選項 ```bash theme={null} Usage $ codex [options] Options -h, --help 顯示幫助資訊並退出 -m, --model 指定使用的模型 (預設: codex-mini-latest) -i, --image 包含圖像輸入的檔案路徑 -v, --view 查看之前保存的會話記錄 -q, --quiet 非互動模式，僅列印助手的最終輸出 -a, --approval-mode 覆蓋審批策略: 'suggest', 'auto-edit', 或 'full-auto' --auto-edit 自動批准檔案編輯；仍會提示確認指令 --full-auto 自動批准沙箱環境中的編輯和指令 --no-project-doc 不自動包含倉庫中的 'codex.md' 檔案 --project-doc 包含指定的 Markdown 檔案作為上下文 --full-stdout 不截斷指令輸出的 stdout/stderr 危險選項 --dangerously-auto-approve-everything 跳過所有確認提示並直接執行指令（無沙箱保護） 僅用於臨時本地測試環境 實驗性選項 -f, --full-context 以"完整上下文"模式啟動，將整個倉庫加載到上下文中 並在一次操作中應用批量編輯 僅相容 --model 參數 範例 $ codex "編寫並運行一個列印 ASCII 藝術的 Python 程式" $ codex -q "修復構建問題" ```

在 Codex 中使用自訂模型

Codex 預設只在 `/model` 清單裡顯示 OpenAI 官方模型。如果你想直接從清單中選擇 AIHubMix 上的任意模型（GLM、Claude、Gemini、DeepSeek、Kimi、Qwen……），可以用官方支援的「自訂模型」機制：透過一個本機 JSON 檔案（`model_catalog_json`）宣告可選模型，再用 `[model_providers.aihubmix]` 把請求指向 AIHubMix。 > 官方說明：[Advanced Configuration · OSS mode / local providers](https://developers.openai.com/codex/config-advanced) ### 兩種接入方式 本頁前面「環境變數設定」講的是**基礎方式**，本節講的是**自訂模型方式**，差別如下，依需求選擇： | | 基礎方式（profile + 單模型） | 自訂模型方式（本節） | | ---- | ------------------------------------- | -------------------------------- | | 設定內容 | 在 `config.toml` 裡寫死一個 `model = "xxx"` | 額外維護一個 `model_catalog_json` 目錄檔案 | | 切換模型 | 改設定檔後重啟 | 直接在 `/model` 清單裡點選，隨時切 | | 適合場景 | 長期固定用某一個模型 | 想在多個模型間頻繁比較 / 切換 | | 複雜度 | 低 | 中 | 整體流程只有 4 步：**產生目錄檔案 → 改 `config.toml` → 設環境變數 → 重啟選模型**。 ### 第 1 步：產生模型目錄檔案 目錄檔案是一個 `{ "models": [ ... ] }` 結構，陣列裡每個元素描述一個可在 `/model` 裡選擇的模型。下面先用**一個固定模型**講清欄位，再給**批次產生前 30 名**的指令稿。 #### 1.1 先理解格式：固定一個模型 下面是一份**已驗證可被 Codex 解析**的最小完整目錄（只含 `glm-5.2` 一個模型）。直接存成 `~/.codex/model-catalogs/custom-models.json` 就能用；想要更多模型，就往 `models` 陣列裡繼續追加同樣結構的條目。 ```json theme={null} { "models": [ { "slug": "glm-5.2", "display_name": "GLM 5.2", "description": "GLM 5.2 (via AIHubMix)", "context_window": 1000000, "max_context_window": 1000000, "supported_reasoning_levels": [ { "effort": "low", "description": "Fast responses" }, { "effort": "medium", "description": "Balanced" }, { "effort": "high", "description": "Deeper reasoning" } ], "shell_type": "shell_command", "visibility": "list", "supported_in_api": true, "priority": 0, "availability_nux": null, "upgrade": null, "base_instructions": "You are Codex, a coding agent.", "supports_reasoning_summaries": true, "support_verbosity": false, "default_verbosity": null, "apply_patch_tool_type": null, "truncation_policy": { "mode": "tokens", "limit": 10000 }, "supports_parallel_tool_calls": true, "experimental_supported_tools": [] } ] } ``` 欄位說明（你通常會改的幾個）： | 欄位 | 作用 | 來自介面 | | --------------------------------------- | ----------------------------------------- | ---------------- | | `slug` | 模型 ID，Codex 用它發起請求，必須與介面回傳的 `model_id` 一致 | `model_id` | | `display_name` | `/model` 清單裡顯示的名稱 | `model_name` | | `context_window` / `max_context_window` | 上下文視窗。**不寫會回退到很小的保守預設值**，建議按介面真實值填 | `context_length` | | `supported_reasoning_levels` | 推理檔位，切換模型後用 `/model` 還能選 effort | — | | `visibility` | 設為 `list` 才會出現在選擇器中 | — | | `priority` | 清單排序，數字越小越靠前 | — | **其餘欄位是必填且值固定的**：`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` 上驗證）嚴格解析，**少任何一個，整份目錄都會被丟棄**並回退到內建目錄，報錯形如 `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 模型列表介面](https://aihubmix.com/api/v1/models?type=llm) 的前 30 個 LLM 一次性寫進目錄，用下面的指令稿——它**以一個內建模型為範本複製**，必填欄位（含正確的 `base_instructions`）天生齊全，跨 Codex 版本都不缺。需要 `curl`、`python3` 和已安裝的 `codex` CLI： ```bash theme={null} mkdir -p ~/.codex/model-catalogs # 1) 取一个内置模型当模板：它自带 base_instructions 等全部必填字段 codex debug models --bundled > /tmp/_tpl.json # 2) 拉 AIHubMix 模型列表 curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json # 3) 克隆模板逐个生成条目，只覆盖每个模型独有的字段 python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json import json, sys tpl = json.load(open("/tmp/_tpl.json"))["models"][0] # 任意内置模型当模板 api = json.load(open("/tmp/_aihubmix.json"))["data"] # 跳过图像生成模型（types 含 image_generation），再取前 30 api = [m for m in api if "image_generation" not in (m.get("types") or "")][:30] out = [] for i, m in enumerate(api): e = dict(tpl) # 克隆模板的全部字段 ctx = m.get("context_length") or 200000 e["slug"] = m["model_id"] # 必须与接口 model_id 一致 e["display_name"] = m.get("model_name") or m["model_id"] e["description"] = (m.get("model_name") or m["model_id"]) + " (via AIHubMix)" e["context_window"] = ctx e["max_context_window"] = ctx e["visibility"] = "list" e["supported_in_api"] = True e["priority"] = i e["availability_nux"] = None e["upgrade"] = None out.append(e) json.dump({"models": out}, sys.stdout, ensure_ascii=False, indent=2) PY ``` 指令稿只覆蓋每個模型獨有的欄位（`slug`、`display_name`、`description`、`context_window` 等），其餘必填欄位全部從內建範本複製而來——這正是 1.1 裡那套欄位，只是 `base_instructions` 用的是完整官方提示詞。 > 產生的檔案較大（每個條目都含完整 `base_instructions`，約 1～2 MB），屬正常現象。執行後用 `codex debug models` 驗證能否被正確解析（見第 5 步）。 > 指令稿裡那行 `image_generation` 過濾是有意保留的：`type=llm` 的回傳中有極少數模型同時帶 `image_generation` 標籤（如 `gpt-image-2`），不適合對話，指令稿會自動跳過後再取前 30。 ### 第 2 步：修改 `config.toml` 編輯 `~/.codex/config.toml`，在**根層級**加上 `model_catalog_json`，並定義 `aihubmix` provider： ```toml theme={null} # ⚠️ model_catalog_json 必须写在根级别，不能放进 [model_providers.*] 段里 model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` `wire_api = "responses"` 是關鍵，**漏寫或寫成 `chat` 都連不上**。Codex 新版只走 OpenAI 的 Responses API（`/v1/responses`），AIHubMix 已原生相容 Responses API，所以直接指向 `https://aihubmix.com/v1` 即可，無需自建轉換代理。 如果想順便指定**預設模型**和**預設推理檔位**（啟動時直接用，不用每次手點），可以用這份更完整的設定： ```toml theme={null} model = "glm-5.2" # 启动默认模型，需在目录文件里存在 model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" model_reasoning_effort = "high" # 默认推理档位：minimal / low / medium / high [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` 設好後 `config.toml` 大致如下（紅框為本步的關鍵項：根層級的 `model` / `model_provider` / `model_catalog_json`，以及 `[model_providers.aihubmix]` 段）： config.toml 中 model_catalog_json 與 aihubmix provider 設定 ### 第 3 步：設定環境變數 把上面 `env_key` 指定的環境變數設好（注意 `=` 兩側不要有空格）： ```bash theme={null} export AIHUBMIX_API_KEY=sk-xxx ``` 建議寫進 `~/.zshrc` / `~/.bashrc` 持久化。在 [AIHubMix 主控台](https://aihubmix.com/token) 取得 Key。 ### 第 4 步：重啟並選擇模型 重啟 Codex App / TUI 讓目錄檔案生效，然後： ```bash theme={null} codex # 在交互界面里输入 /model，即可看到上一步声明的 30 个模型并切换 ``` 輸入 `/model` 後會列出目錄裡宣告的全部模型，方向鍵選中、Enter 確認： Codex /model 選擇器顯示 AIHubMix 自訂模型清單 選中模型後，`/model` 還會讓你選推理檔位（effort），依需求選 `low` / `medium` / `high` 即可。 ### 第 5 步：驗證是否生效 1. 進入 Codex 後輸入 `/model`，確認能看到目錄裡宣告的模型，並切到其中一個（如 `glm-5.2`）。 2. 隨便提一個問題驗證鏈路打通。注意：**不要靠「你是哪個模型」來判斷**——`base_instructions` 裡寫著「You are Codex... based on GPT-5」，所有模型都會照此自稱 GPT-5，問了也分辨不出真實模型。要確認實際呼叫的模型，登入 [AIHubMix 主控台](https://aihubmix.com/token)「日誌」頁看那條請求記錄的 `model_id`，這才是真相。 切換成功後頂部會提示 `Model changed to ...`，底部狀態列也會顯示目前模型與上下文視窗（下圖切到了 `glm-5.2`，視窗 258K）： Codex 切換到 glm-5.2 後的工作階段與底部狀態列 ## 自訂模型常見問題 * **`/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：它會在本機目錄之上再套一層官方 slug 白名單過濾，把非官方模型從選擇器裡刪掉（見 GitHub Issue [#19694](https://github.com/openai/codex/issues/19694)、[#15138](https://github.com/openai/codex/issues/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” 重連。** 部分網路/代理環境下 WebSocket（WSS）不通，可在 provider 段加 `supports_websockets = false` 強制走 HTTP。 * **解析報 `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](https://developers.openai.com/codex/config-advanced) ｜ [Configuration Reference](https://developers.openai.com/codex/config-reference) * 官方內建目錄格式參考：[codex-rs/models-manager/models.json](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) * 社群指南：[Codex config.toml：6 行接入任意自訂 provider](https://www.morphllm.com/codex-provider-configuration) *** 最後更新：2026-06-25