Codex 配置 DeepSeek 模型详细教程：从 API 到 Responses 兼容网关

很多教程会让你在 Codex 的 config.toml 中写入 DeepSeek 的 Base URL，再设置 wire_api = "chat"。这个办法在旧版 Codex 中曾经可用，但在当前版本中已经失效。

现在接入 DeepSeek，最重要的不是模型名称，而是 API 协议：Codex 当前要求自定义模型供应商提供 OpenAI Responses API，不能再使用 Chat Completions 协议。 如果你的 DeepSeek 接口只有 /chat/completions，就需要在中间增加一个能够接收 /responses 请求并转换协议的兼容网关。

本文将完整讲清以下内容：

为什么 DeepSeek 官方兼容接口不一定能直接接入 Codex
Codex、Responses API 和 DeepSeek 之间是什么关系
如何安全保存 API Key
如何编写 ~/.codex/config.toml
如何通过 Responses 兼容网关使用 DeepSeek
如何验证接口、启动 Codex 并排查常见错误

IMPORTANT

本文以 codex-cli 0.146.0-alpha.3.1 的实际配置校验结果为基准。Codex 更新速度很快，操作前建议先执行 codex --version，并结合文末官方资料确认最新行为。

一、先看结论：当前应该怎样接入

可用的请求链路如下：

text

Codex CLI
    ↓  POST /v1/responses
Responses 兼容网关
    ↓  转换为供应商支持的请求格式
DeepSeek 模型 API

需要满足三个条件：

Codex 中的 wire_api 必须是 "responses"。
base_url 对应的服务必须真正实现 /responses，仅宣传“兼容 OpenAI API”并不够。
网关必须能把 Codex 使用的工具调用、流式输出和 Responses 事件正确转换给 DeepSeek。

下列旧配置不要再使用：

toml

# 当前 Codex 已不再支持
wire_api = "chat"

当前 Codex 会直接拒绝该配置，并提示：

text

`wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

这也解释了为什么有些配置看起来完全正确，启动时却还没发出网络请求就失败了。

二、准备工作

开始前需要准备：

已安装 Codex CLI
一个可用的 DeepSeek API Key
一个支持 OpenAI Responses API 的网关
Node.js 和 npm（用于安装或更新 Codex）
如果选择本地网关方案，还需要 Python 3.10+ 或 Docker

1. 安装或更新 Codex

使用 npm 安装：

bash

npm install -g @openai/codex

macOS 也可以使用 Homebrew：

bash

brew install codex

检查版本：

bash

codex --version

如果已经安装，但文章中的配置字段不生效，先更新 Codex，再重新验证。

2. 获取 DeepSeek API Key

在 DeepSeek 开放平台创建 API Key。密钥通常只完整显示一次，创建后应立即保存到密码管理器，不要放进项目代码、Git 仓库、截图或聊天记录。

DeepSeek API 控制台和接口文档可能调整入口，请从 DeepSeek API 官方文档进入，避免从搜索结果中的第三方页面创建密钥。

三、确认你的接口是否支持 Responses API

“OpenAI 兼容”可能有两种完全不同的含义：

兼容范围	常见端点	能否直接供当前 Codex 使用
只兼容 Chat Completions	`/v1/chat/completions`	不能
兼容 Responses API	`/v1/responses`	可以继续测试

因此，不能只看 Base URL 或供应商宣传。最可靠的判断方法，是直接向网关的 /responses 发送最小请求。

假设网关地址为 https://gateway.example.com/v1：

bash

curl https://gateway.example.com/v1/responses \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "input": "只回复 OK"
  }'

判断结果：

返回正常 JSON：基础 Responses 接口可用，可以继续配置 Codex。
返回 404：Base URL 不对，或者服务没有实现 /responses。
返回 401：接口存在，但 API Key 错误或认证头不符合要求。
返回“unknown field: input”：服务可能只支持 Chat Completions。
普通对话成功但 Codex 工具调用失败：网关的 Responses 兼容层不完整。

WARNING

不要把 YOUR_GATEWAY_API_KEY 原样写入脚本并提交到 Git。上面的命令只用于说明请求结构，实际使用时应从环境变量读取密钥。

四、方案 A：使用现成的 Responses 兼容网关

如果你使用云端代理或公司统一 AI 网关，需要向服务方确认以下信息：

Responses API Base URL，例如 https://gateway.example.com/v1
网关要求的 API Key
DeepSeek 在网关中的准确模型 ID
是否支持流式 Responses
是否支持 function calling 或 tool calling

注意，网关里的模型 ID 不一定是 DeepSeek 官方名称。可能是 deepseek-chat，也可能包含命名空间。以网关的模型列表为准，不要猜测。

拿到这些信息后，可以直接进入第六节配置 Codex。

五、方案 B：使用 LiteLLM 搭建本地转换网关

如果 DeepSeek 上游只提供 Chat Completions，可以使用支持 Responses API 转换的新版 LiteLLM Proxy 在本机做协议适配。

1. 安装 LiteLLM

推荐使用独立的 Python 环境：

bash

python3 -m venv .venv-litellm
source .venv-litellm/bin/activate
pip install "litellm[proxy]"

Windows PowerShell 激活命令：

powershell

.venv-litellm\Scripts\Activate.ps1
pip install "litellm[proxy]"

TIP

LiteLLM 的 Responses 支持会随版本变化。安装后先查看版本，并用上一节的 /responses 请求验证，不要只以服务能启动作为成功标准。

2. 创建 LiteLLM 配置

新建一个不放入公开仓库的 litellm-config.yaml：

yaml

model_list:
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

  - model_name: deepseek-reasoner
    litellm_params:
      model: deepseek/deepseek-reasoner
      api_key: os.environ/DEEPSEEK_API_KEY

如果 DeepSeek 后续更改模型 ID，应以其官方文档和你的账户实际可用列表为准。

3. 设置上游密钥并启动网关

macOS 或 Linux：

bash

export DEEPSEEK_API_KEY="sk-your-deepseek-key"
litellm --config ./litellm-config.yaml --host 127.0.0.1 --port 4000

Windows PowerShell：

powershell

$env:DEEPSEEK_API_KEY = "sk-your-deepseek-key"
litellm --config .\litellm-config.yaml --host 127.0.0.1 --port 4000

本地 Base URL 为：

text

http://127.0.0.1:4000/v1

启动后先验证：

bash

curl http://127.0.0.1:4000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","input":"只回复 OK"}'

如果你给 LiteLLM 配置了 Master Key，还要增加 Authorization: Bearer ... 请求头，并在 Codex 中使用对应的网关密钥。

CAUTION

本地代理只监听 127.0.0.1。不要为了省事监听 0.0.0.0 并暴露到公网，否则可能泄露模型额度和上游 API Key。

六、配置 Codex 的 config.toml

Codex 的用户级配置文件位于：

系统	默认路径
macOS	`~/.codex/config.toml`
Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

自定义模型供应商属于机器级配置。不要把包含供应商和认证信息的配置直接放进项目的 .codex/config.toml。

1. 云端网关完整配置

打开 ~/.codex/config.toml，加入以下内容：

toml

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek via Responses Gateway"
base_url = "https://gateway.example.com/v1"
env_key = "DEEPSEEK_CODEX_API_KEY"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 2
stream_max_retries = 2
stream_idle_timeout_ms = 300000

字段说明：

字段	作用
`model`	发给网关的模型 ID，必须与网关提供的名称一致
`model_provider`	选择下面定义的供应商 ID，此处为 `deepseek`
`name`	在日志和界面中显示的供应商名称
`base_url`	Responses 网关地址，通常包含 `/v1`，不要写到 `/responses`
`env_key`	保存网关密钥的环境变量名，不是密钥本身
`wire_api`	当前应固定为 `"responses"`
`requires_openai_auth`	自定义供应商通常设为 `false`，不使用 OpenAI 登录凭证
`request_max_retries`	普通请求失败后的重试次数
`stream_max_retries`	流式连接中断后的重试次数
`stream_idle_timeout_ms`	流式响应空闲超时，推理模型可适当放宽

然后设置网关密钥。

macOS 或 Linux：

bash

export DEEPSEEK_CODEX_API_KEY="your-gateway-api-key"

Windows PowerShell，仅当前窗口生效：

powershell

$env:DEEPSEEK_CODEX_API_KEY = "your-gateway-api-key"

这里的密钥是网关要求 Codex 提交的密钥。如果网关代管上游 DeepSeek 凭证，它可能与 DeepSeek API Key 不同。

2. 本地无认证 LiteLLM 配置

如果 LiteLLM 只监听本机并且没有设置 Master Key，可以省略 env_key：

toml

model = "deepseek-chat"
model_provider = "deepseek_local"

[model_providers.deepseek_local]
name = "Local DeepSeek Gateway"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 1
stream_max_retries = 1
stream_idle_timeout_ms = 300000

3. 为什么不要把 API Key 直接写进 TOML

下面这种写法不推荐：

toml

# 不要这样保存真实密钥
experimental_bearer_token = "sk-xxxxxxxx"

明文密钥容易进入备份、日志、截图和同步盘。使用 env_key，让配置文件只保存环境变量名称，更容易控制泄露范围。

七、启动并验证 Codex

1. 先检查配置和环境

bash

codex doctor --summary

如果要让 Codex 对未知配置字段直接报错，可以在启动时使用：

bash

codex --strict-config

这能尽早发现拼写错误，例如把 model_provider 写成 model_provide。

2. 在项目中启动

bash

cd your-project
codex

首次测试不要直接交给模型大范围修改。可以先输入：

text

只读分析当前项目，告诉我使用了什么技术栈，并列出三个主要入口文件。不要修改任何文件。

这一步可以同时验证：

模型能否正常回复
Codex 能否解析流式事件
工具调用是否可用
模型是否能理解工具执行结果

3. 临时切换模型

配置了供应商后，可以通过 -m 临时指定同一网关中的模型：

bash

codex -m deepseek-reasoner

该命令只覆盖当前会话的模型，不修改 config.toml。前提是网关确实提供这个模型 ID，并且其 Responses 与工具调用行为兼容 Codex。

八、常见问题排查

1. 提示 wire_api=chat 不再支持

错误示例：

text

`wire_api = "chat"` is no longer supported

原因：使用了旧版教程。

解决方法：

toml

wire_api = "responses"

但只修改这个字段还不够。base_url 指向的服务也必须真正提供 /responses，否则下一步会出现 404。

2. 返回 404 Not Found

依次检查：

base_url 是否包含网关要求的 /v1
是否错误地写成了完整的 /v1/responses
网关是否只实现 /chat/completions
反向代理是否放行 POST /responses

Codex 会自动在 base_url 后调用对应资源，一般不要把 /responses 写进 base_url。

3. 返回 401 Unauthorized

重点检查：

env_key 中写的是环境变量名称，不是实际密钥
启动 Codex 的同一个终端能否读取该环境变量
网关要求的是上游 DeepSeek Key，还是单独的网关 Key
密钥是否已过期、被禁用或余额不足

macOS 和 Linux 可检查变量是否存在，但不要直接打印完整密钥：

bash

test -n "$DEEPSEEK_CODEX_API_KEY" && echo "API key is set" || echo "API key is missing"

4. 模型能对话，但不会调用工具

这通常不是 Codex 配置文件的问题，而是兼容层能力不完整。检查网关和模型是否支持：

Responses API 的工具定义
function calling 或 tool calling
工具调用参数的结构化 JSON
工具执行结果回传
多轮连续工具调用

Codex 是编码智能体，不是普通聊天客户端。只支持文本生成的接口即使能回复，也很难完成读文件、改代码和执行测试等任务。

5. 输出中断或长时间无响应

DeepSeek 推理模型可能在复杂任务上等待较久。可以适当增加：

toml

stream_idle_timeout_ms = 300000

同时检查网关、CDN 或反向代理的读取超时。如果每次都在固定时间断开，通常是代理层超时，而不是 Codex 本身。

6. 模型 ID 不存在

模型名称以网关实际暴露的列表为准。deepseek-chat、deepseek-reasoner 或带供应商前缀的名称不是通用规则，不能在不同服务之间直接照搬。

如果网关提供模型列表接口，可先查看：

bash

curl https://gateway.example.com/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY"

7. Codex App 中没有立即生效

修改用户级 config.toml 或环境变量后，完全退出并重新打开 Codex App。通过桌面图标启动的应用不一定继承终端里的临时环境变量，因此桌面端更适合使用系统级安全凭证注入或网关自身的登录机制。

九、DeepSeek Chat 和 Reasoner 怎么选

在网关同时支持两种模型时，可以按任务选择：

场景	建议模型	原因
浏览项目、解释代码、小范围修改	`deepseek-chat`	通常响应更快、成本更容易控制
复杂调试、架构分析、多步骤推理	`deepseek-reasoner`	更适合需要较长推理链的任务
高频自动化任务	先用 Chat，再按需升级	可控制延迟和费用

模型是否适合 Codex，还取决于工具调用稳定性，而不是只看代码榜单。建议使用自己的真实仓库做三类测试：只读分析、单文件修改、跨文件修改加测试。

十、安全与成本建议

1. 给 API Key 设置最小权限

如果网关支持项目级密钥、额度限制或 IP 限制，应为 Codex 单独创建密钥。这样即使泄露，也可以单独撤销，不影响其他应用。

2. 不要关闭 Codex 的沙箱和审批机制

更换模型供应商不会改变命令执行的风险。初次使用 DeepSeek 时，建议保留默认审批策略，并使用 workspace-write 沙箱，只允许模型修改当前工作区。

不要为了绕过一次权限提示长期使用：

bash

codex --dangerously-bypass-approvals-and-sandbox

3. 记录网关和模型版本

生产团队应记录：

Codex CLI 版本
网关版本
上游模型 ID
配置变更时间
典型任务的成功率、延迟和 Token 消耗

当某次升级导致工具调用异常时，这些信息能快速定位是 Codex、网关还是模型行为发生了变化。

十一、完整检查清单

正式使用前，逐项确认：

[ ] codex --version 能正常输出版本
[ ] DeepSeek 上游 API Key 有效且有可用额度
[ ] 网关的 /v1/responses 最小请求成功
[ ] 网关支持流式输出和工具调用
[ ] model_provider 与 [model_providers.<id>] 的 ID 一致
[ ] wire_api = "responses"
[ ] base_url 没有误写成完整的 /responses 地址
[ ] API Key 通过环境变量提供，没有写入 Git
[ ] codex doctor --summary 没有关键错误
[ ] 只读项目分析任务可以完成
[ ] 单文件修改和测试任务可以完成

十二、总结

Codex 配置 DeepSeek 的核心不是填写一个 Base URL，而是解决协议兼容问题。当前 Codex 已经不再支持 wire_api = "chat"，因此只有 Chat Completions 接口的 DeepSeek 服务不能直接使用。

稳定的做法是：

准备 DeepSeek API Key。
使用真正支持 /responses 的云端或本地网关。
在用户级 ~/.codex/config.toml 中定义自定义供应商。
设置 wire_api = "responses" 和正确的模型 ID。
先验证 Responses、流式输出和工具调用，再让 Codex 修改真实项目。

只要把“模型兼容”和“API 协议兼容”区分开，绝大多数 404、工具调用失败和旧配置报错都能快速定位。

Codex 配置 DeepSeek 模型详细教程：从 API 到 Responses 兼容网关 ​

一、先看结论：当前应该怎样接入 ​

二、准备工作 ​

1. 安装或更新 Codex ​

2. 获取 DeepSeek API Key ​

三、确认你的接口是否支持 Responses API ​

四、方案 A：使用现成的 Responses 兼容网关 ​

五、方案 B：使用 LiteLLM 搭建本地转换网关 ​

1. 安装 LiteLLM ​

2. 创建 LiteLLM 配置 ​

3. 设置上游密钥并启动网关 ​

六、配置 Codex 的 config.toml ​

1. 云端网关完整配置 ​

2. 本地无认证 LiteLLM 配置 ​

3. 为什么不要把 API Key 直接写进 TOML ​

七、启动并验证 Codex ​

1. 先检查配置和环境 ​

2. 在项目中启动 ​

3. 临时切换模型 ​

八、常见问题排查 ​

1. 提示 wire_api=chat 不再支持 ​

2. 返回 404 Not Found ​

3. 返回 401 Unauthorized ​

4. 模型能对话，但不会调用工具 ​

5. 输出中断或长时间无响应 ​

6. 模型 ID 不存在 ​

7. Codex App 中没有立即生效 ​

九、DeepSeek Chat 和 Reasoner 怎么选 ​

十、安全与成本建议 ​

1. 给 API Key 设置最小权限 ​

2. 不要关闭 Codex 的沙箱和审批机制 ​

3. 记录网关和模型版本 ​

十一、完整检查清单 ​

十二、总结 ​

参考资料 ​

Codex 配置 DeepSeek 模型详细教程：从 API 到 Responses 兼容网关

一、先看结论：当前应该怎样接入

二、准备工作

1. 安装或更新 Codex

2. 获取 DeepSeek API Key

三、确认你的接口是否支持 Responses API

四、方案 A：使用现成的 Responses 兼容网关

五、方案 B：使用 LiteLLM 搭建本地转换网关

1. 安装 LiteLLM

2. 创建 LiteLLM 配置

3. 设置上游密钥并启动网关

六、配置 Codex 的 config.toml

1. 云端网关完整配置

2. 本地无认证 LiteLLM 配置

3. 为什么不要把 API Key 直接写进 TOML

七、启动并验证 Codex

1. 先检查配置和环境

2. 在项目中启动

3. 临时切换模型

八、常见问题排查

1. 提示 wire_api=chat 不再支持

2. 返回 404 Not Found

3. 返回 401 Unauthorized

4. 模型能对话，但不会调用工具

5. 输出中断或长时间无响应

6. 模型 ID 不存在

7. Codex App 中没有立即生效

九、DeepSeek Chat 和 Reasoner 怎么选

十、安全与成本建议

1. 给 API Key 设置最小权限

2. 不要关闭 Codex 的沙箱和审批机制

3. 记录网关和模型版本

十一、完整检查清单

十二、总结

参考资料