让 Codex 桌面版拥抱 DeepSeek-V4：协议桥接与模型网关接入实践

背景：接口鸿沟与性价比的诱惑

OpenAI Codex 已成为许多开发者的日常工具，其桌面版体验日趋成熟。而 DeepSeek 的 V4 模型在编码场景下展现出了优异的性价比和可控的 API 成本。然而两者并不能直连，根本差异在于通信协议：

Codex（0.81.0 及之后版本）使用 Responses API，路径为 /v1/responses，工具调用嵌套在 tools 字段内。
DeepSeek 沿用标准的 Chat Completions API，路径为 /v1/chat/completions，工具调用采用独立的 tool_calls 消息体。

若只是简单地将 Codex 的 base_url 指向 https://api.deepseek.com/v1，通常只会收到 400 错误。解决方案很自然：在本地架设一个轻量翻译层，实时转换两边迥异的请求与响应。

整体架构

数据流极其清晰：

text

┌──────────────────┐       Responses API       ┌─────────────────┐
│  Codex 桌面版     │ ─────────────────────────▶│  codex-bridge    │
│  (示例 v0.129.0)  │  Authorization: Bearer    │  localhost:4000  │
└──────────────────┘                           └────────┬────────┘
                                                        │
                                               Chat Completions API
                                                        │
                                                        ▼
                                             ┌──────────────────┐
                                             │  上游模型服务     │
                                             │ (DeepSeek/网关)  │
                                             └──────────────────┘

中间层使用开源项目 codex-bridge——一个零外部依赖的 Node.js 脚本，专门完成协议翻译。上游模型服务既可以直接填入 DeepSeek 官方地址，也可以指向更为灵活的模型接入网关，后面会展开。

运行环境准备

Windows 10/11 操作系统
Node.js 18 或更新版本
Codex 桌面版（从官方 Releases 获取最新稳定版即可，无需降级）
可用的模型调用凭证（DeepSeek API Key 或网关平台密钥）
能够执行基本命令的终端（PowerShell 或 Git Bash）

实施步骤拆解

第一步：环境核对

在终端中执行：

text

node --version    # 确认 ≥ v18.0.0
codex --version   # 确认显示 cli 版本号

第二步：获取桥接脚本

将仓库克隆到用户目录下的配置路径：

text

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

如果访问 GitHub 不稳定，可以用镜像地址替代，例如 https://gitcode.com/wujfeng712-ui/codex-bridge.git。

第三步：配置环境变量与上游网关

编辑 C:\Users<你的用户名>.codex\codex-bridge.env 文件，填入模型服务信息。这里我们推荐两种上游接入方式：

方式一：直连 DeepSeek 官方

text

DEEPSEEK_API_KEY=sk-你的DeepSeek密钥
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash,deepseek-reasoner
DEFAULT_PROVIDER=deepseek
LOG_LEVEL=info

方式二：通过 4SAPI 模型网关接入（推荐）

如果希望获得更稳定的链路、统一管理多个模型 key，并降低直连可能遇到的限流抖动，可以选择将上游指向 4SAPI 中转站。4SAPI 提供了一套标准的 Chat Completions 接口，完全兼容 DeepSeek V4 Pro 等模型，使用时只需将 base URL 和密钥替换为平台分配的值即可。具体在 .env 中配置如下：

text

DEEPSEEK_API_KEY=你的4SAPI密钥
DEEPSEEK_BASE_URL=https://4sapi.com
DEEPSEEK_MODELS=deepseek-v4-pro,deepseek-v4-flash,deepseek-reasoner
DEFAULT_PROVIDER=deepseek
LOG_LEVEL=info

通过这种方式，所有经由 codex-bridge 发出的请求都会被透明地转发到 4SAPI 网关，网关再按需路由到 DeepSeek 模型。对于终端用户而言，行为和直连完全一致，只是 endpoint 和凭证发生了变更。这样一来，既保留了桥接层的协议转换能力，又获得了网关带来的额外弹性。

