1. 前言：为什么选择 Codex + DeepSeek

Codex 是 OpenAI 推出的命令行 AI 编程助手，默认对接的是 ChatGPT 账号与 OpenAI 官方模型。对国内开发者来说，默认方案有两个明显痛点：

• 网络不稳定：访问 OpenAI 接口需要代理，体验时好时坏。
• 成本偏高：高频编码场景下，OpenAI 模型的费用相对更高。

好消息是，Codex 本身支持自定义模型提供商（Custom Model Provider），只要目标服务兼容 OpenAI 接口协议，就能把后端模型替换掉。DeepSeek 恰好提供了与 OpenAI 完全兼容的 API，并且：

• 国内直连、稳定、无需代理；
• 价格低，deepseek-chat 与 deepseek-reasoner 都能用于编程；
• 代码能力在开源与国产模型中处于第一梯队。

本教程以 Windows 11 为例，完整演示从零开始，把 Codex 的默认模型换成 DeepSeek 的全过程。macOS/Linux 的配置思路完全一致，只是安装命令与路径略有差异。

---

2. 整体配置思路

先建立全局认知，后面每步操作都会回归到这张图上。

Codex 的所有配置集中在一个文件里：

C:\Users\<你的用户名>\.codex\config.toml

我们要做的事可以概括为三步：

1. 安装 Codex CLI；
2. 把 DeepSeek 的 API Key 写进环境变量；
3. 在 config.toml 中注册一个名为 deepseek 的自定义模型提供商，并把它设为默认模型。

其中最关键的是下面的配置映射关系：

配置项	含义
model_provider	当前默认使用哪个提供商
model	当前默认使用哪个模型
[model_providers.deepseek]	定义名为 deepseek 的提供商
name	提供商显示名称
base_url	DeepSeek 的兼容接口地址
env_key	从哪个环境变量读取 API Key
wire_api	使用哪种协议，DeepSeek 用 chat

---

3. 准备 DeepSeek API Key

3.1 注册并开通

1. 打开 DeepSeek 开放平台：https://platform.deepseek.com。
2. 使用手机号或邮箱注册账号，完成登录。
3. 进入控制台，在「充值」页面按需充值。DeepSeek 按量计费，个人调试充 10 元就能用很久。

注意区分：chat.deepseek.com 是网页版聊天界面，platform.deepseek.com 才是开放的 API 平台，API Key 必须在后者创建。

3.2 创建 API Key

1. 在左侧菜单点击「API keys」。
2. 点击「创建 API key」，可以填一个备注名，比如 codex。
3. 创建成功后，页面会显示一个形如 sk-xxxxxxxxxxxxxxxx 的密钥。

这个密钥只显示一次，请立即复制并妥善保存。它本质上就是账户的支付凭证，泄露后可能被他人盗刷。

---

4. 安装 Node.js 与 Codex CLI

Codex CLI 官方推荐通过 npm 安装，因此需要先准备 Node.js 环境。

4.1 安装 Node.js

打开 PowerShell（建议以管理员身份运行），使用 winget 安装 LTS 版本：

winget install OpenJS.NodeJS.LTS

也可以到官网 https://nodejs.org 下载 Windows 安装包，一路下一步即可。

安装完成后，关闭并重新打开 PowerShell，验证：

node -v
npm -v

能看到版本号（如 v20.x.x、10.x.x）即表示成功。

4.2 安装 Codex CLI

继续执行：

npm install -g @openai/codex

安装过程需要几分钟。完成后验证：

codex --version

如果提示「无法将 codex 识别为 cmdlet」，通常是 npm 全局目录没有被加入 PATH，重启终端再试一次；仍然失败的话，检查 Node.js 是否安装完整。

---

5. 写入 DeepSeek API Key 环境变量

Codex 不会把密钥写死在代码或配置文件中，而是通过环境变量读取，这样更安全。

5.1 临时设置（仅当前终端会话有效）

PowerShell 中执行：

$env:DEEPSEEK_API_KEY = "sk-你的密钥"

这种方式关闭终端后就会失效，适合先做快速测试。

5.2 永久设置（推荐）

使用 setx 把变量写入用户级环境变量：

setx DEEPSEEK_API_KEY "sk-你的密钥"

setx 对之后新打开的终端才生效，当前已打开的终端不会自动继承。

也可以通过图形界面设置：按 Win + R 输入 sysdm.cpl，进入「高级 → 环境变量」，在「用户变量」中新建：

• 变量名：DEEPSEEK_API_KEY
• 变量值：sk-你的密钥

设置完成后，重新打开一个 PowerShell，验证是否生效：

echo $env:DEEPSEEK_API_KEY

能打印出密钥即成功。

---

6. 编写 config.toml 配置 DeepSeek

这是把 Codex 切到 DeepSeek 的核心步骤。

6.1 创建配置目录

PowerShell 执行：

New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex

6.2 创建并编辑配置文件

