Codex桌面版接入DeepSeek V4本地桥接版配置指南

想用Codex，但是想用便宜的DeepSeek。

接入背景

Codex 已经成为不少开发者日常写代码、改项目和处理工程任务时常用的 AI 编程工具，它同时提供命令行环境与桌面端入口，适合在真实代码仓库中完成解释、重构、补全、调试和批量修改等工作。DeepSeek V4 则更偏向高性价比模型后端，尤其在代码生成、长上下文理解和代&理式任务处理中具备较强吸引力，因此很多人会希望把 Codex 的前端工作流与 DeepSeek 的模型能力结合起来使用。

不过，二者不能直接通过简单替换 API 地址完成对接。主要问题不在于密钥或模型名称，而在于两边默认采用的接口形态并不一致：Codex 新版自定义模型供应商侧更倾向于使用 Responses API 结构，而 DeepSeek 官方 OpenAI 兼容接口主要接收 Chat Completions 格式。因此，如果直接把 Codex 的 base_url 指向 DeepSeek 官方地址，常见结果是请求路径、消息结构或工具调用字段无法匹配，最终出现 400、模型不可用或工具调用失败等问题。

对比项	Codex 新版	DeepSeek V4 API	差异说明
主要使用场景	AI 编程助手、项目级代码修改、CLI / 桌面端协作	模型推理服务、代码生成、长上下文与通用问答	Codex 更像客户端工作流，DeepSeek 更像模型服务后端
推荐接口形态	Responses API	Chat Completions API	两者请求体结构不同，不能直接互换
常见请求路径	/v1/responses	/chat/completions	直接改 base_url 容易出现路径不匹配
消息输入方式	input / response items	messages 数组	需要把 Codex 输入转换成 Chat messages
工具调用结构	Responses API 内部 output item / tool call 结构	Chat Completions 中的 tool_calls	编程代&理场景必须正确转换工具调用
模型配置位置	~/.codex/config.toml	DeepSeek 控制台与 API 请求参数	Codex 侧需要配置 provider，DeepSeek 侧需要有效 API Key
典型模型名	由 Codex 配置中的 model 指定	deepseek-v4-pro、deepseek-v4-flash	建议优先使用 DeepSeek V4 官方模型名
直接对接结果	通常不稳定或报错	无法理解 Codex 的 Responses 请求	需要中间层做协议适配

因此，更稳妥的方案是在本机启动一个轻量桥接服务。Codex 只连接本地代&理，本地代&理负责接收 Codex 发来的 Responses API 请求，再转换为 DeepSeek 可识别的 Chat Completions 请求；DeepSeek 返回结果后，代&理再把响应重新包装成 Codex 能读取的格式。这样既不需要降低 Codex 版本，也不需要修改客户端程序，还能保留新版 Codex 的配置方式与桌面端体验。

目标：不回退 Codex 版本、不修改客户端程序，通过本机转发服务，把 Codex 的新版请求格式转换为 DeepSeek API 可识别的调用格式。

1. 基本原理

Codex 新版调用自定义模型时，主要走的是 Responses API 风格；而 DeepSeek 官方 OpenAI 兼容接口主要使用 Chat Completions 风格。两者字段结构、接口路径和工具调用格式并不完全一致，所以不能简单把 Codex 的 base_url 直接改成 DeepSeek 地址。

本方案的中间层作用如下：

Codex Desktop / Codex CLI
        │
        │  Responses API 风格请求
        ▼
本机桥接服务：127.0.0.1:4000/v1
        │
        │  Chat Completions 风格请求
        ▼
DeepSeek API：api.deepseek.com

本地桥接服务主要负责：

• 接收 Codex 发出的 /v1/responses 请求；
• 将 input、tools、tool_call 等结构转换为 DeepSeek 可处理的 Chat Completions 格式；
• 把 DeepSeek 返回内容再包装成 Codex 期望的 Responses API 输出；
• 暴露 /v1/models，方便 Codex 识别可用模型；
• 处理流式输出，避免 Codex 长任务卡死。

2. 准备工作

