Codex 配置 DeepSeek 模型詳細教學

更新時間：2026-08-12

導讀

Codex 預設使用 OpenAI 模型；透過 ~/.codex/config.toml 中的 model_providers，可以把推理後端切換為 DeepSeek API——在保留 Codex「讀倉庫、改檔案、跑命令」工作流的同時，使用 deepseek-v4-pro、deepseek-v4-flash 等模型。

本文涵蓋：申請金鑰 → 環境變數 → config.toml → curl 連通性驗證 → 常見報錯。開始前請已完成 Codex 安裝與基礎配置。DeepSeek 端點、模型名與 Codex 版本行為以 DeepSeek API 文件 與 Codex 配置文件 為準。

為什麼要給 Codex 接 DeepSeek？

訴求	DeepSeek 作為後端的潛在收益
成本	API 單價通常低於同檔 OpenAI 模型，適合高頻 Agent 呼叫
中文與程式碼	V4 系列在中文註解、報錯解釋場景表現穩定
資料路徑	金鑰與請求走 DeepSeek 官方或自建閘道，便於合規審計

注意： Codex 的工具呼叫、沙箱、審批仍由 Codex 客戶端實現；換模型不會自動降低「亂改檔案」風險，權限策略仍需嚴格配置。

第一步：取得 DeepSeek API Key

1. 開啟 DeepSeek 官網 進入開發者平台（步驟以當前頁面為準）。
2. 完成帳號、計費與 API Key 建立——金鑰通常只顯示一次，應存入密碼管理器。
3. 禁止把 Key 寫入 Git、前端程式碼或 config.toml 明文；應使用環境變數。

更完整的申請、首個請求與生產清單見 DeepSeek API 申請與開發入門。若暫時只想在瀏覽器體驗模型能力，可用 DeepSeek V4 國內入口 或 AI Chat Studio 鏡像——網頁聊天與 API 帳號、配額並不預設相同。

第二步：確認 API 參數

根據 DeepSeek API 文件，OpenAI 相容介面常用參數為：

參數	值
Base URL	https://api.deepseek.com
認證	Authorization: Bearer $DEEPSEEK_API_KEY
模型名（範例）	deepseek-v4-pro、deepseek-v4-flash

模型字串會更新，務必從文件複製，不要沿用舊教學中的 deepseek-chat 等過期名稱。程式設計向任務可優先試 deepseek-v4-pro；對延遲敏感時可試 deepseek-v4-flash。

第三步：設定環境變數

macOS / Linux（當前 shell）：

export DEEPSEEK_API_KEY="你的金鑰"

Windows PowerShell（當前工作階段）：

$env:DEEPSEEK_API_KEY = "你的金鑰"

生產環境應使用系統密鑰管理或 CI Secret，而非長期寫在 shell 設定檔裡。DeepSeek 側安全實務詳見 API 指南 中的「上線必做」一節。

第四步：編輯 ~/.codex/config.toml

以下配置需寫在使用者級 ~/.codex/config.toml（Windows：%USERPROFILE%\.codex\config.toml）。model_provider 與 model_providers 不能僅寫在專案級 .codex/config.toml 中——Codex 會忽略專案檔案裡的這些鍵。

# 宣告 DeepSeek 為自訂 provider
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
requires_openai_auth = false

# 切換預設後端
model_provider = "deepseek"
model = "deepseek-v4-pro"

# 新手建議保持詢問式審批
approval_policy = "on-request"
sandbox_mode = "workspace-write"

欄位說明

欄位	作用
base_url	DeepSeek API 根位址；若文件要求帶 /v1 後綴，以文件為準
wire_api	Codex 新版本預設走 responses 協定；若閘道僅支援 Chat Completions，需確認 DeepSeek 或中轉是否提供相容端點
env_key	從該環境變數讀取 Bearer Token
requires_openai_auth = false	非 OpenAI 金鑰前綴時必須設為 false
model	必須與 DeepSeek 文件中的模型 ID 完全一致

DeepSeek 文件提到其 API 已被 Claude Code、Copilot 等 Agent 工具支援；Codex 透過 OpenAI 相容 + model_providers 接入，思路與 DeepSeek 程式設計實戰 中的 API 呼叫一致，只是配置入口在 Codex 而非 SDK 程式碼裡。

第五步：用 curl 先驗證 API

在改 Codex 之前，用最小請求確認金鑰與模型名有效（占位符請替換為文件當前值）：

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "回覆 OK"}],
    "stream": false
  }'

