1. 背景與原理

Codex CLI 使用 OpenAI Responses API 與模型通信；DeepSeek 官方 API 僅提供 Chat Completions 格式，二者協(xié)議不兼容，不能直接改 base_url 指向 DeepSeek。

因此需要在本機(jī)運(yùn)行一層 協(xié)議轉(zhuǎn)換代理（本項(xiàng)目使用 codex-bridge）：

Codex CLI  ──Responses API──?  本地代理 (127.0.0.1:4000)  ──Chat Completions──?  DeepSeek API

2. 前置條件

驗(yàn)證 Codex 是否已安裝：

codex --version
node --version

3. 需要人工提供的內(nèi)容

注意：PROXY_AUTH_KEY 不是 DeepSeek Key，也不是 OpenAI Key。它是 Codex 訪問(wèn)本地代理時(shí)使用的「本地通行證」，需同時(shí)寫入 ~/codex-bridge/.env 和 ~/.codex/auth.json，且兩者必須完全一致。

4. 涉及的配置文件一覽

重要：model_providers、profiles 等 provider 相關(guān)配置必須寫在 ~/.codex/config.toml（用戶級(jí)），不要寫在項(xiàng)目目錄的 .codex/config.toml 中，否則會(huì)被忽略。

5. 安裝本地代理

5.1 下載 codex-bridge

mkdir -p ~/codex-bridge
curl -fsSL -o ~/codex-bridge/proxy.mjs \
  "https://raw.githubusercontent.com/wujfeng712-ui/codex-bridge/main/proxy.mjs"
curl -fsSL -o ~/codex-bridge/env.example \
  "https://raw.githubusercontent.com/wujfeng712-ui/codex-bridge/main/env.example"

若 git clone 可用，也可：

git clone https://github.com/wujfeng712-ui/codex-bridge.git ~/codex-bridge

5.2 配置 ~/codex-bridge/.env

復(fù)制示例并編輯：

cp ~/codex-bridge/env.example ~/codex-bridge/.env

.env 最少需要以下內(nèi)容（替換占位符）：

# 本地代理鑒權(quán) Key（自行生成，需與 ~/.codex/auth.json 一致）
PROXY_AUTH_KEY=sk-proxy-local-你的隨機(jī)字符串

# DeepSeek 官方 API Key（人工申請(qǐng)）
DEEPSEEK_API_KEY=sk-你的deepseek密鑰

# 對(duì)外暴露的模型列表
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash

# 監(jiān)聽端口
PROXY_PORT=4000
LOG_LEVEL=info

5.3 啟動(dòng)腳本（可選）

~/codex-bridge/start.sh：

#!/bin/zsh
set -euo pipefail
cd "$(dirname "$0")"

if grep -q "REPLACE_WITH_YOUR_DEEPSEEK_KEY" .env 2>/dev/null; then
  echo "請(qǐng)編輯 ~/codex-bridge/.env，將 DEEPSEEK_API_KEY 替換為你的 DeepSeek API Key"
  exit 1
fi

node --env-file=.env proxy.mjs

chmod +x ~/codex-bridge/start.sh

6. 配置 Codex

6.1 ~/.codex/auth.json

Codex 連接本地代理時(shí)使用 OPENAI_API_KEY 字段傳遞 PROXY_AUTH_KEY（不是 DeepSeek Key）：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-proxy-local-你的隨機(jī)字符串"
}

OPENAI_API_KEY 的值必須與 ~/codex-bridge/.env 中的 PROXY_AUTH_KEY 完全一致。

6.2 ~/.codex/config.toml

在現(xiàn)有配置基礎(chǔ)上追加 DeepSeek 相關(guān)段落（保留你原有的 projects、marketplaces 等配置）：

# DeepSeek via local codex-bridge proxy
[profiles.deepseek]
model = "deepseek-v4-flash"
model_provider = "local_proxy"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

[profiles.deepseek-pro]
model = "deepseek-v4-pro"
model_provider = "local_proxy"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

[model_providers.local_proxy]
name = "local_proxy"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
requires_openai_auth = true

可選：為項(xiàng)目目錄添加信任（首次進(jìn)入項(xiàng)目時(shí)不再反復(fù)詢問(wèn)）：

[projects."/Users/am/Desktop/code/cmlivekit"]
trust_level = "trusted"

6.3 模型說(shuō)明

7. 驗(yàn)證配置

7.1 啟動(dòng)代理

~/codex-bridge/start.sh
# 或
cd ~/codex-bridge && node --env-file=.env proxy.mjs

成功時(shí)應(yīng)看到類似輸出：

[codex-bridge] Listening on http://localhost:4000
[codex-bridge] Default provider: deepseek
[codex-bridge] Deepseek: https://api.deepseek.com/v1 | models=deepseek-v4-pro, deepseek-v4-flash

7.2 健康檢查

curl http://127.0.0.1:4000/health

期望返回：

{"status":"ok","proxy":"codex-bridge","providers":["deepseek"],"default_provider":"deepseek"}

7.3 啟動(dòng) Codex

cd /Users/am/Desktop/code/cmlivekit
codex -p deepseek       # flash 版
codex -p deepseek-pro   # pro 版

首次進(jìn)入新目錄可能提示：

Do you trust the contents of this directory?

選擇 Yes, continue 即可。

常見錯(cuò)誤：使用 codex -m deepseek-v4-flash 只會(huì)換模型名，不會(huì)切換 provider，仍走 OpenAI 路徑。必須使用 codex -p deepseek。

8. 日常使用

# 終端 1：?jiǎn)?dòng)代理（每次重啟電腦或關(guān)閉終端后需重新執(zhí)行）
~/codex-bridge/start.sh

# 終端 2：使用 Codex + DeepSeek
cd /path/to/your/project
codex -p deepseek

后臺(tái)運(yùn)行代理：

nohup ~/codex-bridge/start.sh > /tmp/codex-bridge.log 2>&1 &

9. 故障排查

10. 配置關(guān)系圖

┌─────────────────────────────────────────────────────────────┐
│  ~/.codex/config.toml                                       │
│  ├── [profiles.deepseek]         → model + provider         │
│  └── [model_providers.local_proxy] → http://127.0.0.1:4000  │
└──────────────────────────┬──────────────────────────────────┘
                           │ requires_openai_auth
┌──────────────────────────▼──────────────────────────────────┐
│  ~/.codex/auth.json                                         │
│  └── OPENAI_API_KEY = PROXY_AUTH_KEY（本地代理鑒權(quán)）         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│  ~/codex-bridge/.env                                        │
│  ├── PROXY_AUTH_KEY  ← 與 auth.json 一致                    │
│  └── DEEPSEEK_API_KEY ← 人工申請(qǐng)，轉(zhuǎn)發(fā)到 DeepSeek 官方 API   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
                    api.deepseek.com

11. 安全提醒

• 不要將 DEEPSEEK_API_KEY、PROXY_AUTH_KEY 提交到 Git 倉(cāng)庫(kù)
• ~/codex-bridge/.env 應(yīng)保持在本地，加入 .gitignore（若代理目錄在 git 倉(cāng)庫(kù)內(nèi)）
• PROXY_AUTH_KEY 僅用于 localhost 鑒權(quán)，代理默認(rèn)只監(jiān)聽本機(jī)，不應(yīng)對(duì)外暴露

12. 參考鏈接

• Codex CLI 官方文檔
• Codex 高級(jí)配置（Custom model providers）
• codex-bridge 項(xiàng)目
• DeepSeek 開放平臺(tái)

文檔生成環(huán)境：macOS，Codex CLI 0.133.0，Node.js 22，代理端口 4000。