2.1 必要环境

建议先准备好：

• Node.js 18 或更高版本；
• Codex Desktop 最新版；
• Codex CLI；
• DeepSeek API Key；
• 一个可用的终端环境，例如 PowerShell、Git Bash、Terminal 或 iTerm2。

2.2 检查版本

在终端执行：

node --version
codex --version

Node.js 版本建议不低于：

v18.0.0

如果 codex --version 无法识别，说明 Codex CLI 尚未正确安装或环境变量没有生效。

3. 安装本地桥接服务

以下以 codex-bridge 类型的 Node.js 本地代&理为例。你也可以换成其他支持 Responses API 与 Chat Completions API 互转的同类项目。

3.1 创建目录

mkdir -p ~/.codex

3.2 克隆项目

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

如果 GitHub 访问不稳定，可以使用可信镜像源，但要注意确认代码是否与原仓库一致，避免 API Key 泄露风险。

4. 配置 DeepSeek 访问参数

进入桥接服务目录：

cd ~/.codex/codex-bridge

创建或编辑 .env 文件：

nano .env

Windows 用户也可以直接用记事本打开：

C:Users你的用户名.codexcodex-bridge.env

推荐写法：

DEEPSEEK_API_KEY=sk-你的DeepSeek密钥
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash
DEFAULT_PROVIDER=deepseek
PROXY_HOST=127.0.0.1
PROXY_PORT=4000
LOG_LEVEL=info

注意事项：

• .env 必须逐行书写，不要把多个配置挤在一行；
• API Key 不建议加引号；
• .env 中是明文密钥，不要上传到 GitHub；
• 如果桥接项目使用的变量名不同，应以该项目 README 为准；
• 推荐优先使用 deepseek-v4-pro 和 deepseek-v4-flash，不建议长期依赖旧别名。

5. 配置 Codex

Codex 用户级配置文件通常位于：

~/.codex/config.toml

Windows 对应路径通常是：

C:Users你的用户名.codexconfig.toml

macOS 对应路径通常是：

/Users/你的用户名/.codex/config.toml

打开配置文件后，写入或合并以下内容：

model = "deepseek-v4-pro"
model_provider = "deepseek_bridge"
cli_auth_credentials_store = "file"

[model_providers.deepseek_bridge]
name = "DeepSeek V4 Local Bridge"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

这里的关键点是：

wire_api = "responses"

不要写成：

wire_api = "chat"

新版 Codex 中，chat 类型已经不适合作为主配置使用。

6. 是否需要配置 API Key 到 Codex

通常有两种方式。

方案 A：由本地桥接服务读取.env

这是更推荐的方式。Codex 只连本地地址，DeepSeek Key 由桥接服务负责读取。

此时 config.toml 中不需要额外写：

env_key = "DEEPSEEK_API_KEY"

方案 B：让 Codex 通过环境变量传递 Key

如果你的桥接服务要求 Codex 也发送 Authorization 请求头，可以在 config.toml 中增加：

env_key = "DEEPSEEK_API_KEY"

然后设置系统环境变量。

Windows PowerShell：

[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-你的DeepSeek密钥", "User")

macOS / Linux：

echo 'export DEEPSEEK_API_KEY="sk-你的DeepSeek密钥"' >> ~/.zshrc
source ~/.zshrc

如果 Codex Desktop 是从图形界面启动，macOS 可能还需要：

launchctl setenv DEEPSEEK_API_KEY "sk-你的DeepSeek密钥"

7. 启动桥接服务

进入项目目录：

cd ~/.codex/codex-bridge

启动代&理：

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

如果启动成功，通常会看到类似输出：

Listening on http://127.0.0.1:4000
Default provider: deepseek
Models: deepseek-v4-pro, deepseek-v4-flash

这个终端窗口需要保持开启。关闭窗口后，本地桥接服务会停止，Codex 就无法继续访问 DeepSeek。

8. 验证 DeepSeek API 是否可用

先测试 DeepSeek 官方接口本身是否正常：

curl https://api.deepseek.com/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer sk-你的DeepSeek密钥" 
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {
        "role": "user",
        "content": "只回复一个字：好"
      }
    ],
    "stream": false
  }'

