讓 Codex 使用 DeepSeek 模型的兩種方法：本機閘道和 OpenRouter BYOK

想讓 Codex 使用 DeepSeek，第一反應通常是改 ~/.codex/config.toml：

1
2


model = "deepseek-chat"
base_url = "https://api.deepseek.com"

這個思路在一些舊版本或普通 OpenAI SDK 場景裡確實成立，但放到目前的 Codex CLI 上，很容易撞到一個底層問題：Codex 的自訂模型供應商走的是 OpenAI Responses 協議，而 DeepSeek 官方介面主要提供 OpenAI 相容的 Chat Completions 呼叫方式。

我本機目前是 codex-cli 0.111.0。codex --help 裡可以看到它支援 --config、--model、--profile 這些設定入口；OpenAI 官方 Codex 設定參考也寫得很明確：model_providers.<id>.wire_api 目前只支援 responses，省略時也預設是 responses。

DeepSeek 官方文件則給出的呼叫路徑是 https://api.deepseek.com/chat/completions，範例也是 client.chat.completions.create(...)。所以問題不在於 DeepSeek 不能被 OpenAI SDK 呼叫，而在於 Codex 發出的請求語義，和 DeepSeek 原生介面能理解的語義不完全是同一套東西。

這就是為什麼直接把 base_url 改成 https://api.deepseek.com 後，可能出現下面這些現象：

請求路徑不匹配，直接 404 或回傳格式不對。
多輪對話、工具呼叫、補丁產生時解析失敗。
tool_calls 順序、訊息結構、串流事件格式對不上。
看起來模型能回一句話，但一到 Codex 真正幹活就開始報錯。

更穩的辦法，是在 Codex 和 DeepSeek 之間放一個「翻譯層」。常見有兩種路線。

方法一：用本機閘道橋接 DeepSeek

本機閘道的作用不是簡單轉發，而是把 Codex 側的 Responses 風格請求，轉換成 DeepSeek 能處理的 Chat Completions 風格請求，再把 DeepSeek 的結果轉換回 Codex 能吃的格式。

如果你用的是 ccx 這類本機閘道，設定思路大致是這樣：

1
2
3
4
5
6
7
8


[profiles.deepseek-ccx]
model = "deepseek-v4-flash"
model_provider = "ccx-bridge"

[model_providers.ccx-bridge]
name = "Local CCX Gateway"
base_url = "http://localhost:3000/v1"
env_key = "DEEPSEEK_API_KEY"

然後在終端機裡設定 DeepSeek Key，再用這個 profile 啟動：

1
2


export DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

PowerShell 裡是：

1
2


$env:DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

這裡有兩個細節要注意。

第一，base_url 要指向閘道暴露給 Codex 的位址，不是 DeepSeek 官方位址。閘道背後再去呼叫 DeepSeek。

第二，env_key 寫什麼取決於閘道怎麼鑑權。有的閘道直接讀取 DeepSeek 官方 Key，有的閘道會要求你給它一個本機代理 Key，再由閘道自己的後台保存 DeepSeek Key。遇到這種情況，env_key 就應該改成閘道要求的環境變數名。

這條路的優點是本機可控，延遲和成本也更容易算清楚。缺點是你必須確認閘道真的支援 Codex 目前使用的 Responses 語義，而不是只做了普通 Chat Completions 代理。

方法二：用 OpenRouter BYOK 做線上橋接

如果不想在本機部署閘道，可以考慮 OpenRouter 的 BYOK。BYOK 的意思是把你自己的上游供應商 Key 綁定到 OpenRouter，由 OpenRouter 負責路由和轉發。

這裡最容易寫錯的是環境變數。Codex 存取的是 OpenRouter，所以 env_key 通常應該是 OPENROUTER_API_KEY，不是 DEEPSEEK_API_KEY。DeepSeek Key 要在 OpenRouter 的 BYOK 或 provider key 設定裡新增。

設定範例：

1
2
3
4
5
6
7
8


[profiles.deepseek-openrouter]
model = "deepseek/deepseek-chat"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