执行下面命令，用记事本打开配置文件（不存在会自动新建）：

notepad $env: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"
requires_openai_auth = false

各字段说明：

• model = "deepseek-chat"：默认使用 DeepSeek 的对话模型，兼顾速度与成本，适合日常编码。
• model_provider = "deepseek"：指向下面定义的提供商。
• base_url：DeepSeek 的 OpenAI 兼容接口，https://api.deepseek.com/v1 与 https://api.deepseek.com 均可。
• env_key = "DEEPSEEK_API_KEY"：告诉 Codex 从名为 DEEPSEEK_API_KEY 的环境变量读取密钥。
• wire_api = "chat"：使用 Chat Completions 协议。DeepSeek 走的是 chat，而不是 OpenAI 官方的 responses。
• requires_openai_auth = false：跳过 OpenAI 账号强制登录，直接使用第三方模型。

保存后关闭记事本。

---

7. 启动并验证

重新打开一个 PowerShell（确保环境变量已生效），执行：

codex "用一段话解释什么是递归"

如果配置正确，Codex 会调用 DeepSeek 返回解释。你可以再加一个简单的编程任务验证代码能力：

codex "用 Python 写一个冒泡排序，并加上注释"

7.1 临时切换为推理模型

不需要改动配置文件，也可以在启动时用 -m 指定模型。DeepSeek 的推理模型 deepseek-reasoner 更适合复杂架构与算法问题：

codex -m deepseek-reasoner "分析这段代码的性能瓶颈"

7.2 直接验证 API 连通性

如果 Codex 一直报错，可以先绕过 Codex，用 curl 直接测试 DeepSeek 接口是否可用（在已设置环境变量的终端中执行）：

curl.exe -X POST https://api.deepseek.com/v1/chat/completions `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer $env:DEEPSEEK_API_KEY" `
  -d "{\"model\":\"deepseek-chat\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}"

能返回 JSON 说明 Key 与网络都没问题，再把排查重心放回 Codex 配置上。

---

8. 常用模型与参数建议

DeepSeek 主要有两个可用的对话模型：

模型	特点	适用场景
deepseek-chat	响应快、成本最低	日常问答、代码补全、一般重构
deepseek-reasoner	带深度推理，速度较慢	复杂架构设计、疑难 bug 定位

在 Codex 中切换模型有两种方式：

• 临时切换：codex -m deepseek-reasoner，仅本次生效。
• 永久切换：修改 config.toml 顶部的 model = "..."。

如果希望接受自动执行命令、减少每次确认，可以在 config.toml 中追加：

approval_policy = "on-request"

其中 on-request 表示由 Codex 判断有需要时再请求你的批准。更激进的 never 会让 Codex 自动执行命令，风险较高，不建议新手开启。

---

9. 常见问题排查

9.1 提示「model provider not found」

说明 config.toml 中的 model_provider 与 [model_providers.xxx] 的名称不一致。检查两个地方是否完全一致，注意大小写。

9.2 提示鉴权失败 / 401 / api key 无效

• 确认 DEEPSEEK_API_KEY 环境变量真的存在：echo $env:DEEPSEEK_API_KEY；
• 确认 Key 是从 platform.deepseek.com 创建，而不是网页版；
• 确认 Key 没有多余空格，setx 时如果 Key 含特殊字符建议用图形界面设置；
• 确认账户余额不为 0。

9.3 仍然弹出 ChatGPT 登录界面

说明 requires_openai_auth = false 没有生效。检查：

• 配置是否真的保存到了 C:\Users\<你的用户名>\.codex\config.toml；
• Codex 版本是否过旧，可执行 npm install -g @openai/codex@latest 升级到最新版；
• 文件是否被记事本意外存成了 config.toml.txt（查看完整文件名，去掉多余后缀）。

9.4 响应很慢或报超时

DeepSeek 推理模型 deepseek-reasoner 速度明显慢于 deepseek-chat，属于正常现象；如果 deepseek-chat 也超时，先按 7.2 的方法用 curl 测试网络连通性。

9.5 想彻底卸载换回官方模型

执行以下命令卸载：

npm uninstall -g @openai/codex

如果要恢复默认配置，删除 C:\Users\<你的用户名>\.codex\config.toml 即可，环境变量可以保留不影响其它程序。

---

10. 总结

至此，你已经完成了在 Windows 11 下用 DeepSeek 驱动 Codex 的全部配置。整体链路回顾：

1. 在 DeepSeek 开放平台创建 API Key；
2. 安装 Node.js 与 Codex CLI；
3. 把 Key 写入环境变量 DEEPSEEK_API_KEY；
4. 在 ~/.codex/config.toml 中注册自定义提供商；
5. 用 codex 命令验证调用。

这套方案的收益很明显：国产模型、国内直连、成本可控，同时保留了 Codex 强大的终端编程体验。日常开发用 deepseek-chat，遇到复杂问题临时切到 deepseek-reasoner，是一个比较舒服的组合。