如果这里失败，优先检查：

• API Key 是否正确；
• DeepSeek 账户是否还有余额；
• 模型名是否写错；
• 本机网络能否访问 DeepSeek；
• 是否被代&理、防火墙或 DNS 拦截。

9. 验证本地桥接服务

9.1 检查模型列表

curl http://127.0.0.1:4000/v1/models

理想情况下应能看到：

deepseek-v4-pro
deepseek-v4-flash

如果这里没有模型列表，Codex 里的 /model 切换可能无法正常工作。

9.2 检查 Responses API 转换

curl http://127.0.0.1:4000/v1/responses 
  -H "Content-Type: application/json" 
  -d '{
    "model": "deepseek-v4-pro",
    "input": "只回复一个字：好"
  }'

如果能正常返回“好”，说明桥接服务已经能把 Codex 风格请求转成 DeepSeek 请求。

10. 验证 Codex CLI

执行：

codex exec "只回复一个字：好"

如果最后输出：

好

说明链路已经打通：

Codex CLI → 本地桥接服务 → DeepSeek API

可以继续测试一个更接近真实编码场景的请求：

codex exec "写一个 Python 函数，接收字符串列表，返回按长度排序后的新列表。"

11. 在 Codex Desktop 中使用

确认本地桥接服务已经启动后，再打开 Codex Desktop。

进入对话后可以尝试切换模型：

/model deepseek-v4-pro

或：

/model deepseek-v4-flash

推荐选择：

deepseek-v4-pro    适合复杂代码分析、架构调整、长上下文任务
deepseek-v4-flash  适合快速问答、轻量修改、短代码补全

12. 常见问题处理

12.1 提示wire_api = chat is no longer supported

检查 ~/.codex/config.toml，确保是：

wire_api = "responses"

不要使用：

wire_api = "chat"

12.2 直接连接 DeepSeek 后返回 400

这是因为 Codex 请求的是 Responses API，而 DeepSeek 主要接收 Chat Completions API。两者不能直接互通，需要本地桥接服务做格式转换。

错误思路：

base_url = "https://api.deepseek.com/v1"
wire_api = "responses"

推荐思路：

base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"

12.3 Codex Desktop 仍然弹出登录窗口

可以先检查 CLI 登录状态：

codex login status

如需初始化 API Key 登录，可尝试：

codex login --with-api-key

如果桌面端仍要求登录，可能是 Codex Desktop 当前版本的认证逻辑限制。此时可以：

• 先确认 CLI 是否能正常使用；
• 重启 Codex Desktop；
• 检查 cli_auth_credentials_store = "file" 是否写在顶层；
• 避免频繁手动修改 auth.json，因为该文件结构可能随版本变化。

12.4/model找不到 DeepSeek 模型

优先检查：

curl http://127.0.0.1:4000/v1/models

如果没有返回模型列表，需要检查 .env：

DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash

修改 .env 后，要重启桥接服务。

12.5 端口 4000 被占用

Windows：

netstat -ano | findstr ":4000"
taskkill /PID  /F

macOS / Linux：

lsof -i :4000
kill -9 

也可以换一个端口，例如 4001。

.env：

PROXY_PORT=4001

config.toml：

base_url = "http://127.0.0.1:4001/v1"

12.6 普通聊天正常，但改代码不稳定

这通常说明桥接服务只完成了基础文本转换，没有完整处理 Codex 的工具调用流程。

稳定的编程代&理桥接至少需要支持：

tools
tool_calls
tool result
stream events
response output items
file edit related calls

如果这些转换不完整，可能会出现：

• 能回答问题，但无法正确读写项目文件；
• 能生成代码，但不能可靠应用补丁；
• 长任务中途停止；
• 工具调用返回结构不符合 Codex 预期；
• 流式输出卡住。

13. Windows 开机自动启动

可以用任务计划程序创建自启动任务。

PowerShell 示例：

$bridge = "$env:USERPROFILE.codexcodex-bridge"