啟動方式：

1
2


export OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

PowerShell：

1
2


$env:OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

然後在 OpenRouter 後台把 DeepSeek 的 provider key 加進去。OpenRouter 的 BYOK 文件說明，綁定的 provider key 會被加密保存，並用於路由到對應供應商。

這條路的優點是省掉本機閘道維護成本，設定起來更像普通第三方 API 代理。缺點是中間多了一層線上服務，排障時要同時看 Codex、OpenRouter、DeepSeek 三邊的錯誤訊息。

要不要繼續用 deepseek-chat 這個模型名？

DeepSeek 官方文件在 2026 年 5 月的說明裡，推薦模型名已經出現 deepseek-v4-flash 和 deepseek-v4-pro，並提示 deepseek-chat、deepseek-reasoner 相容別名會在 2026-07-24 之後廢棄。

所以新設定裡更建議優先測試：

1

model = "deepseek-v4-flash"

如果走 OpenRouter，則要按 OpenRouter 的模型命名來寫，例如：

1

model = "deepseek/deepseek-chat"

實際可用名稱以你所用閘道或 OpenRouter 模型頁為準。模型名不對時，錯誤通常會表現為 model not found、404，或者 provider 找不到對應 endpoint。

直接改 DeepSeek 官方 base_url 為什麼不推薦

你當然可以試著寫：

1
2
3
4
5
6
7
8


[profiles.deepseek-direct]
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

但這更像排錯實驗，不適合作為穩定方案。因為 Codex 會按 Responses 協議去和自訂 provider 說話，而 DeepSeek 官方範例走的是 /chat/completions。如果 DeepSeek 或 Codex 未來補齊了相容層，這種直連才可能變得簡單；在此之前，橋接層更可靠。

改完設定後還是走 OpenAI 怎麼辦

先確認設定檔位置。全域設定應該在：

1

~/.codex/config.toml

專案裡的 .codex/config.toml 不適合放 model_provider、model_providers 這類機器級 provider 設定。OpenAI 官方文件也提醒，專案級設定不會覆蓋這些本機 provider 和認證相關欄位。

如果 Codex 仍然要求網頁登入，或者看起來還在走預設 OpenAI 模型，可以先退出目前登入狀態：

1

codex logout

有些舊教學會寫成交互介面裡的 /logout。在目前 CLI 裡，更穩的是直接在終端機執行 codex logout。

還可以用臨時參數做一次快速驗證：

1

codex --profile deepseek-ccx

或者：

1

codex -c model_provider=ccx-bridge -c model=deepseek-v4-flash

如果這樣能生效，說明設定本身可讀；如果不生效，優先檢查 profile 名稱、TOML 語法、環境變數是否只在目前 shell 裡有效。

排障清單

401：Key 不對，或者 env_key 指向了錯誤的環境變數。
404：base_url 或模型名不對，也可能是把 Responses 請求打到了只支援 Chat Completions 的位址。
tool_calls、patch、串流解析報錯：大機率是協議橋接不完整。
仍然提示登入 OpenAI：執行 codex logout，再確認是否用了正確 profile。
PowerShell 設定環境變數後新開視窗失效：$env:... 只對目前會話生效，需要長期保存就改使用者環境變數。
OpenRouter BYOK 沒走自己的 DeepSeek Key：檢查 OpenRouter 後台 provider key 是否綁定、是否允許目前 OpenRouter API Key 使用，以及是否開啟了 fallback。

結論

讓 Codex 使用 DeepSeek，不是不能改 config.toml，而是不能只改 base_url 就指望一切自動相容。

目前更穩的兩條路是：

用本機閘道做協議橋接，Codex 連本機閘道，閘道再連 DeepSeek。
用 OpenRouter BYOK 做線上轉發，Codex 連 OpenRouter，DeepSeek Key 綁定在 OpenRouter 後台。

如果只是想快速試用，OpenRouter 路線更省事；如果你希望 Key、成本、日誌都盡量掌握在自己手裡，本機閘道更適合長期折騰。

參考資料：