DeepSeek接入Codex：解决协议不匹配的完整配置指南

把 DeepSeek 接进 Codex 这个事最近问的人特别多。原因也简单Codex CLI 用起来确实顺但官方默认只认自己的模型和 Responses APIDeepSeek 的接口走的是 Chat Completions 兼容格式两边协议对不上导致很多人配置到一半就卡住。这篇文章把我实际跑通的完整链路整理出来从报错原因、方案选型到每一步操作尽量让还没搞定的人照着做就能通。先说结论新版 Codex 并不是不能接 DeepSeek而是默认情况下它只会往/v1/responses这个端点发请求DeepSeek 服务端没有这个接口所以一调就报错。解决办法也很直接让 Codex 改用 Chat Completions 协议跟 DeepSeek 通信就行根本不需要写复杂的中间层。下面我会把原理、配置和踩坑记录全部摊开讲。1. 先说清楚问题是怎么来的这部分我尽量不绕弯子把三个关键概念一次讲透Responses API 是什么、Chat Completions API 是什么以及新版 Codex 为什么卡在这一层。1.1 Responses API 和 Chat Completions API 到底差在哪OpenAI 早期的接口是/v1/chat/completions大家习惯叫它 Chat Completions API。请求体里传model、messages、temperature这些参数返回结果里通过choices[0].message拿模型回复。这个协议已经非常成熟现在绝大多数兼容 OpenAI 的服务商包括 DeepSeek都是照着这套格式实现的。后来 OpenAI 在 2024 年底推出了 Responses API端点是/v1/responses。它在设计上想解决两件事一是把多轮对话、工具调用、联网搜索、文件检索这些都收进一个统一的接口二是返回结构更加规范化不再是choices列表而是output数组。这个设计对官方生态是好事但对第三方模型厂商来说就有点麻烦因为要重新实现一套完全不同的协议。一个很直观的对比同样的“用 Python 写一个快速排序”Chat Completions 的请求长这样{ model: deepseek-chat, messages: [ {role: user, content: 用 Python 写一个快速排序} ] }而 Responses API 的请求是另一套结构消息不再叫messages改成了input返回里面的output也不是简单的message对象。这两套协议之间没有自动兼容的机制服务端只实现了哪套客户端就必须用哪套去对接。1.2 新版 Codex 为什么非要走 Responses APICodex CLI 早期版本用的就是 Chat Completions 兼容方式所以那时候网上很多教程直接改base_url就能接上各种第三方模型。但 Codex 升级之后官方把模型的调用链路整体切换到了 Responses API本地不再自己去组 Chat Completions 请求而是把所有请求统一发到/v1/responses。问题就在这如果你还按照老教程把base_url指向https://api.deepseek.com/v1Codex 会往https://api.deepseek.com/v1/responses发请求而 DeepSeek 服务端根本没有这个路由自然就报错。很多人在网上搜到类似endpoint /responsesfailed 的错误其实就是这一层协议不匹配。我记得第一次复现这个报错的时候也一脸懵明明 API Key 没问题、模型名也没问题为什么一调用就失败后来抓了一下请求日志才明白Codex 压根没按 Chat Completions 的格式发请求。所以这个问题的本质不是 DeepSeek 不稳定也不是 Codex 不能用而是两边各说各话中间缺一个“翻译”。1.3 DeepSeek 那边到底支持什么DeepSeek 官方 API 是 OpenAI 兼容的但这一点要说得严谨一些它兼容的是 Chat Completions 这一路/v1/responses接口到现在都没有开放。DeepSeek 开放平台提供的base_url是https://api.deepseek.com/v1也可以用https://api.deepseek.com模型名主要就两个deepseek-chat和deepseek-reasoner。也就是说DeepSeek 侧能做的事情很有限你不能指望它临时上线一个 Responses API 兼容层。现阶段最现实的思路就两条要么让 Codex 改回 Chat Completions 协议去请求要么在本地起一个转换服务把请求转成 DeepSeek 能识别的格式。第二条路是兜底方案第一条路才是真正省事的解法。2. 三种接入方案我建议你选哪种网上关于接 DeepSeek 的方案五花八门有改环境变量的、有挂网关的、有用各种小工具的。我实际试了一圈把它们按推荐程度排个序。2.1 方案一直接改 config.toml最推荐这个方案的核心是 Codex 的配置文件里有一个很容易被忽略的字段wire_api。它支持两个值responses和chat。默认是responses只要你在自定义 provider 里把它改成chatCodex 就会用 Chat Completions 协议发请求DeepSeek 那边直接就能接住。这个配置写起来非常简单不依赖任何第三方服务也不需要在本地额外跑一个进程。我把它放在最前面推荐是因为它最干净、最不容易出幺蛾子。很多人卡在“新版 Codex 不支持第三方模型”的误区里其实就是不知道有wire_api这个字段。具体配置我放在第三章完整展开这里先说明一点官方文档对这个字段的说明非常少但它确实是新版 Codex 留给第三方模型的正规入口。社区里很多人通过这个字段接入了 Ollama、vLLM 这类本地推理服务原理跟接 DeepSeek 完全一致。2.2 方案二本地转换网关兜底方案wire_api chat这个字段不是所有版本的 Codex 都好使。我见过有些版本在部分场景下依然强制走 Responses API尤其是桌面版在联网搜索、工具调用这些功能上可能会绕回默认协议。真遇到这种情况就需要一个本地转换网关。这个网关的作用很简单在本地监听一个端口Codex 把请求发到http://127.0.0.1:8787/v1/responses网关收到后把它翻译成 Chat Completions 格式再转发给 DeepSeek最后把 DeepSeek 的返回结果按照 Responses API 的结构回给 Codex。这类工具社区里已经有很多比如之前流行的 cc-switch、一些自制的网关脚本都可以实现。如果你只是临时用用我建议优先试方案一如果方案一在你的环境下确实走不通再考虑这个兜底方案。它多了一层本地进程排查问题的时候会稍微麻烦一点。2.3 方案三用 cc-switch 这类配置管理工具cc-switch 是社区里一个专门用来管理 Codex、Claude Code 等工具 provider 配置的小工具可以一键切换不同模型服务商省得每次手动改config.toml。它本质上做的事情跟方案一是一样的只是把配置动作封装成了图形界面或者命令行交互。如果你经常在 DeepSeek、OpenAI、本地模型之间来回切换cc-switch 能省不少事。但如果你只是想把 DeepSeek 接上然后用起来我建议先手动配置一次理解了原理之后再去用工具不然出了问题都不知道去哪排查。我自己见过不少人用 cc-switch 配完还是报错最后发现是工具的模板版本太老里面的 provider 配置根本没有wire_api chat所以请求还是走的老协议。3. 完整接入实操每一步都可复现这一章是全文的重点我按自己实际跑通的顺序把每个步骤和参数都写清楚。环境是 macOS Node.js 20Windows 的差异点我会单独标注。3.1 安装 Codex CLICodex 的安装方式有三种我建议优先用 npm 全局安装因为版本最新而且不太会遇到安装包卡住的问题。npm install -g openai/codex安装完成后验证一下版本codex --version能正常输出版本号就说明装好了。如果你用的是 Windows安装包方式有概率卡在“正在完成安装”这一步我试过几次都不太顺利最后还是用 npm 装上的。另外建议直接使用官方渠道下载不要从第三方下载站拿安装包网上流传的一些“破解版”“绿色版”不仅版本旧还有安全风险。安装完之后先不用急着登录 OpenAI 账号因为我们接 DeepSeek 根本不走官方认证。这一点很多人没意识到结果一运行就卡在登录界面。3.2 准备 DeepSeek API Key登录 DeepSeek 开放平台在控制台里找到 API Keys 页面创建一个新的 Key。创建的时候它会完整显示一次一定要立刻复制保存关闭页面之后你就只能重新创建了。DeepSeek 的接口是按量计费的新注册的账号可能会有少量免费额度但真正要稳定调用最好先充值一点。别小看这一步我遇到过不少人在配置完全正确的情况下还是报 401 鉴权失败最后发现是账号余额不足请求根本到不了模型层。复制出来的 Key 长这样sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx这个 Key 是你访问 DeepSeek 的唯一凭证不要把它写进配置文件里。正确做法是放到环境变量里这样即使config.toml不小心被分享出去也不会泄露密钥。3.3 编写 config.toml 配置文件Codex 的配置文件路径在 macOS/Linux 下是~/.codex/config.tomlWindows 下是%USERPROFILE%\.codex\config.toml。如果文件不存在就手动创建目录也一起建好。直接贴一份我实测可用的完整配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat逐项解释一下方便你自己调整model要使用的模型名这里填deepseek-chat。如果你需要跑推理类任务比如数学题、逻辑分析可以改成deepseek-reasoner。model_provider指定使用下面哪个 provider 配置必须跟[model_providers.deepseek]里的名字一致。nameprovider 的显示名称随便写不影响调用。base_urlDeepSeek 接口地址。这里要注意结尾的/v1不能漏Codex 会在后面拼接/chat/completions路径。env_key指定哪个环境变量存放 API Key。这里写DEEPSEEK_API_KEY就要求你在环境变量里设置一个叫DEEPSEEK_API_KEY的值。wire_api最关键的一项必须改成chat这样 Codex 才会走 Chat Completions 协议。不写或者写成responses就会回到默认的 Responses API继续报错。配好之后保存文件。这里有个小细节Codex 的配置文件是 TOML 格式键值对之间不要多写逗号字符串要加引号布尔值不要加引号。格式错了 Codex 启动时会直接提示解析失败问题倒是不难发现。3.4 配置环境变量并启动验证打开终端把刚才的 Key 设置成环境变量export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWindows PowerShell 下是这样$env:DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx这里要特别注意环境变量只在当前终端窗口里生效。如果你关闭了这个终端再重新打开需要重新设置。更好的办法是写到 shell 配置文件里比如~/.zshrc或~/.bashrc这样每次打开终端自动加载。设置完之后先跑一个最简单的命令测试连通性codex exec 用 Python 写一个快速排序直接输出代码正常情况下 Codex 会调用 DeepSeek 返回结果。第一次调用可能会慢一点因为需要建立连接后面就快了。如果codex exec没问题再试试交互模式codex进入交互界面后随便问一个问题能正常回答就说明整条链路已经通了。我在实际测试中发现交互模式下 Codex 可能会多做一些工具调用的尝试DeepSeek 的deepseek-chat模型对工具调用的支持有限偶尔会出现一次调用不发工具请求的情况这属于正常现象不影响常规的代码问答和生成。3.5 用 cc-switch 管理多个 provider可选如果你需要在多个模型之间频繁切换可以考虑用 cc-switch。它的原理就是帮你改写config.toml省得手动编辑。用 cc-switch 的时候要注意版本问题。我遇到过的情况是cc-switch 自带的 DeepSeek 模板里只有base_url和env_key没有wire_api chat这个字段导致切换之后 Codex 依然走 Responses API一调用就报endpoint /responses错误。解决办法有两个一是看 cc-switch 有没有提供自定义模板的功能自己加一行wire_api chat二是直接用 cc-switch 切换到 DeepSeek 之后再手动打开config.toml补上这个字段。我个人更推荐第二种简单直接还不会覆盖掉已有配置。4. 常见报错排查与实战记录代码类工具真正折腾人的地方从来不是配置本身而是各种报错。这一章把我遇到过的、以及社区里高频出现的问题整理成速查表再挑几个典型的讲一下排查思路。4.1 报错速查表报错信息原因解决办法cc switch local proxy failed while handling codex endpoint /responsescc-switch 的 provider 模板走了旧的本地转换逻辑没有使用wire_api chat手动在 config.toml 补上wire_api chat或更新 cc-switch 模板The gpt-5.6-sol model is not supported when using codex with ...没有正确配置model_providerCodex 还是用默认的官方模型名去请求在 config.toml 里显式写上model deepseek-chat和model_provider deepseekcodex auth token is unavailable启动时走了 OpenAI 的全局认证逻辑确认model_provider配置正确DEEPSEEK_API_KEY环境变量已设置如果仍然提示可将~/.codex/auth.json临时改名移走重试401 Authentication ErrorDeepSeek API Key 错误或者账号没有余额检查 Key 是否复制完整登录 DeepSeek 平台确认账号有可用余额Model Not Exist模型名拼写错误使用deepseek-chat或deepseek-reasoner不要用网上流传的各种非官方命名Windows 安装包卡在“正在完成安装”安装包在个别 Windows 环境下会卡住改用npm install -g openai/codex安装4.2 几个印象很深的排查实录第一个是cc switch local proxy failed while handling codex endpoint /responses。这个报错的特点是不能直接看出问题在哪我当时第一反应是 Codex 配置错了但反复检查base_url和 Key 都没问题。后来才发现cc-switch 在切换 provider 的时候会把base_url改成一个本地地址然后在本地起一个转换进程。这个转换进程默认还是按 Responses API 去转发所以链路就变成了 Codex 找本地进程、本地进程又去找 DeepSeek 的/responses两边都在等对方最终超时报错。解决方式就是开头说的让 provider 直接走wire_api chat绕过那个本地转换进程。第二个是gpt-5.6-sol这个模型不存在的报错。这个报错常见于那些之前用过官方模型、后来切换到 DeepSeek 但没改干净的情况。Codex 启动时会读取config.toml里的model字段如果你没有显式指定它就用内置的默认模型名去请求而 DeepSeek 当然不认识这个模型名。解决方式很直接在配置里显式写上model deepseek-chat和model_provider deepseek。第三个是环境变量的问题。我在终端里明明设置了DEEPSEEK_API_KEY但 Codex 桌面版还是提示没有凭证。排查之后发现桌面版启动时不会加载终端里临时设置的环境变量它是从系统环境变量里读的。解决办法要么在系统环境变量里永久设置这个 Key要么从设置了环境变量的终端里启动 Codex。这个问题在 macOS 上比较常见Windows 上反而少一些。4.3 接入之后的一些实用调优建议配置跑通之后还有几个小经验可以分享。关于模型选择日常写代码、改 bug 用deepseek-chat就够了速度快、成本低遇到比较复杂的推理题、系统设计分析可以临时切到deepseek-reasoner它的深度思考能力明显强一截但响应时间和费用也会更高。我目前的做法是默认用deepseek-chat需要深度分析时再改配置切一次。关于任务拆分Codex 的exec模式比较适合单次明确的指令比如“给这个函数补上类型注解”“把这段逻辑重构成面向对象写法”。一次只做一件事返回质量会稳定很多。如果你把一个很大的需求一次性丢给它虽然也能跑但中间一旦某个步骤理解偏了后面可能越跑越偏。关于费用控制DeepSeek 的定价本身不贵但 Codex 在交互模式下会频繁请求有时候还会带上下文重发一天用下来量也不小。建议在 DeepSeek 平台设置好调用上限或者定期留意账单避免出现“跑了个大任务结果费用超出预期”的情况。还有一个容易被忽略的点不要把DEEPSEEK_API_KEY和OPENAI_API_KEY同时设置为同一个值或者互相混用。Codex 对不同的 provider 会读取对应的env_key但如果环境变量里同时存在两个 Key某些版本可能会出现读取混乱的情况。我现在只保留DEEPSEEK_API_KEY把OPENAI_API_KEY从环境变量里清掉了省心很多。我在实际使用中的一点体会是这类接入问题绝大多数时候不是“不支持”而是协议没对齐。Codex 这边只要把wire_api换成chatDeepSeek 就能正常接收请求。这个思路也不局限在 DeepSeek换成其他兼容 OpenAI 接口的模型服务也是一样的操作。希望这篇整理能帮你少走几步弯路配置好一次之后后面切换模型、切换工具都能更顺手。