$action = New-ScheduledTaskAction `
  -Execute "node.exe" `
  -Argument "--env-file=`"$bridge.env`" `"$bridgeproxy.mjs`"" `
  -WorkingDirectory $bridge

$trigger = New-ScheduledTaskTrigger -AtLogon

Register-ScheduledTask `
  -TaskName "CodexDeepSeekBridge" `
  -Action $action `
  -Trigger $trigger `
  -Description "Local bridge for Codex and DeepSeek V4" `
  -RunLevel Highest `
  -Force

查看任务：

Get-ScheduledTask -TaskName "CodexDeepSeekBridge"

删除任务：

Unregister-ScheduledTask -TaskName "CodexDeepSeekBridge" -Confirm:$false

14. macOS 开机自动启动

先确认 Node 路径：

which node

创建 LaunchAgent：

cat > ~/Library/LaunchAgents/com.codex.deepseek.bridge.plist <<'EOF'



  
    Label
    com.codex.deepseek.bridge
    ProgramArguments
    
      /usr/local/bin/node
      --env-file
      /Users/你的用户名/.codex/codex-bridge/.env
      /Users/你的用户名/.codex/codex-bridge/proxy.mjs
    
    WorkingDirectory
    /Users/你的用户名/.codex/codex-bridge
    RunAtLoad
    
    KeepAlive
    
    StandardOutPath
    /tmp/codex-deepseek-bridge.out.log
    StandardErrorPath
    /tmp/codex-deepseek-bridge.err.log
  

EOF

注意替换：

/Users/你的用户名

如果 which node 显示的不是 /usr/local/bin/node，也要同步替换 plist 中的 Node 路径。

加载服务：

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.codex.deepseek.bridge.plist
launchctl enable gui/$UID/com.codex.deepseek.bridge
launchctl kickstart -k gui/$UID/com.codex.deepseek.bridge

查看日志：

tail -f /tmp/codex-deepseek-bridge.out.log
tail -f /tmp/codex-deepseek-bridge.err.log

卸载服务：

launchctl bootout gui/$UID ~/Library/LaunchAgents/com.codex.deepseek.bridge.plist
rm ~/Library/LaunchAgents/com.codex.deepseek.bridge.plist

15. 安全建议

使用本地桥接时，重点注意以下几点：

• 只监听 127.0.0.1，不要开放到 0.0.0.0；
• 不要把 .env、auth.json、日志文件上传到公开仓库；
• 不要把 API Key 截图发给别人；
• 尽量使用源码可审计的桥接项目；
• 使用第三方工具前，先检查是否会上传请求内容或密钥；
• 发现 Key 泄露后，立即到 DeepSeek 控制台删除旧 Key 并重新生成；
• 如果多人共用电脑，不建议把密钥放在容易被读取的目录中。

16. 推荐最终配置

16.1.env

DEEPSEEK_API_KEY=sk-你的DeepSeek密钥
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash
DEFAULT_PROVIDER=deepseek
PROXY_HOST=127.0.0.1
PROXY_PORT=4000
LOG_LEVEL=info

16.2~/.codex/config.toml

model = "deepseek-v4-pro"
model_provider = "deepseek_bridge"
cli_auth_credentials_store = "file"

[model_providers.deepseek_bridge]
name = "DeepSeek V4 Local Bridge"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

16.3 启动命令

cd ~/.codex/codex-bridge
node --env-file=.env proxy.mjs

16.4 测试命令

codex exec "只回复一个字：好"

总结

这套方案本质上不是修改 Codex，而是在本机增加一个协议适配层：

Codex 需要 Responses API
DeepSeek 提供 Chat Completions API
本地桥接服务负责双向转换

只要桥接服务正确实现 /v1/models、/v1/responses、流式输出和工具调用转换，就可以在保留 Codex 新版功能的同时，使用 DeepSeek V4 作为代码任务后端。

对于日常使用，建议默认选择：

deepseek-v4-pro

对于快速问答或轻量代码修改，可以切换为：

deepseek-v4-flash