如何設定 Codex config.toml：自訂 API、Proxy 與常見錯誤

Codex 將設定儲存在單一檔案 config.toml 中：要使用哪個模型、呼叫哪個 API，以及代理程式無須詢問即可執行多少操作。這個格式在 2026 年經過數次變更，許多年初的指南所列設定，現在會導致 Codex 無法啟動。

本指南會先提供一份可用的設定檔，再介紹多數人會調整的部分：設定檔、專案設定、沙箱與 Proxy。最後列出你可能遇到的錯誤，以及各錯誤代表的意思。內容已對照 OpenAI 文件確認，並於 2026 年 10 月 19 日在 Codex CLI 0.162.1 上測試。範例使用 AIHubMix 作為供應商；任何支援 OpenAI Responses API 的閘道都能以相同方式使用。

簡而言之

檔案位於 ~/.codex/config.toml，Windows 上則是 C:\Users\<you>\.codex\config.toml。
自訂供應商需要設定 base_url、wire_api = "responses" 和 env_key。API 金鑰要放在環境變數中。
設定檔現在各自存放於獨立檔案 ~/.codex/<name>.config.toml，並以 --profile <name> 選用。
Repo 中的 .codex/config.toml 只有在受信任的專案中才會生效，而且無法變更供應商。
每次編輯後都要重新啟動 Codex；它只會在啟動時讀取檔案。

config.toml 存放位置

主要設定位於 ~/.codex/config.toml。CLI 和 IDE 擴充功能都會讀取此檔案。如果檔案尚不存在，請自行建立。

另外兩個位置也可以疊加設定：

設定檔，~/.codex/<name>.config.toml，只有在啟動 Codex 時使用 --profile <name> 才會套用。
專案檔案，位於 Repo 中的 .codex/config.toml，可供團隊分享設定。

如果你在 Windows 上透過 WSL2 執行 Codex，它會讀取 Linux 家目錄中的檔案（/home/<you>/.codex/config.toml），而不是 Windows 的檔案。如果已設定 CODEX_HOME，Codex 會使用該資料夾，而非 ~/.codex。

最精簡的可用設定

這份完整的 ~/.codex/config.toml 會將 Codex 的請求傳送至 AIHubMix：

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"

model 是要呼叫的模型 ID，而 model_reasoning_effort 則是預設的推理程度。
model_provider 必須與 [model_providers.<name>] 中的名稱相符。請勿使用 openai、ollama 或 lmstudio；這些名稱已保留給 Codex 內建的供應商。
base_url 是供應商的 API 位址。wire_api = "responses" 是 Codex 目前唯一接受的值。
env_key 是環境變數的名稱，不是金鑰本身。

接著，使用從 AIHubMix 控制台取得的金鑰設定該變數：

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

開啟新的終端機並執行 codex，然後隨便問它一個問題。如果它有回覆，代表供應商已正常運作。是否已登入 Codex 不會影響此處的設定：codex login 使用的金鑰永遠不會傳送給自訂供應商。

設定檔：每種設定各用一個檔案

設定檔只包含與主要設定不同的部分，例如較深入的推理，以及用於程式碼審查的唯讀沙箱。每個設定檔都是與 config.toml 放在一起的獨立檔案，並將鍵值寫在最外層：

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

這項變更從 Codex 0.134.0 開始。較舊的指南會將設定檔放在 config.toml 的 [profiles.review] 區塊中，並以 profile = "review" 選用。現在 Codex 會因為這個選擇器而拒絕啟動。若只留下 [profiles.review] 區塊，它會在沒有任何提示的情況下遭到忽略，因此其中的設定會悄悄失效。若要遷移，請將各區塊的鍵值移至 ~/.codex/<name>.config.toml，再刪除該區塊及 profile = ... 這一行。詳情請參閱 OpenAI 的進階設定指南。

專案設定：.codex/config.toml

Repo 中的 .codex/config.toml 可讓團隊共用預設模型、推理程度或沙箱模式。Codex 只有在專案已於你自己的 ~/.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 的設定基礎列出了以下優先順序，從高到低排列：

命令列旗標，包括 -c 覆寫設定
專案的 .codex/config.toml
以 --profile 選擇的設定檔
你的 ~/.codex/config.toml
系統設定 /etc/codex/config.toml
Codex 內建的預設值

請注意，專案檔案的優先順序高於設定檔。如果設定檔中的設定似乎沒有生效，請檢查 Repo 的 .codex/config.toml 是否設定了相同的鍵值。

若只想在單次執行中變更設定，請使用 -c：

codex -c model_reasoning_effort=high

沙箱與核准

有兩個鍵值會控制 Codex 可自行執行的操作。sandbox_mode 用來設定命令可操作的範圍，而 approval_policy 則設定 Codex 何時會停下來詢問你。

sandbox_mode	命令可執行的操作
read-only	讀取檔案；其他操作都需要核准
workspace-write	可在專案資料夾和暫存資料夾中寫入
danger-full-access	可執行任何操作，不受沙箱限制

approval_policy	Codex 何時會詢問
on-request	需要超出沙箱限制時
never	永不詢問；遭封鎖的命令會直接失敗

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

兩者彼此獨立：never 會停止提問，但不會放寬沙箱限制。在 workspace-write 模式下，除非設定 network_access = true，否則命令無法連線至網路。

使用 Proxy

Codex 沒有可在 config.toml 中設定的 Proxy 選項。它會使用標準環境變數：

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

