近期 Codex CLI 版本更新導致舊版 `config.toml` 設定檔部分內容失效。本文提供適用於 Codex CLI 0.162.1 版的有效配置範例，特別針對自訂供應商的設定。文中也詳細解釋了編輯設定檔後應執行的檢查，以及各種常見錯誤訊息及其解決方案。
近期發布的 Codex CLI 版本不再支援舊版 config.toml 設定檔中的部分內容。例如，profile = "..."、wire_api = "chat" 或 approval_policy = "untrusted" 等設定現在會導致啟動失敗，而其他一些錯誤則會默默地失效。這些問題通常源於使用者複製了 2026 年初撰寫的舊版指南中的配置。
本文將提供適用於 Codex CLI 0.162.1 版、並支援自訂供應商的有效配置。內容包含編輯設定檔後應執行的檢查，以及當設定出錯時 Codex 會顯示的確切錯誤訊息。這些資訊已於 2026 年 10 月 19 日根據 OpenAI 的配置文件進行驗證。範例中使用的供應商是 AIHubMix，任何支援 OpenAI Responses API 的閘道器（gateway）都可依相同方式配置。
簡而言之，設定檔路徑為 ~/.codex/config.toml（Windows 系統為 C:\Users\<你>\.codex\config.toml），Codex 只會在啟動時讀取此檔案。供應商設定需包含 base_url、wire_api = "responses"（唯一接受的值），以及 env_key（指定儲存 API 金鑰的環境變數名稱）。
設定檔現在不再支援 config.toml 內部的 [profiles.x] 表格，而是將每個設定檔獨立儲存為 ~/.codex/<名稱>.config.toml，並透過 --profile <名稱> 選項來選取。專案層級的 .codex/config.toml 僅適用於受信任的專案，且不能設定 model_provider。
代理伺服器（Proxy）沒有專屬的設定金鑰，Codex 會遵循 HTTPS_PROXY、ALL_PROXY 和 NO_PROXY 等環境變數。
首先，您需要安裝 Codex CLI（透過 npm install -g @openai/codex 指令），本文測試版本為 0.162.1。此外，您還需要一個供應商的 API 金鑰，例如 AIHubMix 的金鑰可從其控制台取得。
以下是 ~/.codex/config.toml 的內容範例：
```
model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"
[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"
```
對於 macOS 或 Linux 系統，請將 API 金鑰設定加入 ~/.zshrc 或 ~/.bashrc 檔案中，然後開啟一個新的終端機視窗，例如：export AIHUBMIX_API_KEY = sk-...。Windows PowerShell 使用者則可在設定後開啟新的終端機，例如：setx AIHUBMIX_API_KEY "sk-..."。
大多數失敗都源於以下三條規則：model_provider 的值必須與表格名稱相符，且表格名稱不能是 openai、ollama 或 lmstudio，因為這些是 Codex 內建供應商的保留名稱。env_key 應為環境變數的名稱，而非實際的 API 金鑰。
透過 codex login 儲存在 auth.json 中的金鑰，絕不會傳送給自訂供應商。頂層（top-level）金鑰必須放在第一個 [table] 行之上，因為在 TOML 語法中，表格標頭之後的所有內容都屬於該表格。
您可以執行 codex exec "say ok" 來發送一個非互動式請求，或使用 codex doctor 檢查安裝、配置和認證狀態。codex exec 在發送請求前會印出實際生效的設定，包括 model:、provider:、approval:、sandbox: 和 reasoning effort:。
這個標頭是快速確認哪些值實際生效的最佳方式。請注意，即使設定中包含 on-request，codex exec 在測試中仍會回報 approval: never，因為非互動式執行沒有使用者可以詢問。
設定檔（profile）是一個僅包含不同金鑰的檔案，這些金鑰寫在頂層。例如，~/.codex/review.config.toml 檔案內容可為：model_reasoning_effort = "xhigh" 和 sandbox_mode = "read-only"。
您可以使用 codex --profile review 來執行此設定檔。請注意，設定檔格式在 Codex 0.134.0 版中有所變更，OpenAI 的進階配置指南涵蓋了遷移細節。
專案儲存庫中的 .codex/config.toml 僅在該專案於您的使用者配置中被標記為「受信任」時才會被讀取，例如：[projects."/Users/you/code/my-app"] trust_level = "trusted"。
即使如此，Codex 仍會忽略專案檔案中的 model_provider、model_providers、openai_base_url、profile、notify 等多個金鑰，以防止儲存庫重新導向您的請求。因此，供應商設定應保留在 ~/.codex/config.toml 中。
根據 OpenAI 的「配置基礎」文件，設定的優先順序由高到低依序為：CLI 旗標（flags）和 -c key=value 覆寫、專案層級的 .codex/config.toml（最接近工作目錄者優先）、--profile 指定的檔案、~/.codex/config.toml、/etc/codex/config.toml，以及內建預設值。
專案檔案的優先順序高於設定檔（profile）。在一項測試中，當使用者配置、設定檔和受信任專案都設定了不同的模型時，codex exec --profile fast 執行了專案的模型，且只採用了設定檔的推理努力程度；而 -m 參數則能覆寫兩者。
| 金鑰 | 值 |
|---|---|
| sandbox_mode | read-only、workspace-write、danger-full-access |
| approval_policy | on-request、never，或是一個細化的表格 |
workspace-write 模式允許在工作目錄、/tmp 和 $TMPDIR 中寫入，但在 [sandbox_workspace_write] 下設定 network_access = true 之前，不允許網路連線。never 模式會停止提示，但不會擴大沙盒範圍。
您可以設定環境變數來使用代理伺服器，例如：export HTTPS_PROXY = http://127.0.0.1:7890，以及 export NO_PROXY = localhost,127.0.0.1。若使用 TLS 檢查代理，則需設定 export CODEX_CA_CERTIFICATE = /path/to/corp-root-ca.pem。
OpenAI 的環境變數參考文件僅記載 CODEX_CA_CERTIFICATE，但未提及代理相關變數。在 Codex 0.162.1 版中，對自訂供應商的請求會透過 HTTPS_PROXY、小寫的 https_proxy 和 ALL_PROXY 進行，而 NO_PROXY 中列出的主機則會被跳過。
/model 預設只列出 OpenAI 的模型，除非頂層的 model_catalog_json 指向一個模型目錄檔案。這個目錄檔案會取代內建清單，且每個條目都需要完整的內部欄位設定，因此建議生成它。AIHubMix 的 Codex CLI 指南提供了一個腳本，可以為前 30 個 AIHubMix 模型複製一個內建條目。您可以使用 codex debug models 來驗證。
如果 config.toml 中仍有 profile = "..." 選項，請將該設定檔移至獨立檔案，並刪除此選項。若 config.toml 中殘留 [profiles.x] 表格，使用 --profile x 會導致錯誤訊息「--profile x cannot be used while ... contains legacy ... config」。若不使用該旗標，此表格將被默默忽略。
請將其更改為 responses。僅支援 Chat Completions 的供應商需要透過一個轉譯代理（translating proxy）來處理。
請重新命名名為 openai、ollama 或 lmstudio 的供應商。若要重新指向內建的 OpenAI 供應商，請改為設定頂層的 openai_base_url。
請將其移除，或改用 on-request。on-failure 已被棄用，但目前仍可接受。
env_key 中指定的變數在 Codex 啟動的環境中不存在。請開啟新的終端機，或執行 source ~/.zshrc。
這表示請求沒有攜帶任何金鑰。請檢查 env_key 設定，因為 auth.json 不適用於自訂供應商。
這是針對 Codex 目錄之外的任何模型發出的警告，對於非 OpenAI 模型來說是正常的。請求仍會正常運作，但建立模型目錄可以消除此警告。
這表示專案檔案設定了僅限使用者層級的金鑰，通常是 model_provider。請將其移至 ~/.codex/config.toml。
這表示模型目錄條目不完整，導致整個檔案被拒絕。請重新生成目錄，而非手動編輯。
PAC 檔案：Codex 沒有針對 PAC 檔案的設定；第三方文章中描述的行為未經測試。桌面應用程式的模型選擇器：它可能會隱藏目錄中的模型（參見 openai/codex#19694）；本文僅測試了 CLI 版本。在錯誤測試中，沒有發送實際請求；每個測試都使用了臨時的 CODEX_HOME 和無法連線的 base URL。
覺得值得一看？分享給朋友。
以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Codex) 所有， 建議透過「閱讀原文」前往原始網站，以取得最完整資訊並支持原作者。
43 個來源、每 2 小時更新，太多看不完。電子報每週挑最值得看的幾則，附上 Max 的看法。