无论选择哪种方式，切记：.env 文件中不要给密钥加引号，直接写 sk-xxx 形式，并且该文件包含明文凭据，绝对不要提交到版本控制。

第四步：修改 Codex 自身配置

① 编辑 ~.codex\config.toml，写入：

text

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

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

注意 wire_api 必须为 "responses"，因为 Codex 的新版本已经不再支持 "chat" 模式，协议转换交由桥接层处理。

② 编辑 ~.codex\auth.json，内容如下：

text

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "你的实际密钥"
}

即便使用的是自定义后端，这里的字段名仍必须为 OPENAI_API_KEY，这是 Codex 的固定约定。

③ 执行一次凭证写入：

text

echo "你的实际密钥" | codex login --with-api-key

看到 Successfully logged in 后，可以用 codex login status 确认当前登录状态。

第五步：启动协议桥接服务

text

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

如果一切顺利，终端会打印出监听地址和模型列表。这个窗口必须保持开启，一旦关闭代理就会终止。

第六步：运行 Codex 并切换模型

启动桌面版 Codex，在对话中可通过指令切换：

text

/model deepseek-v4-pro     # 复杂推理与编码
/model deepseek-v4-flash   # 轻量快速编辑

第七步：端到端验证

用 CLI 做一次简单测试：

text

codex exec "回复一个字：好"

输出中应能看到模型名和提供方 local_proxy，并独立返回“好”字，说明整条链路已经贯通。

常遇问题与速查

桌面版仍然弹出登录窗口：可能与 Codex 内置认证逻辑有关，可尝试借助第三方配置工具（如 CC Switch）添加自定义供应商，base URL 指向 http://127.0.0.1:4000/v1，启用后重启。
提示 wire_api = chat is no longer supported：确认 config.toml 中使用的是 wire_api = "responses"。
端口冲突：通过 netstat -ano | findstr ":4000" 定位占用进程并结束，或者在 .env 中修改 PROXY_PORT 并同步更新 base_url。
代理启动后请求超时：核查上游密钥是否正确、本机能否访问上游地址、防火墙是否拦截了 Node.js。
关闭终端后代理停止：参考下文的自动启动方案。

提升运维便利性：代理开机自启

Windows 下可以将桥接服务注册为登录任务。用管理员权限运行 PowerShell：

text

$action = New-ScheduledTaskAction -Execute "node" `
  -Argument "--env-file=$env:USERPROFILE.codex\codex-bridge.env $env:USERPROFILE.codex\codex-bridge\proxy.mjs" `
  -WorkingDirectory "$env:USERPROFILE.codex\codex-bridge"

$trigger = New-ScheduledTaskTrigger -AtLogon

Register-ScheduledTask -TaskName "CodexBridge" -Action $action -Trigger $trigger `
  -Description "Codex → DeepSeek 协议代理" -RunLevel Highest

或者更轻量的方式，在启动文件夹中创建快捷方式，指定起始位置到 codex-bridge 目录，目标为 node --env-file=.env proxy.mjs。

模型切换与多模型策略

在 .env 的 DEEPSEEK_MODELS 中维护逗号分隔的模型名，重启代理后即可在 Codex 中通过 /model 灵活切换。无论是官方直连还是通过 4SAPI 网关，只要远端提供了这些模型名，都能被正确解析。

方案对比总结

对比维度	本方案（本地桥接 + 最新 Codex）	降级至旧版 Codex (0.80.0)
版本策略	跟随官方最新发布	锁定特定旧版
功能演进	持续获得新特性	功能固化
维护风险	依赖桥接层更新	旧版不再维护
上手复杂度	中等，一次性配置	较低，但牺牲功能
上游灵活度	可自由切换官方或网关	受限于旧版兼容性

整体而言，用本地协议转换层来打通 Codex 与 DeepSeek，是兼顾新特性与成本的有效路径。而上游引入 4SAPI 这样的模型网关，则进一步提升了链路的稳定性和密钥管理的便捷度，尤其适合团队或对服务可用性有更高要求的场景。整个配置过程只涉及一次性的文件修改，后续使用与原生体验别无二致。