跳轉到主要內容
Codex CLI 是 OpenAI 官方的終端程式設計工具。接入 AIHubMix 後，你只需一個 API key 就能在終端裡呼叫並自由切換 GLM、Claude、Gemini、DeepSeek 等各家模型，無需綁定單一廠商。本文涵蓋兩種接入方式：基礎方式（profile + 固定單一模型，最快上手）與自訂模型方式（用 model_catalog_json 目錄檔案，在 /model 清單裡隨時切換）。

​
OpenAI Codex CLI 集成

AiHubMix 提供了與 OpenAI Codex CLI 的無縫集成，讓你可以在命令列環境中利用先進的 AI 程式助手。透過簡單的配置步驟，即可在終端機中直接使用自然語言執行各種程式和系統操作任務。 使用之前，請先執行以下指令安裝或更新： 
npm install -g @openai/codex

​
配置步驟

​
1. 環境變數設定

打開你的 Shell 配置檔（例如 .zshrc 或 .bashrc），新增以下環境變數： 
export OPENAI_BASE_URL="https://aihubmix.com/v1"
export OPENAI_API_KEY="sk-***" # 替換為你的 AiHubMix API 密鑰
這裡的 OPENAI_API_KEY 應該使用 AiHubMix 的密鑰，變數名稱保持為 OPENAI_API_KEY 是為了相容 OpenAI 原生客戶端。

​
2. 套用配置變更

在終端機中執行以下指令，使環境變數生效： 
source ~/.zshrc  # 如果使用 zsh
# 或
source ~/.bashrc  # 如果使用 bash

​
3. 啟動 Codex CLI

定位到你的專案目錄，然後執行 codex 指令： 
cd /你的專案路徑
codex
在專案目錄執行 codex 指令啟動 Codex CLI

​
4. 使用自然語言執行任務

現在你可以透過自然語言向 Codex CLI 輸入指令，例如： 
# 範例輸入
講解一下 AnimatedText
在 Codex CLI 中以自然語言輸入任務指令

​
進階配置

  • 預設模型為 codex-mini-latest，一個專為編碼任務微調過的 o4-mini，可以在 ~/.codex/config.json修改
  • 目前僅支援 OpenAI 家的模型，模型列表可在 Responses API 文件 中查看
  • 你可以透過編輯 ~/.codex/instructions.md 檔案來自訂系統提示詞，定制 AI 助手的行為

​
實用指令參考

​
幫助指令

codex -h

​
完整指令選項

Usage
  $ codex [options] <prompt>

Options
  -h, --help                 顯示幫助資訊並退出
  -m, --model <model>        指定使用的模型 (預設: codex-mini-latest)
  -i, --image <path>         包含圖像輸入的檔案路徑
  -v, --view <rollout>       查看之前保存的會話記錄
  -q, --quiet                非互動模式，僅列印助手的最終輸出
  -a, --approval-mode <mode> 覆蓋審批策略: 'suggest', 'auto-edit', 或 'full-auto'

  --auto-edit                自動批准檔案編輯；仍會提示確認指令
  --full-auto                自動批准沙箱環境中的編輯和指令

  --no-project-doc           不自動包含倉庫中的 'codex.md' 檔案
  --project-doc <file>       包含指定的 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

​
兩種接入方式

本頁前面「環境變數設定」講的是基礎方式，本節講的是自訂模型方式，差別如下，依需求選擇：
基礎方式（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 陣列裡繼續追加同樣結構的條目。 
{
  "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 模型列表介面 的前 30 個 LLM 一次性寫進目錄，用下面的指令稿——它以一個內建模型為範本複製，必填欄位（含正確的 base_instructions）天生齊全，跨 Codex 版本都不缺。需要 curl、python3 和已安裝的 codex CLI： 
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： 
# ⚠️ 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 即可，無需自建轉換代理。
如果想順便指定預設模型和預設推理檔位（啟動時直接用，不用每次手點），可以用這份更完整的設定： 
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 指定的環境變數設好（注意 = 兩側不要有空格）： 
export AIHUBMIX_API_KEY=sk-xxx
建議寫進 ~/.zshrc / ~/.bashrc 持久化。在 AIHubMix 主控台 取得 Key。

​
第 4 步：重啟並選擇模型

重啟 Codex App / TUI 讓目錄檔案生效，然後： 
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 主控台「日誌」頁看那條請求記錄的 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、#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 欄位集即可。

​
參考文章

最後更新：2026-06-25