开头先交代背景：很多人想用 Codex，但登录、订阅、客户端起步都不顺畅，而 DeepSeek 这类国产模型 API 又便宜得不像话，于是有人想到一条折中路线：用开源 Codex CLI 做前端，把底层模型切换到 DeepSeek 的 API，成本瞬间从订阅制变成按量付费。这个思路本身没问题，但完整跑通的人其实不多，因为坑不在“改一行配置”，而在环境、认证、路径、代理、模型参数、客户端兼容这一连串细节。
我花了 18 分钟把这条链路完整走了一遍，从零开始，到最终在 Codex CLI 里用 DeepSeek 模型跑通对话和代码任务。这篇文章不写 PPT 式步骤，而是把真正决定成败的节点、容易误判的地方、还有长期使用要考虑的事情一次讲清楚。
1. 先搞清楚这 18 分钟到底在解决什么问题
1.1 为什么有人想用 Codex 但始终进不了门
OpenAI 的 Codex 产品形态一直在变。网页版、桌面客户端、CLI 工具、IDE 插件，不同入口的要求不太一样。有的需要登录 OpenAI 账号，有的希望有订阅额度，有的对网络环境有要求。对国内开发者来说，这一串前置条件本身就劝退了不少人：账号注册是一道坎，订阅支付又是另一道坎，最后进到界面里发现模型成本还得再看。
于是社区里出现了一个非常自然的思路：Codex 只是一个前端交互层，真正干活的是背后的模型。如果 Codex CLI 允许自定义模型提供商，那是不是可以把模型换成 DeepSeek 的 API？这样前端交互体验还是 Codex 那一套，后端成本则变成 DeepSeek 按 token 计费，非常便宜。这个思路其实已经被不少开发者验证过了，只是信息分散在各种 issue、论坛帖子和个人博客里，新手拼不出完整链路。
1.2 这条链路的本质不是“白嫖”，而是“换模型”
先纠正一个说法。标题里的“白嫖”更多是夸张表达，实际意思是：不买 OpenAI 的订阅、不按 OpenAI 的模型价格计费，而是通过 API 切换到 DeepSeek 模型。DeepSeek 的 API 价格相对低，而且支持 OpenAI 兼容格式，这让“Codex 前端 + DeepSeek 后端”的组合在成本和工作流上变得可行。
所以这里真正解决的不是“零成本使用 AI 编程助手”，而是“低成本获得一套接近 Codex 的交互体验”。它的价值在于：
- 交互层是 Codex，有对话、有文件读写、有任务执行，体验统一。
- 模型层是 DeepSeek，按量付费，成本更低。
- 不依赖 OpenAI 订阅，前置条件更少。
这个组合的适用人群非常明确：想体验 Codex 交互流程、但不想为订阅和高价 API 买单的开发者，以及已经在用 DeepSeek API、希望统一到 Codex 界面的团队。
1.3 单次跑通和长期使用，是两个完全不同的问题
这篇文章的标题是“18 分钟跑通”，但我想把话说透：18 分钟只能做到“单次跑通”，也就是把环境装好、配置改好、跑通一次对话。真正长期用它写代码、做批量任务、接入团队工作流，还需要面对另一批问题：模型能力差异、日志排查、客户端版本兼容、API 限流、上下文长度限制、工具调用稳定性等等。
所以下文会按这个顺序展开：
- 环境准备和安装。
- 配置 DeepSeek API 的关键点。
- Codex CLI 和客户端的路径问题。
- 代理接口错误和模型参数问题。
- 常见报错排查与长期使用建议。
2. 环境准备：不要一上来就纠结配置语法
2.1 先确认本机已经有哪些东西
跑 Codex CLI，第一步不是去配置模型，而是确认 Node.js 环境、Codex CLI 安装情况和网络出口。看到一个很常见的报错：
unable to locate the codex cli binary. set codex cli path or ensure the electron app has the proper environment如果你的桌面客户端是 Electron 包装的，这个报错意味着客户端启动时找不到 codex 这个二进制。原因通常是：
- Codex CLI 没有安装，或者安装路径不在系统 PATH 里。
- 桌面客户端配置的 codex_cli_path 为空或指向了不存在的路径。
- 终端里能跑 codex，但客户端进程拿不到同样的环境变量。
这类问题最容易误导新手，因为终端里明明能跑，为什么客户端找不到？本质是环境变量作用域不同。Electron 应用往往不会自动继承 shell 里 export 的变量，特别是 mac 上通过 GUI 启动的应用。解决办法是在配置文件里显式指定 codex_cli_path，或者确保 codex 被安装到系统级路径里。
2.2 我的实际安装顺序
这里给你一条可以直接照抄的顺序。先说环境：Windows 或 macOS 都适用，Linux 也基本一样，但路径写法需要微调。
# 1. 安装 Node.js，建议 18 以上 node -v # 2. 安装 Codex CLI npm install -g @openai/codex # 3. 确认 codex 命令可用 codex --version如果codex命令找不到，先看 npm 全局 bin 目录有没有在 PATH 里。Windows 上一般是%APPDATA%\npm，macOS 上一般是/usr/local/bin或~/.npm-global/bin。
Codex CLI 安装完成之后，再启动桌面客户端。如果客户端还是报找不到二进制，就在客户端的配置文件（一般是设置页或~/.codex/config.toml附近）里设置：
codex_cli_path = "/usr/local/bin/codex"Windows 上写完整路径，注意是 Python 风格的路径写法，不是C:\...，而是C:/Users/你的用户名/AppData/Roaming/npm/codex.exe。
注意：不同版本客户端的配置字段可能有区别，有的是
codex_cli_path，有的是codexCliPath。找不到对应字段时，优先看客户端文档或配置文件注释。
3. 接入 DeepSeek：核心不是改地址，而是理解“兼容层”
3.1 Codex 为什么能接 DeepSeek
Codex CLI 本身设计成了可配置模型提供商，支持 OpenAI 兼容接口。DeepSeek API 提供 OpenAI 兼容端点，所以理论上只要把 base URL 换成 DeepSeek，把模型名改成 DeepSeek 的模型，就能跑。这也是为什么社区里有人叫它 DeepSeek Harness。
但兼容不意味着免费能跑。日常最常遇到的几个问题是：
- base URL 写错。
- API key 没配。
- 模型名不支持。
- 返回格式和 Codex 期待的不一致。
- 客户端在中间加了代理，代理又改写了请求。
3.2 最小配置示例
Codex CLI 支持用环境变量或配置文件指定模型提供商。常见方式是设置OPENAI_BASE_URL和OPENAI_API_KEY，然后再用--model参数指定模型。一个常见配置结构如下：
export OPENAI_BASE_URL="https://api.deepseek.com/v1" export OPENAI_API_KEY="sk-你的key" codex --model deepseek-chat如果你喜欢用配置文件，可以在~/.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"注意：这里 base URL 的写法会直接影响请求路径，因为 Codex 内部会请求/responses或/chat/completions，不同版本的 Codex 对端点要求不一样。如果 DeepSeek 提供一个 OpenAI 兼容的/v1端点，那 base URL 写到/v1一般都能工作。具体以 DeepSeek 官方文档为准。
3.3 模型名选不对，报错会非常快
Codex 默认带一批模型名，比如gpt-5.6-sol之类。当 Codex 向 DeepSeek API 发送请求时，如果仍然带着默认模型名，DeepSeek 服务器会直接拒绝。
我看到一个真实报错：
{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a ..."}很有迷惑性。表面看是 Codex 不支持，其实是模型名没换成 DeepSeek 所支持的模型。DeepSeek 的常见模型名是deepseek-chat和deepseek-reasoner。不同时间点模型名会更新，比如搜索材料里出现的deepseek-v4-flash，这类命名变化要以 DeepSeek API 文档列出的模型列表为准。落地时先发起一次最小的对话测试来确认模型名有效。
4. 最容易卡住的三个坑：CLI 路径、代理接口、thinking mode
4.1 坑一：Electron 客户端里的 CLI 路径
这个在前面已经提到。实际跑的时候会有两类表现：
- 直接报
unable to locate the codex cli binary。 - 客户端能打开，但点不了操作，后台日志也在报找不到二进制。
排查顺序建议：
- 在终端确认
codex --version能输出版本号。 - 执行
which codex或where codex，拿到绝对路径。 - 在客户端设置中把
codex_cli_path设为该绝对路径。 - 重启客户端，再看日志。
不要跳过第一步直接配置路径，因为很可能你的 codex 根本没装成功。判断标准是终端命令本身有没有返回。
4.2 坑二：本地代理服务和端点转发
搜索材料里出现了一个很典型的报错：
cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the `reasoning_content` in the thinking mode must be passed back to the api.这个名字里出现了 “local proxy”，说明本机或某个客户端启动了一个本地代理端口，Codex 请求会先经过它，再转发到 DeepSeek API。问题出在 “thinking mode”：DeepSeek 某些推理模型在流式返回时会在reasoning_content字段里输出思考过程，如果后续请求没有把这段内容回传给 API，服务端就会返回 400。
这个问题的典型场景是：
- 你用一个带图形界面的 Harness 或桌面客户端。
- 客户端内部维护了一个本地代理，统一把 Codex 请求转成 DeepSeek 兼容请求。
- 代理在转换请求时，没有把多轮对话中的
reasoning_content正确传递回去。 - DeepSeek 收到缺少思考内容的请求，直接拒绝。
解决办法分别从几个方向试：
- 升级客户端或代理组件，看是否已经修复。
- 关掉“思考模式”或切换到非推理模型，比如
deepseek-chat，这类模型不需要回传 reasoning_content。 - 检查代理组件配置里是否有专门针对 DeepSeek 模型名称的映射项，把模型名和模式同时指定。
- 如果不是必须用桌面客户端，建议直接用 Codex CLI 测试，CLI 对这种字段的兼容性通常更新得更快。
4.3 坑三：模型和端点组合不匹配
Codex 对端点的调用路径是动态的。旧版本可能走/v1/chat/completions，新版本或某些模式可能走/v1/responses。DeepSeek API 是否支持/responses端点，取决于它的实现版本。如果 API 不支持，就会出现类似 “failed while handling codex endpoint /responses” 的报错。
遇到这种情况，最简单的验证方式是：
- 直接写一段 curl 请求，手动请求 DeepSeek 的
/v1/chat/completions，确认 key 和模型可用。 - 再试
/v1/responses或 Codex 当前使用的端点，看 API 是否支持。 - 如果不支持，要么更换 Codex 版本，要么使用官方的 OpenAI 兼容模式，并显式指定使用
/v1/chat/completions的 base URL。
curl 验证的常见结构如下：
curl https://api.deepseek.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的key" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "hello"}] }'如果这个请求能正常返回内容，说明网络、key、模型名都是通的。接下来再去排查 Codex 配置环节。
5. 把这套东西工程化：从单次对话到稳定使用
5.1 先建立三张检查表
跑通一次之后，不要着急写博客发朋友圈，先检查三件事：
第一张表：环境检查表
- Node.js 版本是否满足 Codex CLI 要求。
- codex 是否出现在 PATH 中。
- 桌面客户端是否已经正确读取 codex_cli_path。
- 网络出口是否稳定。
- 是否设置了代理，代理是否会改写 Host 或 Authorization 头。
第二张表：API 检查表
- DeepSeek API key 是否有效。
- base URL 写法是否包含正确的版本前缀。
- 模型名是否在 DeepSeek 当前 API 文档中。
- 如果是推理模型，是否处理了 reasoning_content。
- 是否开通了对应模型的权限或额度。
第三张表：客户端检查表
- 客户端版本是否和 Codex CLI 版本匹配。
- 本地代理端口是否被占用。
- 是否有多个代理进程同时运行。
- 配置文件和环境变量是否冲突。
- 日志路径是否可写。
这套检查表看着简单，但实际排查时非常有用。很多时候报错不是单一原因，而是多个条件同时不满足。
5.2 单对话模式跑通后，再考虑批量任务
Codex CLI 本身支持把任务拆成多轮对话、文件修改和命令执行。第一次使用建议这样渐进：
- 先让它回答一个纯文本问题，确认模型返回正常。
- 再给一个小任务，比如“读取当前目录下 README.md，总结里面的 API 列表”。
- 再给它一个修改类任务，明确告诉它只能改哪些文件。
- 最后再进入自治模式，让它自己决定执行哪些命令。
不要一上来就让它在真实项目里随意修改文件。模型会犯错，API 会限流，工具调用也会失败。先小规模验证，再扩大范围，这是所有 AI 编程工具的正确使用姿势。
5.3 如果团队要统一使用，需要补的工程能力
如果一个小组想统一走“Codex + DeepSeek”这套方案，单机配置就不够了。至少还需要考虑：
- 统一的 API key 管理，不要每个人把 key 写死在 shell 历史里。
- 模型的成本统计，按项目或按人拆分。
- 日志集中收集，方便出了问题看是模型问题、代理问题还是 Codex 版本问题。
- 配置模板，通过仓库统一分发
config.toml。 - 定期更新 Codex CLI 和客户端，避免因版本落后产生兼容问题。
这些问题普通个人开发者不用全做，但团队场景必须尽早规划，否则后面每一次升级都可能出现“我这能跑，他那不能跑”的局面。
6. 常见报错速查与最终建议
6.1 症状到原因的对应思路
| 症状 | 常见原因 | 优先排查方向 |
|---|---|---|
| 客户端报 unable to locate the codex cli binary | codex 未安装或路径未配置 | which codex，检查 codex_cli_path |
| 调用时 model 不支持 | 模型名不是 DeepSeek 支持的名称 | 查 DeepSeek API 文档，换 deepseek-chat |
| upstream_status 400, thinking mode 相关 | 代理未正确回传 reasoning_content | 升级代理或换非推理模型 |
| endpoint /responses 失败 | DeepSeek API 不支持该端点 | curl 手动验证端点，或换 Codex 版本 |
| 没有输出但请求成功 | 上下文过长或工具调用卡住 | 看日志，检查 timeout，缩短对话历史 |
| 速度慢 | 网络代理、模型推理本身耗时 | 对比直连和代理，选择合适模型 |
这个表格不是让你对着抄，而是给一个排查时的判断框架：先判断问题在哪一层，再动手改。不要一看到 400 就怀疑 API key，也不要一看到 timeout 就换代理。先看日志，再看请求，最后再动配置。
6.2 使用成本的真实评估
DeepSeek 的 API 按 token 计费，价格通常比 OpenAI 便宜很多。但“便宜”只适合做总量判断，不能忽略模型能力和使用频率。即使单价很低，如果每天大量调用推理模型、上下文很长、历史记录不清理，一个月下来也可能不是“0 成本”。
如果你是自己学习或小规模验证，按量付费很合适。如果是团队重度使用，建议做两件事：
- 给每条对话设置最大历史轮数，避免无限堆积。
- 记录每个项目的 token 消耗，定期复盘哪里贵、哪里可以精简。
6.3 我的最终建议
这条路线值得尝试，但不是因为它能让你“白嫖”，而是因为它把“用 Codex 交互 + 用 DeepSeek 出活”这个组合变成了一种低成本可实验的开发方式。它适合愿意折腾环境、接受模型能力差异、并且有时间做小规模验证的开发者。如果你想要的是一键安装、零配置、生产级稳定，那还不适合。
从一个朴素的经验来说，18 分钟跑通只是起点，能连续稳定跑两周才算真正上手。先按上面的步骤跑通最小流程，然后把每一次报错记录下来，形成自己的排查清单。这套方法不只适用于 Codex 和 DeepSeek，换成任何新工具、新模型、新客户端的组合，都是同一个逻辑：先确认底层 API 通不通，再检查中间层有没有改写请求，最后再看上层客户端有没有读对配置。把这三层理顺，绝大多数问题都能在五分钟内定位。
