Codex 终端版接入 DeepSeek 配置指南

1. 背景与原理

Codex CLI 使用 OpenAI Responses API 与模型通信；DeepSeek 官方 API 仅提供 Chat Completions 格式，二者协议不兼容，不能直接改 base_url 指向 DeepSeek。

因此需要在本机运行一层 协议转换代理（本项目使用 codex-bridge）：

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

2. 前置条件

验证 Codex 是否已安装：

codex --version
node --version

3. 需要人工提供的内容

注意：PROXY_AUTH_KEY 不是 DeepSeek Key，也不是 OpenAI Key。它是 Codex 访问本地代理时使用的「本地通行证」，需同时写入 ~/codex-bridge/.env 和 ~/.codex/auth.json，且两者必须完全一致。

4. 涉及的配置文件一览

重要：model_providers、profiles 等 provider 相关配置必须写在 ~/.codex/config.toml（用户级），不要写在项目目录的 .codex/config.toml 中，否则会被忽略。

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

复制示例并编辑：

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

.env 最少需要以下内容（替换占位符）：

# 本地代理鉴权 Key（自行生成，需与 ~/.codex/auth.json 一致）
PROXY_AUTH_KEY=sk-proxy-local-你的随机字符串

# DeepSeek 官方 API Key（人工申请）
DEEPSEEK_API_KEY=sk-你的deepseek密钥

# 对外暴露的模型列表
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash

# 监听端口
PROXY_PORT=4000
LOG_LEVEL=info

5.3 启动脚本（可选）

~/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 "请编辑 ~/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 连接本地代理时使用 OPENAI_API_KEY 字段传递 PROXY_AUTH_KEY（不是 DeepSeek Key）：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-proxy-local-你的随机字符串"
}

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

6.2 ~/.codex/config.toml

在现有配置基础上追加 DeepSeek 相关段落（保留你原有的 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

可选：为项目目录添加信任（首次进入项目时不再反复询问）：

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

6.3 模型说明

7. 验证配置

7.1 启动代理

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

成功时应看到类似输出：

[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 启动 Codex

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

首次进入新目录可能提示：

Do you trust the contents of this directory?

选择 Yes, continue 即可。

常见错误：使用 codex -m deepseek-v4-flash 只会换模型名，不会切换 provider，仍走 OpenAI 路径。必须使用 codex -p deepseek。

8. 日常使用

# 终端 1：启动代理（每次重启电脑或关闭终端后需重新执行）
~/codex-bridge/start.sh

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

后台运行代理：

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

9. 故障排查

10. 配置关系图

┌─────────────────────────────────────────────────────────────┐
│  ~/.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（本地代理鉴权）         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│  ~/codex-bridge/.env                                        │
│  ├── PROXY_AUTH_KEY  ← 与 auth.json 一致                    │
│  └── DEEPSEEK_API_KEY ← 人工申请，转发到 DeepSeek 官方 API   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
                    api.deepseek.com

11. 安全提醒

• 不要将 DEEPSEEK_API_KEY、PROXY_AUTH_KEY 提交到 Git 仓库
• ~/codex-bridge/.env 应保持在本地，加入 .gitignore（若代理目录在 git 仓库内）
• PROXY_AUTH_KEY 仅用于 localhost 鉴权，代理默认只监听本机，不应对外暴露

12. 参考链接

• Codex CLI 官方文档
• Codex 高级配置（Custom model providers）
• codex-bridge 项目
• DeepSeek 开放平台

文档生成环境：macOS，Codex CLI 0.133.0，Node.js 22，代理端口 4000。