Codex CLI接入DeepSeek：18分钟跑通低成本AI编程

开头先交代背景：很多人想用 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 限流、上下文长度限制、工具调用稳定性等等。

所以下文会按这个顺序展开：

1. 环境准备和安装。
2. 配置 DeepSeek API 的关键点。
3. Codex CLI 和客户端的路径问题。
4. 代理接口错误和模型参数问题。
5. 常见报错排查与长期使用建议。

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。
• 客户端能打开，但点不了操作，后台日志也在报找不到二进制。

排查顺序建议：

1. 在终端确认codex --version能输出版本号。
2. 执行which codex或where codex，拿到绝对路径。
3. 在客户端设置中把codex_cli_path设为该绝对路径。
4. 重启客户端，再看日志。

不要跳过第一步直接配置路径，因为很可能你的 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” 的报错。

遇到这种情况，最简单的验证方式是：

1. 直接写一段 curl 请求，手动请求 DeepSeek 的/v1/chat/completions，确认 key 和模型可用。
2. 再试/v1/responses或 Codex 当前使用的端点，看 API 是否支持。
3. 如果不支持，要么更换 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 本身支持把任务拆成多轮对话、文件修改和命令执行。第一次使用建议这样渐进：

1. 先让它回答一个纯文本问题，确认模型返回正常。
2. 再给一个小任务，比如“读取当前目录下 README.md，总结里面的 API 列表”。
3. 再给它一个修改类任务，明确告诉它只能改哪些文件。
4. 最后再进入自治模式，让它自己决定执行哪些命令。

不要一上来就让它在真实项目里随意修改文件。模型会犯错，API 会限流，工具调用也会失败。先小规模验证，再扩大范围，这是所有 AI 编程工具的正确使用姿势。

5.3 如果团队要统一使用，需要补的工程能力

如果一个小组想统一走“Codex + DeepSeek”这套方案，单机配置就不够了。至少还需要考虑：

• 统一的 API key 管理，不要每个人把 key 写死在 shell 历史里。
• 模型的成本统计，按项目或按人拆分。
• 日志集中收集，方便出了问题看是模型问题、代理问题还是 Codex 版本问题。
• 配置模板，通过仓库统一分发config.toml。
• 定期更新 Codex CLI 和客户端，避免因版本落后产生兼容问题。

这些问题普通个人开发者不用全做，但团队场景必须尽早规划，否则后面每一次升级都可能出现“我这能跑，他那不能跑”的局面。

6. 常见报错速查与最终建议

6.1 症状到原因的对应思路

这个表格不是让你对着抄，而是给一个排查时的判断框架：先判断问题在哪一层，再动手改。不要一看到 400 就怀疑 API key，也不要一看到 timeout 就换代理。先看日志，再看请求，最后再动配置。

6.2 使用成本的真实评估

DeepSeek 的 API 按 token 计费，价格通常比 OpenAI 便宜很多。但“便宜”只适合做总量判断，不能忽略模型能力和使用频率。即使单价很低，如果每天大量调用推理模型、上下文很长、历史记录不清理，一个月下来也可能不是“0 成本”。

如果你是自己学习或小规模验证，按量付费很合适。如果是团队重度使用，建议做两件事：

• 给每条对话设置最大历史轮数，避免无限堆积。
• 记录每个项目的 token 消耗，定期复盘哪里贵、哪里可以精简。

6.3 我的最终建议

这条路线值得尝试，但不是因为它能让你“白嫖”，而是因为它把“用 Codex 交互 + 用 DeepSeek 出活”这个组合变成了一种低成本可实验的开发方式。它适合愿意折腾环境、接受模型能力差异、并且有时间做小规模验证的开发者。如果你想要的是一键安装、零配置、生产级稳定，那还不适合。

从一个朴素的经验来说，18 分钟跑通只是起点，能连续稳定跑两周才算真正上手。先按上面的步骤跑通最小流程，然后把每一次报错记录下来，形成自己的排查清单。这套方法不只适用于 Codex 和 DeepSeek，换成任何新工具、新模型、新客户端的组合，都是同一个逻辑：先确认底层 API 通不通，再检查中间层有没有改写请求，最后再看上层客户端有没有读对配置。把这三层理顺，绝大多数问题都能在五分钟内定位。