最近我终于把一套很多人在问的组合彻底跑通了——在终端里用 OpenAI 的 Codex CLI 干活，底层驱动模型换成 DeepSeek。说白了，就是通过标准兼容协议，让 Codex 这个官方出品的编程智能体去调用 DeepSeek 的 API 端点，让它替我们写代码、执行命令、翻文件，而推理的活儿全部交给 DeepSeek。这套方案的好处非常直接：成本比直接用 GPT-4o 低一个量级，数据链路完全可控，还能无缝切换到本地部署的 DeepSeek 蒸馏模型。适合想把 Codex 装上国产大脑的开发者，适合对 API 费用敏感的团队，也适合想在受限或离线环境里跑编程助手的朋友。下面从原理、选型到完整配置一步步讲清楚，所有的坑我都替你踩过一遍了。
1. 先搞懂原理再动手：为什么 Codex 能换 DeepSeek 来驱动
1.1 Codex CLI 到底是个什么工具
Codex CLI 是 OpenAI 开源的终端版编程代理，本质上是一个跑在你本地命令行里的智能体。你给它一句自然语言指令，它会自己读代码仓库、拆解任务、调用模型推理、生成修改方案，然后在你批准后直接改文件、执行测试命令。它和 ChatGPT 网页版最大的区别是：它真正操作的是你本地工程里的文件，而不是一个孤立对话框。
Codex 有三个安全级别：只读模式（read-only）、允许写工作区（workspace-write）和完全放行（danger-full-access）。日常重构建议用 workspace-write，让它动代码但不碰系统目录；只在跑自动化脚本这种情境下才考虑完全放行。它还会把每次会话存下来，下次用codex resume就能接着聊，这个设计对长任务特别友好。
1.2 关键点：OpenAI 兼容协议才是打通一切的那把钥匙
很多人第一次听到“把 Codex 接到 DeepSeek”会觉得是玄学，毕竟一个是 OpenAI 的工具，一个是深度求索的模型，凭什么能互换？答案在于 OpenAI 把自己的 API 做成了事实标准：任何大模型服务，只要按照base_url + api_key + model这套协议提供服务，就能被任何兼容 OpenAI 的客户端调用。
DeepSeek 官方 API 恰好就兼容这个协议。它提供了 OpenAI SDK 兼容的端点，模型名有两个：deepseek-chat指向 V3 系列对话模型，deepseek-reasoner指向 R1 系列推理模型。所以对 Codex 来说，换模型不需要改工具本身，只需要改配置里的三个值：模型提供商的名字、请求地址、API Key。本质和手机换运营商一样，号不用变，换张卡而已。
这里有个特别容易翻车的细节：Codex 新版默认使用 Responses API（也就是/responses端点）来通信，但 DeepSeek 官网提供的是 Chat Completions 模式（/chat/completions端点）。如果你在配置里不显式声明“用老的 chat 协议”，Codex 会傻乎乎地往 DeepSeek 端点上发/responses请求，然后收到一个 404。这可以说是八成接入失败的共同根源。
1.3 两条接入路径：官方 API 和本地模型怎么选
接入 DeepSeek 并不是只有一条路，严格说有两大方向：
第一条是云端官方 API。去 DeepSeek 开放平台注册账号，充值拿 Key，直接配进 Codex。这条路最省事，模型能力最强，不用自己买显卡，适合日常正经干活的人。缺点是按 token 付费，但价格比 GPT-4o 便宜一个数量级，具体以官方价格页为准。
第二条是本地部署。用 Ollama、LM Studio 或者 vLLM 在你自己电脑或内网服务器上跑一个 DeepSeek 蒸馏模型（常见的有 7B、14B、32B 这几个档位），然后把 Codex 指向http://127.0.0.1:端口/v1。这条路几乎没有推理费用，数据不出内网，适合隐私敏感场景。代价是：小参数的蒸馏模型写代码的能力比官方 V3 弱不少，复杂的架构设计和长链路重构容易翻车。
我自己实际用下来，最稳妥的组合是：大任务走官方 API，小改动、变量重命名这种机械活走本地小模型。两条路在 Codex 的配置上只有 base_url 和 model 不一样，其他完全一致，所以学会了都能配。
2. 动手前的环境准备与工具选型
2.1 安装 Codex CLI：npm 和 Windows 桌面版两种姿势
Codex 的安装方式主要看操作系统。macOS 和 Linux 用户最简单，一条 npm 命令搞定：
npm install -g @openai/codex装完以后验证一下：
codex --version如果你看到版本号，就说明装好了。Windows 用户有两个选择：一个是原生 Windows 新版本已经可以直接跑，另一个更稳的是用 Windows 桌面版。桌面版其实就是一个带图形界面的壳子，里面还是同一个 CLI，只不过帮你把 Node.js 环境和依赖都打包好了，双击就能用，适合不想折腾命令行的朋友。
安装过程中有个容易劝退新手的环节：第一次运行codex，它会提示你登录 OpenAI 账号。这里不要慌——如果你要接的是 DeepSeek 或者本地模型，是可以跳过登录直接用自定义 provider 的。配置好模型提供商以后，Codex 会把认证信息读环境变量，不依赖 ChatGPT 的登录态。我第一次配的时候在这个地方卡了二十分钟，一直在想是不是必须登录，后来才发现完全是多虑。
2.2 准备 DeepSeek 官方 API Key 或者本地模型
官方 API 这条路很直接。去 DeepSeek 开放平台注册账号，创建一个 API Key，格式大致是sk-开头的一串字符。把 Key 存好，接下来要填进环境变量里。
这里有一个我强烈建议照做的习惯：不要用OPENAI_API_KEY这个变量名来装 DeepSeek 的 Key。因为 Codex 官方文档里默认读取的就是这个名字，如果你真这么干了，万一以后装了别的 OpenAI 兼容工具，会有意无意把两个 Key 搞混。更合理的做法是用自定义变量名，比如DEEPSEEK_API_KEY，然后在 config.toml 里通过env_key明确告诉 Codex 读哪个变量。这样两套 Key 井水不犯河水。
本地部署这条路的准备工作要看显卡和内存。最省心的方式是 Ollama：
ollama run deepseek-r1:7b这个命令会自动拉模型并启动一个本地服务，默认地址是http://127.0.0.1:11434，它还自带一个 OpenAI 兼容端点变成http://127.0.0.1:11434/v1，这就足够让 Codex 接入了。如果你有 NVIDIA 显卡且想追求性能，可以用 vLLM：
python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \ --port 8000vLLM 的并发能力和吞吐量比 Ollama 强得多，但部署门槛也高不少，要装 CUDA、要下个大模型文件。没有经验的朋友先用 Ollama 或者 LM Studio 起步就好，跑通了再追求性能不迟。
2.3 CC Switch、LM Studio 这类网关工具到底起了什么作用
接本地模型之前得先明白一个概念：像 CC Switch 和 LM Studio 这种工具，本质上是一个“API 网关”。它们的核心功能是把多个模型服务的地址统一成一个本地端口，然后在图形界面上切换。
举个例子。CC Switch 会在你电脑上开一个本地 HTTP 服务，比如http://127.0.0.1:3005，你把 DeepSeek 官方 Key 填进去，它就把到:3005的请求转发给 DeepSeek；你把配置切到本地 LM Studio，它就把请求转发到127.0.0.1:1234。对 Codex 来说，它根本不需要知道模型跑在哪，它只知道有一个请求地址，发过去就有相应回来，这就是“网关”的意义——屏蔽了后端的位置变化。
社区里还能看到一些特定的适配项目，比如有人维护的 deepseek-harness 之类的封装层，但我个人的建议永远是：先走标准 OpenAI 协议，中间层越少越容易排查。网关工具是为了切换方便，而不是为了解决“接不通”的问题。如果标准协议本身没配对，加再多网关都是叠 buff 掩盖 bug。
3. 接入配置完整实操：三个方案按需选
3.1 方案 A：DeepSeek 官方 API 直连（最短路径）
这是我最推荐大多数人先跑通的方案，因为故障点最少。首先找到 Codex 的配置文件，macOS 和 Linux 在~/.codex/config.toml，Windows 在%USERPROFILE%\.codex\config.toml。如果文件不存在就新建一个，然后用文本编辑器写入：
model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek API" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"这里每个字段都值得解释一下，因为很多人就是栽在字段含义上：
model是整个会话默认使用的模型名，官方 API 的话填deepseek-chat即可。想用推理模型就填deepseek-reasoner，但这家伙思考时间长、token 消耗大，日常改代码用不上，更适合架构方案分析。
base_url是请求端点，注意要把/v1写全。DeepSeek 官方文档里旧版是https://api.deepseek.com，新版兼容 OpenAI SDK 的写法是https://api.deepseek.com/v1。在 Codex 里填带/v1的更稳，因为 Codex 的拼接逻辑会在 base_url 后直接加路径，不带/v1的话/chat/completions会被拼成https://api.deepseek.com/chat/completions，这个地址不标准，可能触发网关边缘大小写、路由之类的问题。
env_key是让 Codex 从哪个环境变量读取 API Key。我测试时特意绕开了默认的OPENAI_API_KEY，用了个独立变量名。在 shell 里设置：
export DEEPSEEK_API_KEY="sk-你的key"wire_api = "chat"是整份配置最关键的一行。它强制 Codex 使用 Chat Completions 协议而不是默认的 Responses 协议，DeepSeek 官方只实现前者，不写这行必报 404。我把这个看作“协议适配开关”，每次有人说接不通，我第一反应就是问他有没有写这一行。
配置好后先别急着启动 Codex，用一行 curl 验证 Key 和端点是否正常：
curl https://api.deepseek.com/v1/chat/completions \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'如果返回一段带content字段的 JSON，说明链路通畅。这时候再运行：
codex "用 Python 写一个读取 CSV 并算平均值的脚本"第一次会拉起一个会话，让你确认权限，按提示操作即可。看到 Codex 开始输出思考过程和生成代码，就算正式跑通了。
3.2 方案 B：本地部署 DeepSeek 蒸馏模型（离线也能用）
本地方案里最推荐新手用的是 LM Studio。它是个带图形界面的工具，能下载模型文件、直接内置一个 OpenAI 兼容服务。启动后在设置里打开本地服务，默认端口是1234，然后写 Codex 配置：
model = "deepseek-r1-distill-qwen-7b" model_provider = "local" [model_providers.local] name = "LM Studio" base_url = "http://127.0.0.1:1234/v1" env_key = "LOCAL_API_KEY" wire_api = "chat"注意本地服务一般不需要真实 Key，但 Codex 要求env_key必须指向一个存在的变量，所以设一个空的或者随便填的占位都可以：
export LOCAL_API_KEY="not-needed"用 Ollama 的话，地址改为http://127.0.0.1:11434/v1，模型名改成你ollama list里看到的名字，比如deepseek-r1:7b。思路完全一致，只是端口和名称变了。
本地模型跑起来以后最大的感受是：响应速度和硬件强相关。我在一台 32G 内存的 M 系列芯片机器上跑 7B 量化模型，小改动的任务基本流畅；但如果让 7B 模型去做跨文件重构，它就明显力不从心，代码逻辑会飘。所以对本地方案要有一个正确认知：这是“可用”和“易用”的平衡，而不是“最强能力”的选择。真要拿本地模型当主力干活，建议直接上 32B 档位，并保证内存至少 32G 以上。
3.3 方案 C：通过 CC Switch 网关统一管理多个模型
如果你手头不止一个模型服务，想在一个 Codex 配置下随便切换，CC Switch 这类网关工具就有用武之地了。
操作思路是三步：
先在 CC Switch 里添加 Provider。如果你用的是 DeepSeek 官方 API，就新建一个 OpenAI 兼容 Provider，名字随意，base URL 填https://api.deepseek.com/v1，Key 填你申请的 Key。如果你用的是本地模型，就填本地地址，比如http://127.0.0.1:1234/v1。
然后在 CC Switch 里启动本地代理服务，它会给你一个统一的地址，通常形如http://127.0.0.1:3005/v1。把这个地址记下来。
最后在 Codex 配置里把 base_url 指到这个统一地址：
model = "deepseek-chat" model_provider = "switch" [model_providers.switch] name = "CC Switch" base_url = "http://127.0.0.1:3005/v1" env_key = "LOCAL_API_KEY" wire_api = "chat"以后切换模型时，你不需要再改 Codex 的配置，只需要在 CC Switch 的图形界面上切换 Provider，Codex 下次请求就会自动走新的后端。
这个方法最大的好处是解耦：Codex 的配置永远不用动，模型层面的变化全部收敛到网关层。
3.4 参数调优：让 Codex + DeepSeek 的组合更好用
基础配置跑通以后，还可以做一些微调让体验好很多。
第一个是控制上下文。Codex 会自动把当前目录相关的文件塞进上下文，项目一大了很容易吃掉整个上下文窗口。在配置里可以限制：
[context] max_conversation_tokens = 50000把它设成一个比模型上限小的值，可以防止会话越聊越笨。DeepSeek 的上下文上限高，但超过一半的时候模型注意力已经分散，代码准确率会下降，所以留出余量不是保守，而是明智。
第二个是写项目规范。在项目根目录建一个AGENTS.md文件，用自然语言写清楚这个项目的技术栈、代码风格、注意事项。Codex 每次启动会自动读这个文件，相当于给模型一个“项目说明书”。我在自己的项目里写了三条：不许动测试文件的公共函数签名；改代码前先看对应单测；注释用中文但提交信息用英文。实测下来 Codex 的遵守程度比没有规范时高出一大截。
第三个是灵活切换推理模式和对话模式。做架构讨论时用deepseek-reasoner，让它慢一点深一点；写 CRUD 代码时用deepseek-chat，速度快、成本低。甚至可以配置两套 provider，一个叫reasoner一个叫fast，用codex --model reasoner临时指定，不需要改全局配置。
3.5 日常用法实测：Codex 到底该怎么用
跑通配置以后，Codex 的日常使用流程大概是这样的：
遇到小任务，直接一句指令：
codex "给 user 表加一个 last_login_at 字段，更新对应迁移文件和 model"Codex 会开始查看项目结构，定位迁移文件、model 文件，然后给出改动方案，询问你是否执行。你按 Tab 键批准，它就写文件、跑测试，一气呵成。
遇到长任务，想让它在后台持续干活，可以加权限参数：
codex --sandbox workspace-write "把所有的 console.log 替换成 logger.info，并且更新相关测试断言"这个模式允许它写工作区文件，但不会碰系统目录，安全性有保障。
会话断了或者想接着上次的思路继续，用：
codex resume它会列出历史会话列表，选一个就能接着聊。上下文延续性对复杂任务非常重要，不用每次把需求重新说一遍。
我在测试里最明显的一个感受是：DeepSeek 对中文指令的理解非常自然，写代码时的注释风格偏向简洁，不像某些模型喜欢堆英文废话。这可能和它训练数据的分布有关，总之中文开发者体验很好。
4. 常见问题与排查实录
4.1 报错：CC Switch local proxy failed while handling codex endpoint /responses
这个报错是接入 DeepSeek 时出现频率最高的一个，错误特征非常明显：Codex 提示本地代理在处理/responses端点时失败。
先解释一下这个报错为什么会出现。前文说过，Codex 新版默认使用 Responses API 协议，发送请求到/responses路径。但 CC Switch 或者 DeepSeek 官方端点只实现了 Chat Completions 协议，能处理的是/chat/completions路径。两边的“方言”不统一，请求就被拒了。
解决方法按这个顺序来：
第一步，检查 config.toml 里是否写了wire_api = "chat"。没写就先补上，这是最可能的坑。
第二步，重启 Codex。注意不是简单Ctrl+C再运行一次就完了，如果有代理进程也要一并重启。你可以在终端里直接查看代理日志，确认新的请求路径已经变成/chat/completions了。
第三步，检查 CC Switch 版本。旧版本对 OpenAI 兼容协议的支持不完整，升级到最新版能解决大部分“协议不识别”类问题。
大多数情况走到第一步就好了，私信我的几个朋友全都是在wire_api上栽的跟头。
4.2 Codex 无法加载组织设置或提示配置项不识别
有朋友跑起来以后发现 Codex 报unrecognized configuration setting之类的警告，说忽略了一个无法识别的配置项。这个多半是抄网上旧教程导致的，因为 Codex 版本迭代很快，一些旧配置项被改名或废弃。
比如早期版本有context_window和max_tokens这种直接写法，新版本统一收归到[context]和[model_providers]下面了。遇到不识别配置项，最稳妥的办法是把 config.toml 精简到一个最小可用状态：只保留model、model_provider、[model_providers.xxx]这几项，一层层加回去。这比每次看警告猜要快得多。
至于“无法加载组织设置”，这个通常是因为你本地残留了 ChatGPT 登录态的老档案，但用的又是第三方 provider。直接删掉~/.codex/auth.json，让 Codex 重新初始化即可。放心，这不影响你的 DeepSeek Key，它只负责清掉跟官方账号相关的会话状态。
4.3 响应速度慢、token 消耗异常大
接入 DeepSeek 以后感觉响应慢，要从两个方向排查。
第一个原因是模型本身慢。deepseek-reasoner是推理模型，思考时间明显比对话模型长，这是它的工作方式决定的。如果你只是改个变量名，没必要用推理模型。换成deepseek-chat会快一大截。
第二个原因是 Codex 往上下文里塞了太多文件。它默认会根据你的指令猜测相关文件，但猜测逻辑比较激进，一个小改动可能把几个大文件全读一遍。解决办法是在 AGENTS.md 里写明“不要主动读取指定以外的文件”，或者用--exclude参数排除不必要的目录。
token 消耗异常大还有一个隐蔽原因：Codex 的自动命令执行开着，模型在反复检查 lint、test 输出，每次检查都是一轮完整请求。如果你在本地小模型上测试，这种循环会让响应时间成倍增加。可以把[command]里的自动化命令关掉，改成人工确认制，效率反而更高。
4.4 避坑清单：按现象速查
| 现象 | 真正原因 | 解决办法 |
|---|---|---|
请求返回 404，路径是/responses | 协议没切换 | config.toml 里加wire_api = "chat" |
| 401 Unauthorized | API Key 没传对 | 确认env_key对应的环境变量已设置，curl 先验证 |
| 响应慢 | 用了推理模型或上下文过大 | 换deepseek-chat，限制上下文 token 数 |
| 本地模型完全无响应 | 端口地址不对 | 确认 LM Studio 服务是否启动、监听端口是否一致 |
| 配置项警告 | 旧配置残留 | 精简 config.toml 到最小可用再逐项加 |
| 无法加载组织设置 | 官方登录态残留 | 删除~/.codex/auth.json重新初始化 |
这个表基本覆盖了我被问到的八成问题。你如果遇到表里没有的情况，我的建议只有一个核心思路：从 Codex 的视角走一遍请求路径——它读了哪个配置、请求发到哪个地址、后端返回了什么错误。把这三件事搞清楚，没有接不通的兼容端点。
在我实际使用的这一周里，最让我满意的场景是让 Codex 用deepseek-chat快速生成一批重复性 API 接口代码，再切换成本地模型做变量重命名和格式修正，最后用deepseek-reasoner审一遍关键模块的架构设计。不同档位的模型各司其职，成本被压得非常低。一个小技巧是给这套组合单独配一个自定义提示词文件，用中文写好项目规范和代码风格要求，实测下来 Codex 生成代码的贴合度会明显好于默认状态。这套玩法后续还能继续扩展，比如在 Codex 里通过 MCP 接上飞书多维表格做需求同步，或者接蓝湖把设计图标注直接拉进对话里，本质上只是多配几个 server 的问题。先把 DeepSeek 这条链路跑稳，其他的都好说。