OpenAI 文件沒有提到這些變數，因此我們在 Codex 0.162.1 上進行了測試：包括傳送至自訂供應商的請求，都會透過 HTTPS_PROXY（或 ALL_PROXY）傳送，而 NO_PROXY 中的主機則會直接連線。不支援 PAC 檔案，因此請直接輸入 Proxy 位址。如果公司的 Proxy 使用自己的根憑證，請依照環境變數參考中的說明，將 CODEX_CA_CERTIFICATE 指向該憑證。

在 /model 中加入更多模型

/model 選擇器只會列出 OpenAI 的模型。若要從中選擇 GLM、Claude、Gemini 或 DeepSeek 模型，請加入模型目錄：使用最外層的 model_catalog_json 鍵值指定一個 JSON 檔案。請將此鍵值放在第一個 [table] 區塊之前，否則 TOML 會將它視為該區塊的一部分，而 Codex 便會忽略它。

模型目錄會取代內建清單，而每個項目都需要填寫一長串欄位，因此最好用程式產生，而非手動撰寫。AIHubMix Codex CLI 指南提供一個指令碼，可根據 AIHubMix 上排名前 30 的模型建立模型目錄。桌面應用程式可能仍會在選擇器中隱藏自訂模型（openai/codex#19694），因此請在終端機中切換模型。

常見錯誤及其含意

以下是 Codex 0.162.1 在發生各種錯誤時顯示的訊息。

legacy profile = "..." config is no longer supported
你的 config.toml 中仍有舊版的 profile = "..." 這一行。請依照前文說明，將設定檔移至獨立檔案。如果舊版 [profiles.x] 區塊仍存在時執行 --profile x，也會出現類似錯誤：--profile x cannot be used while ... contains legacy ... config。

wire_api = "chat" is no longer supported
Codex 不再支援 Chat Completions API。請將其改為 wire_api = "responses"。只提供 Chat Completions 的供應商，若沒有轉換用的 Proxy，就無法使用。

model_providers contains reserved built-in provider IDs
你將供應商命名為 openai、ollama 或 lmstudio。請將區塊名稱和 model_provider 改成其他名稱。

approval_policy = "untrusted" is no longer supported
請移除此行，或改用 on-request。

Missing environment variable: AIHUBMIX_API_KEY
env_key 中指定的變數，未在啟動 Codex 的終端機中設定。請開啟新的終端機，或執行 source ~/.zshrc，然後重新啟動 Codex。

出現幾行「Reconnecting...」後，接著顯示 401 Unauthorized
請求送出時沒有附上金鑰。請確認供應商區塊中有設定 env_key。儲存在 auth.json 中的登入資訊不適用於自訂供應商。

Model metadata for ... not found. Defaulting to fallback metadata
Codex 沒有該模型的內建設定；非 OpenAI 模型出現此情況很正常。請求仍可正常運作。若要使用正確的設定，並讓模型出現在 /model 中，請加入模型目錄。

Ignored unsupported project-local config keys
Repo 的 .codex/config.toml 設定了只能用於你自己的設定檔中的鍵值，通常是 model_provider。請將它移至 ~/.codex/config.toml。

missing field base_instructions
模型目錄中的某個項目缺少必要欄位，因此 Codex 拒絕整個檔案。請使用指令碼重新產生模型目錄，不要手動編輯。

設定沒有生效時

編輯後請重新啟動 Codex。
確認最外層的鍵值位於第一個 [table] 區塊之前。
檢查 Repo 的 .codex/config.toml；它的優先順序高於你的設定檔。
確認是否還留有 [profiles.x] 區塊。
執行 codex doctor，檢查安裝、設定和登入狀態。

如果你想在 Codex 中使用 OpenAI、Anthropic、Google、Zhipu、DeepSeek 等模型，只需一組金鑰，AIHubMix 可透過 https://aihubmix.com/v1 提供 Responses API。請先使用上方的最精簡設定；需要透過 /model 切換模型時，再加入模型目錄。

常見問題

Codex 的 config.toml 檔案在哪裡？
macOS 和 Linux 上位於 ~/.codex/config.toml；Windows 上則位於 C:\Users<you>.codex\config.toml。如果已設定 CODEX_HOME，檔案就會位於該資料夾中。

變更 config.toml 後，需要重新啟動 Codex 嗎？
需要。Codex 會在啟動時讀取檔案，因此請結束並重新開啟終端機工作階段或應用程式。

為什麼 Codex 顯示「不再支援舊版設定檔設定」？
Codex 0.134.0 已移除在 config.toml 內定義的設定檔。請將每個設定檔移至 ~/.codex/name.config.toml，刪除舊的設定行，並使用 --profile name 啟動 Codex。

我還能使用 wire_api = "chat" 嗎？
不能。Codex 僅接受 wire_api = "responses"。只支援 Chat Completions 的供應商需要透過代理伺服器轉換為 Responses API。

為什麼我已登入 Codex，自訂供應商卻回傳 401？
auth.json 中的登入金鑰不會傳送給自訂供應商。請在供應商資料表中新增 env_key，並在終端機中設定該變數。

Codex 會使用 HTTPS_PROXY 嗎？
會。在 Codex 0.162.1 的測試中，請求會透過 HTTPS_PROXY 傳送，並略過列於 NO_PROXY 中的主機。不支援 PAC 檔案。

為什麼專案的 .codex/config.toml 中的 model_provider 沒有生效？
專案檔案無法變更請求的傳送位置，因此儲存庫無法重新導向你的流量。請將供應商設定在 ~/.codex/config.toml；專案檔案仍可設定模型。

資料來源

設定基礎，OpenAI
進階設定，OpenAI
設定參考，OpenAI
Codex CLI 整合指南，AIHubMix
Codex CLI 代理伺服器設定：SOCKS、HTTP 與企業網路，Daniel Vaughan