若 curl 失敗，先修 Key、餘額與模型名，不要在 Codex 裡反覆試。curl 成功後再在專案目錄執行 codex，發起唯讀任務驗證端到端鏈路。

使用 Profile 做多模型切換

若你希望「日常用 DeepSeek、Review 用 OpenAI」，可用 Profile overlay：

[profiles.openai-default]
model_provider = "openai"
model = "gpt-5.4"

[profiles.deepseek-coding]
model_provider = "deepseek"
model = "deepseek-v4-pro"
model_reasoning_effort = "high"

啟動時指定：codex --profile deepseek-coding。Profile 檔案也可放在 ~/.codex/deepseek-coding.config.toml，詳見官方 Profile 說明。

排錯清單

現象	可能原因	處理
401 / 認證失敗	Key 錯誤或環境變數未匯出	重新 export；勿在公共場合 echo 金鑰
404 / model not found	模型名過期或拼寫錯誤	對照 API 文件 模型表
wire_api / responses 報錯	Codex 與閘道協定不匹配	確認 DeepSeek 或中轉是否支援 Codex 所需的 responses 介面
配置改了不生效	寫在專案 config 或被 Profile 覆蓋	檢查使用者級 config.toml 與 --profile
回應慢或斷流	網路或逾時設定	調整 provider 逾時；國內網路可評估合規閘道
程式碼品質下降	模型與任務不匹配	複雜推理可換 deepseek-v4-pro；參考 DeepSeek R1 推理指南

重要： Codex 在 2026 年初後傾向於 wire_api = "responses"。若 DeepSeek 官方僅暴露 /chat/completions 而你的 Codex 版本強制 responses，可能需要等待官方 Agent 整合更新、使用 DeepSeek 文件推薦的相容層，或經團隊評估後使用提供 /v1/responses 的合規閘道——不要在生產環境硬改 requires_openai_auth 或關閉沙箱來「繞過」報錯。

安全與合規

• DeepSeek API Key 與 OpenAI Key 分開輪換，不要共用同一 env 名。
• 公司倉庫接入前確認資料出境與供應商政策。
• Codex 仍可能讀取倉庫內的業務邏輯；敏感模組使用 read-only 沙箱或排除目錄。
• 帳單以 DeepSeek 控制台為準，與 ChatGPT Codex 訂閱獨立計費。

常見問題

配好 DeepSeek 後還能用 ChatGPT 登入嗎？

可以。model_provider 決定推理後端；ChatGPT 登入用於 Codex 產品授權。兩者關係以你當前 Codex 版本說明為準，若衝突以官方文件為準。

deepseek-v4-flash 和 deepseek-v4-pro 怎麼選？

pro 適合複雜重構與多檔案推理；flash 適合快問快答、註解與小型 patch。用同一倉庫各跑 5 個真實任務對比修改行數與測試通過率，比看宣傳參數更可靠。

能否在 IDE 擴充功能裡用 DeepSeek 後端？

IDE 擴充功能與 CLI 共享使用者級 config.toml，配置方式相同。改完後重啟擴充功能或重新載入視窗。

國內網頁入口的 DeepSeek 與 API 是同一套嗎？

不一定。DeepSeek V4 國內入口 與 AI Chat Studio 適合體驗對話；Codex Agent 必須配置 API Key。參見 DeepSeek 國內使用安全指南。

與直接用 DeepSeek 網頁寫程式碼相比有何優勢？

Codex 優勢在倉庫上下文 + 執行測試 + 多檔案 patch 閉環；純聊天更適合單次片段。兩者可互補：複雜架構先用 DeepSeek 提示詞指南 理清思路，再在 Codex 裡落地改動。

官方資源

• DeepSeek API 文件
• DeepSeek 官網
• OpenAI Codex 配置文件
• OpenAI Platform
• ChatGPT

下一步閱讀

• Codex 下載、安裝、配置基礎教學
• Codex 安裝與使用：新手快速上手
• DeepSeek API 申請與開發入門
• DeepSeek V4 完整功能與使用指南
• DeepSeek vs ChatGPT vs Claude 怎麼選

行動路徑

今天：curl 驗證 Key 與模型名，再在練習倉庫跑一條唯讀 Codex 指令。本週：用 DeepSeek 後端完成一次 failing test 修復，記錄與 OpenAI 預設模型的耗時與 diff 行數。上線前：在團隊內文件化 model_provider 切換方式、金鑰輪換流程與回滾 Profile（codex --profile openai-default）。