我最近被问得最多的问题就是“Codex 到底能不能接 DeepSeek”。答案是能而且接完之后日常跑代码任务的体验相当不错——DeepSeek 的 API 价格比 OpenAI 自家模型便宜一大截而 Codex 这个终端里的编程代理工具本身又非常顺手两者一组合相当于用零头成本拿到一个能自动读代码、改文件、跑命令的 AI 结对程序员。这篇教程我会完整走一遍 Codex 接入 DeepSeek 的流程重点讲清楚几个别人文档里很少说明白的地方为什么 DeepSeek 不能直接用 Codex 默认配置跑通、cc-switch 这个本地代理在中间到底起了什么作用、还有那个高频报错“local proxy failed while handling codex endpoint /responses”到底该怎么排查。无论你是第一次接触 Codex还是已经折腾了半天卡在配置上这篇都能给你一条走通的路线。1. 先搞清楚原理Codex 的“点菜方式”和 DeepSeek 的“厨房规矩”很多人一上来就去改配置结果配了半天还是报错根本原因是没有理解 Codex 和 DeepSeek API 在协议层面上的差异。我先用大白话把这层窗户纸捅破。1.1 Codex 默认走的是哪条链路Codex 是 OpenAI 推出的终端编程代理它会根据你的自然语言指令自主完成“读代码—定位问题—修改文件—执行命令—验证结果”这样的闭环操作。既然是 OpenAI 自家产品它默认当然是连 OpenAI 自家的模型服务而这一层通信走的是Responses API也就是 2024 年之后 OpenAI 主推的新版接口协议。这个“协议”你可以理解为点菜方式Codex 是一个点菜员它习惯用一套特定格式的菜单协议跟厨房模型服务交流——菜名、口味、加辣程度都写在一张固定格式的单子上。Responses API 就是这套新格式。问题在于DeepSeek 的厨房目前只认另一套格式。DeepSeek 官方 API 完全兼容OpenAI Chat Completions API也就是老版的“对话补全”格式。这就好比 Codex 拿着新格式的单子走进 DeepSeek 的厨房厨房老板看了一眼说“你这单子我看不懂我们这儿只收老式单子。”1.2 DeepSeek 兼容的是哪一类接口这里要区分两个概念API 兼容和协议一致。DeepSeek 开放平台提供的接口地址是https://api.deepseek.com它支持 OpenAI 的 Chat Completions 格式这意味着你从 OpenAI 切到 DeepSeek只需要换掉 Base URL 和 API Key请求体结构基本不用改。市面上很多工具比如 Dify、VS Code 插件、各类客户端都是因为这个兼容性才能把 DeepSeek 作为“OpenAI 兼容供应商”添加进去。但 Codex 默认用的是 Responses API而 DeepSeek 目前没有提供 Responses 接口。如果你强行让 Codex 用默认方式去连 DeepSeek它发出的请求是“新格式单子”对方厨房不认自然就报错。1.3 所以需要一个“翻译/路由层”这就是 cc-switch 这类工具存在的理由。cc-switch 本质上是一个 API 供应商切换器它在本地起一个代理服务Codex 把请求发给这个本地代理代理再把请求转换成 DeepSeek 能识别的格式转发出去拿到结果后再翻译回 Codex 能读的格式返回。你可以把它想象成一个双语翻译。Codex 说新格式DeepSeek 只认老格式翻译坐在中间把两边的话互相转述。有了这一层你就不用去改 Codex 内部的协议实现只需要告诉 Codex“你把请求发到本地代理就行”。理解了这条链路后面所有配置和排错都会有方向感。接下来我们进入实操。2. 安装准备Codex 本体与登录验证在接 DeepSeek 之前你得先保证 Codex 本体能跑起来。这一步虽然简单但我见过不少人在 npm 版本、Node 版本、登录方式这几个细节上卡壳。2.1 用 npm 安装命令行版Codex 的 CLI 最新版本安装方式很简单npm install -g openai/codex装完之后验证一下codex --version如果提示找不到命令常见原因是 npm 的全局 bin 目录没有加到系统 PATH 里。macOS 上通常需要检查/opt/homebrew/bin或/usr/local/binWindows 上则需要确认 npm 全局目录是否在环境变量中。装好之后codex --help能看到可用命令列表说明安装没问题。如果你的网络环境拉 npm 包很慢可以临时切换 registry 到国内镜像源装完再切回来npm config set registry https://registry.npmmirror.com npm install -g openai/codex npm config set registry https://registry.npmjs.org这算是个常规操作我在帮朋友排错时经常用到省时间。2.2 桌面版与终端版的区别除了命令行版Codex 还提供了桌面版应用。桌面版适合那些不习惯在终端里操作的场景但如果你最终目标是接入 DeepSeek 并配合 Cursor、VS Code 这类编辑器使用CLI 版依然是核心因为配置文件和命令都是围绕 CLI 展开的。这里我给一个建议主力使用 CLI 版。桌面版界面虽然友好但它的供应商配置入口经常变动社区里查报错方案时大家默认都是拿 CLI 版的目录结构来说事的比如~/.codex/config.toml这个文件。CLI 版出了问题你自己能改配置桌面版反而更黑盒。安装完成后Codex 需要登录 OpenAI 账号。运行codex login会弹出浏览器授权页面用 ChatGPT 或 GitHub 账号登录即可。这一步主要目的是让 Codex 拿到一个默认的鉴权凭据因为后续我们在配置里替换成 DeepSeek 的 API Key 时Codex 其实只是需要一个“看起来合法的凭据位置”具体用谁的 Key 是我们说了算。2.3 先跑一次默认配置确认环境登录完成后先不要急着接 DeepSeek跑一次默认配置codex write a hello world script in python如果 Codex 能正常响应、能创建文件、能执行命令说明环境是完好的。这一步很重要因为后面排查问题时我们需要知道“Codex 本身是好的问题出在供应商配置上”。3. 接入主流程用 cc-switch 本地代理对接 DeepSeekCodex 装好之后我们正式进入接入环节。我推荐的第一条路径就是 cc-switch原因很简单它把协议转换、供应商路由、Key 管理都封装好了你不需要去折腾 Codex 的底层配置接下来我会把完整操作流程拆开讲。3.1 cc-switch 是什么为什么我推荐用它cc-switch 是一个开源的 API 供应商切换工具最早火起来是因为大家在 Claude Code 上切换 Anthropic 与各家兼容 API 的需求后来版本更新也加入了对 Codex 的支持。它会在本地启动一个代理服务Codex 把请求发给这个代理代理再按照你配置的目标供应商规则转发出去。选它有几个现实理由图形化界面管理多个供应商DeepSeek、OpenAI、本地模型、LLM Studio 这类 OpenAI 兼容端点可以一键切换。内置本地代理解决了 Codex 原生不支持非 Responses 服务的问题你不用每天去改 Codex 配置文件。供应商信息以 JSON 文件形式存储看得见、能备份、能迁移。同类工具里它算是社区维护最活跃的遇到问题能找到的参考案例也最多。3.2 添加 DeepSeek 供应商的具体配置从 GitHub 仓库下载对应系统的发行版或者如果你熟悉命令用包管理器安装也行。安装之后打开主界面找到供应商管理。点击新增供应商填写 DeepSeek 的核心参数配置项填写值说明供应商名称DeepSeek自定义方便自己在切换菜单里认出它Base URLhttps://api.deepseek.comDeepSeek 开放平台的标准接入地址API Keysk-xxxxxx在 DeepSeek 开放平台控制台创建不是聊天界面里的那个模型列表deepseek-chat, deepseek-reasoner两个模型根据场景选用后面细说如果你更习惯直接操作配置文件cc-switch 的供应商数据通常存在用户目录下的 JSON 文件里结构类似{ name: DeepSeek, baseUrl: https://api.deepseek.com, apiKey: sk-你的密钥, models: [deepseek-chat, deepseek-reasoner] }注意cc-switch 不同版本的字段名可能略有差异但核心就是 name、baseUrl、apiKey 这三样。API Key 绝对不要截图发到群里、不要提交到 Git 仓库一旦泄露去控制台吊销重建就行。3.3 启动本地代理并验证连通性供应商配置完成后在 cc-switch 里点击启动本地代理。这时候它会默认起一个本地端口通常是http://127.0.0.1:17891之类的地址。接着在 Codex 的配置里让请求走这个本地代理。Codex 配置文件位于~/.codex/config.toml你需要确保它使用了代理地址和对应的 Keymodel deepseek-chat model_provider cc-switch [model_providers.cc-switch] name cc-switch base_url http://127.0.0.1:17891/v1 env_key CODEX_API_KEY wire_api chat这里的几个关键点base_url指向本地代理注意补上/v1路径前缀这是 OpenAI 兼容接口的通用约定。env_key是 Codex 读取 API Key 的环境变量名你需要为 Codex 进程设置这个环境变量例如export CODEX_API_KEYsk-你的DeepSeek密钥。设置成什么名字其实可以自定义只要和env_key对应即可。wire_api chat是灵魂配置必须写成chat而不是responses否则请求还是走 Codex 原生协议代理就没法正确转换。配置完成后拿个简单指令测试codex say hello in one line如果 cc-switch 的代理面板能看到请求记录并且 Codex 正常返回结果说明整条链路已经通了。看到这里你已经完成了接入主流程接下来是所有人都会遇到的问题。4. 踩坑实录/responses 报错与模型名不支持的全排查链路这一节是全文的重头戏因为我敢说 90% 的人第一次接入时都会撞上类似的报错。社区里最典型的一个长这样cc-switch local proxy failed while handling codex endpoint /responses. provider[DeepSeek]很多人一看到/responses就懵了我明明配置的是 DeepSeek为什么还在请求 Codex 的 responses 路径下面我把完整排查链路和修复过程写出来。4.1 报错现场还原我先描述下触发场景。假设你配置完 cc-switch 和 Codex第一次运行codex fix the bug in login.py结果 Codex 界面很快返回类似上面的错误或者提示{detail: the gpt-5.6-sol model is not supported when using codex with a...}这里暴露了真正的两个问题Codx 把请求发到了/responses路径而这个路径是 Codex 原生协议的入口。cc-switch 的本地代理收到这个请求后尝试按照 DeepSeek 供应商规则转发但在转换或转发过程中失败。Codex 默认请求的模型名是 OpenAI 内部代号比如报错里那个gpt-5.6-sol。这个名字只存在于 OpenAI 服务体系里DeepSeek 那边根本不知道它是谁于是返回“模型不支持”。这两件事叠加起来就是“代理处理失败 模型不认”的双重翻车现场。4.2 三步排查法日志、直连、配置遇到这种报错我的习惯是不要瞎改按顺序做三个动作第一步看 cc-switch 的日志。cc-switch 界面通常会有一个日志窗口或者日志输出到用户目录下的 log 文件里。日志里能看到请求从 Codex 发来到代理转发失败的具体原因比如超时、401、404、模型不存在的 error body。这个信息比报错摘要详细得多80% 的问题在这一步就能定位。第二步用 curl 直接测 DeepSeek确认上游本身是好的。拿你配置里的 Key 跑一下curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的密钥 \ -d { model: deepseek-chat, messages: [{role: user, content: hi}] }如果你能正常拿到返回 JSON说明 Key、网络、接口地址都没问题。如果 curl 正常但 cc-switch 报错问题就在本地代理到 Codex 之间的协议转换环节。第三步检查 Codex 的config.toml和 cc-switch 的供应商配置是否对齐。重点核对三处模型名是否改成了deepseek-chat/deepseek-reasonerwire_api是否设为chatbase_url指向的是不是 cc-switch 的本地代理地址。顺着这个链路走一遍你会发现绝大部分问题都出在“模型名没改”或者“wire_api 忘了设”上面。4.3 我最终的修复动作以那个gpt-5.6-sol model is not supported的报错为例我的修复动作是在 Codex 配置里把model从默认值改为deepseek-chat。确认wire_api chat。重启 Codex 会话让配置重新加载。有时候改了配置还是报错是因为 Codex 会缓存老配置。你直接开一个新会话或者关闭终端重开比在同一个会话里反复试更有效。另外如果你在 cc-switch 里配置了多个模型建议在 Codex 配置里手动指定一个默认模型不要用“自动选择”。自动模式会向代理请求模型列表而 Codex 和 DeepSeek 的模型列表格式不完全兼容容易触发额外报错。明确指定模型能少很多幺蛾子。5. 不依赖代理的裸接方案直接改 config.toml 直连cc-switch 虽然好用但有些人就是不喜欢多装一个常驻服务或者想彻底搞清楚原理。那你可以选择第二条路不经过本地代理让 Codex 直连 DeepSeek。这条方案稍微硬核一点但网络拓扑最简洁。5.1 model_provider 配置示例打开~/.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然后设置环境变量export DEEPSEEK_API_KEYsk-你的DeepSeek密钥这个方案没有中间人Codex 发出的请求直接打到https://api.deepseek.com/v1。/v1路径是 OpenAI 兼容接口的标准入口DeepSeek 和 OpenAI 都遵循这一点。wire_api chat的意思是说Codex 内部把请求包装成 Chat Completions 格式而不是默认的 Responses 格式。5.2 wire_api 参数的坑这里有一个很容易被忽略的细节Codex 的wire_api支持两个值——responses和chat。如果你写responsesCodex 会按原生协议发请求此时 DeepSeek 无法处理写chatCodex 才会用 OpenAI 兼容的 Chat 格式。这个参数看上去只是填个单词但对不上的时候就会出现“我看不懂你在说什么”的错误。很多人明明把 Key、URL、模型名都填对了唯独这里没改结果死活连不上。我建议你在排查时把这个字段当作头号检查对象。另外一个相关参数是includes如果你需要的工具调用、系统提示等能力没生效可能是这个字段没配。普通代码任务通常不需要动它保持默认就好。5.3 两种接入方式怎么选我个人意见是分工明确如果你只在一个设备上用 Codex想干净少依赖裸接方案就够了如果你有多套供应商或者经常需要在 OpenAI、DeepSeek、本地模型之间切换用 cc-switch 更省心。从资源占用角度看裸接方案不额外启动任何服务最轻量cc-switch 只是多了一个常驻本地进程吃几十兆内存几乎可以忽略。从排错角度看cc-switch 的好处是它把协议转换集中到一处出了问题有日志可查坏处是你得排两层问题Codex 到代理、代理到 DeepSeek。裸接的排查路径反而更短出了问题直接看 Codex 的报错和 DeepSeek 的返回就行。还有一种折中的使用方式平时用裸接直连 DeepSeek等哪天需要切回 OpenAI 官方模型时再临时改 config.toml。不过这样反复改配置容易出错我后来还是切回了 cc-switch 做统一管理。6. 横向扩展Claude Code、VS Code、Dify 与本地模型的同类思路Codex 接入 DeepSeek 走通以后你会发现这套“OpenAI 兼容 API 工具适配”的思路可以复制到很多场景里。这也是为什么 DeepSeek 火了以后大家不停地在各种工具里接它本质都是同一件事。6.1 同理可得Claude Code 接入 DeepSeek如果你同时用 Claude Code接入逻辑几乎一样只是环境变量不同。Claude Code 支持通过ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN把请求转发到任何 Anthropic 兼容端点但 DeepSeek 对自己的定位是 OpenAI 兼容而不是 Anthropic 兼容。所以社区里常见的做法是再套一层转换层把 Anthropic 格式的请求转成 OpenAI 格式然后发给 DeepSeek。cc-switch 同样支持管理 Claude Code 的供应商配置你可以在里面单独配置一套 DeepSeek然后用它的代理服务完成协议转换。这个场景适合那些想把 Claude Code 也用 DeepSeek 跑起来省钱的朋友但你得清楚这里比 Codex 接 DeepSeek 多了一层转换出现问题的概率更高生产环境使用前务必多测几轮。6.2 VS Code 与 Dify 中的同款思路VS Code 接 DeepSeek 在社区里更常见因为很多 AI 编程插件如 Continue、Cline、Roo Code本身就支持自定义 OpenAI 兼容供应商你只需要把模型改名为deepseek-chat、Base URL 改成https://api.deepseek.com/v1、填入 Key 即可没有协议转换问题因为这些插件本身走的就是 Chat Completions 格式。而 Dify 这类 LLMOps 平台接入 DeepSeek 就更简单了在模型供应商里选择 OpenAI-API-compatible然后填 DeepSeek 的地址和 Key就能在应用编排里使用 DeepSeek 模型。它的配置路径和 Codex 裸接方案高度相似都是“OpenAI 兼容端点 自定义模型名”。这给了我一个思考框架在所有支持 OpenAI 兼容供应商的工具里DeepSeek 基本就是“改了 Base URL 和模型名就能用”的万能接法只有在 Codex 这种默认使用 Responses 协议的工具里才需要额外关心协议转换的问题。6.3 本地部署模型的联想顺着这个框架再往外走一步就轮到本地模型了。如果你用 vLLM 本地部署了一个 DeepSeek 开源权重模型它同样会暴露一个 OpenAI 兼容的 HTTP 接口地址长这样http://127.0.0.1:8000/v1。这时候你在 cc-switch 里新增一个供应商Base URL 填这个本地地址模型名填你实际加载的模型名cc-switch 就能像接入 DeepSeek 云端 API 一样接入本地模型。同理LLM Studio 这类本地模型管理工具也可以作为 cc-switch 的供应商很多人在没有外网 API 额度的情况下就是用这套组合让 Codex 在纯本地环境里跑起来的。这个思路特别适合隐私敏感或者离线场景等于说你在本地起了一个 OpenAI 兼容服务Codex 以为自己连的是 OpenAI其实背后是你的显卡和 vLLM。最后的经验分享经过一段时间实际使用我对 Codex 接 DeepSeek 的稳定性整体是满意的。日常编码任务用deepseek-chat足够速度提上来之后体感跟用官方模型差距很小需要复杂推理、代码重构这类重活时可以切到deepseek-reasoner只把思考和输出的费用贵一档但通常能省掉来回返工的时间。接完 DeepSeek 之后最大的收获不是“少花了多少钱”而是让我意识到工具的真正价值从来不取决于它原生绑定谁而在于你能否把它接到最合适的能力源上。如果你也在配的过程中遇到了别的报错按“日志—直连—配置”的三角排查法去走大多数问题都能自己揪出来。