Codex 配置 DeepSeek 模型详细教程

最后更新：2026-08-12· 14 分钟阅读

🚀 快速通道

ChatGPT 国内版：点击直达↗
稳定镜像站：打开镜像↗
官方 ChatGPT：chatgpt.com ↗

更新时间：2026-08-12

导读

Codex 默认使用 OpenAI 模型；通过 ~/.codex/config.toml 中的 model_providers，可以把推理后端切换为 DeepSeek API——在保留 Codex「读仓库、改文件、跑命令」工作流的同时，使用 deepseek-v4-pro、deepseek-v4-flash 等模型。

本文覆盖：申请密钥 → 环境变量 → config.toml → curl 连通性验证 → 常见报错。开始前请已完成 Codex 安装与基础配置。DeepSeek 端点、模型名与 Codex 版本行为以 DeepSeek API 文档与 Codex 配置文档为准。

为什么要给 Codex 接 DeepSeek？

诉求	DeepSeek 作为后端的潜在收益
成本	API 单价通常低于同档 OpenAI 模型，适合高频 Agent 调用
中文与代码	V4 系列在中文注释、报错解释场景表现稳定
数据路径	密钥与请求走 DeepSeek 官方或自建网关，便于合规审计

注意： Codex 的工具调用、沙箱、审批仍由 Codex 客户端实现；换模型不会自动降低「乱改文件」风险，权限策略仍需严格配置。

第一步：获取 DeepSeek API Key

打开 DeepSeek 官网进入开发者平台（步骤以当前页面为准）。
完成账号、计费与 API Key 创建——密钥通常只显示一次，应存入密码管理器。
禁止把 Key 写入 Git、前端代码或 config.toml 明文；应使用环境变量。

更完整的申请、首个请求与生产清单见 DeepSeek API 申请与开发入门。若暂时只想在浏览器体验模型能力，可用 DeepSeek V4 国内入口或 AI Chat Studio 镜像——网页聊天与 API 账号、配额并不默认相同。

第二步：确认 API 参数

根据 DeepSeek API 文档，OpenAI 兼容接口常用参数为：

参数	值
Base URL	`https://api.deepseek.com`
认证	`Authorization: Bearer $DEEPSEEK_API_KEY`
模型名（示例）	`deepseek-v4-pro`、`deepseek-v4-flash`

模型字符串会更新，务必从文档复制，不要沿用旧教程中的 deepseek-chat 等过期名称。编程向任务可优先试 deepseek-v4-pro；对延迟敏感时可试 deepseek-v4-flash。

第三步：设置环境变量

macOS / Linux（当前 shell）：

export DEEPSEEK_API_KEY="你的密钥"

Windows PowerShell（当前会话）：

$env:DEEPSEEK_API_KEY = "你的密钥"

生产环境应使用系统密钥管理或 CI Secret，而非长期写在 shell 配置文件里。DeepSeek 侧安全实践详见 API 指南中的「上线必做」一节。

第四步：编辑 ~/.codex/config.toml

以下配置需写在用户级 ~/.codex/config.toml（Windows：%USERPROFILE%\.codex\config.toml）。model_provider 与 model_providers 不能仅写在项目级 .codex/config.toml 中——Codex 会忽略项目文件里的这些键。

# 声明 DeepSeek 为自定义 provider
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
requires_openai_auth = false

# 切换默认后端
model_provider = "deepseek"
model = "deepseek-v4-pro"

# 新手建议保持询问式审批
approval_policy = "on-request"
sandbox_mode = "workspace-write"

字段说明

字段	作用
`base_url`	DeepSeek API 根地址；若文档要求带 `/v1` 后缀，以文档为准
`wire_api`	Codex 新版本默认走 `responses` 协议；若网关仅支持 Chat Completions，需确认 DeepSeek 或中转是否提供兼容端点
`env_key`	从该环境变量读取 Bearer Token
`requires_openai_auth = false`	非 OpenAI 密钥前缀时必须设为 false
`model`	必须与 DeepSeek 文档中的模型 ID 完全一致

DeepSeek 文档提到其 API 已被 Claude Code、Copilot 等 Agent 工具支持；Codex 通过 OpenAI 兼容 + model_providers 接入，思路与 DeepSeek 编程实战中的 API 调用一致，只是配置入口在 Codex 而非 SDK 代码里。

第五步：用 curl 先验证 API

在改 Codex 之前，用最小请求确认密钥与模型名有效（占位符请替换为文档当前值）：

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "回复 OK"}],
    "stream": false
  }'

若 curl 失败，先修 Key、余额与模型名，不要在 Codex 里反复试。curl 成功后再在项目目录运行 codex，发起只读任务验证端到端链路。

使用 Profile 做多模型切换

若你希望「日常用 DeepSeek、Review 用 OpenAI」，可用 Profile overlay：

[profiles.openai-default]
model_provider = "openai"
model = "gpt-5.4"

[profiles.deepseek-coding]
model_provider = "deepseek"
model = "deepseek-v4-pro"
model_reasoning_effort = "high"

启动时指定：codex --profile deepseek-coding。Profile 文件也可放在 ~/.codex/deepseek-coding.config.toml，详见官方 Profile 说明。

排错清单

现象	可能原因	处理
401 / 认证失败	Key 错误或环境变量未导出	重新 export；勿在公共场合 echo 密钥
404 / model not found	模型名过期或拼写错误	对照 API 文档模型表
wire_api / responses 报错	Codex 与网关协议不匹配	确认 DeepSeek 或中转是否支持 Codex 所需的 `responses` 接口
配置改了不生效	写在项目 config 或被 Profile 覆盖	检查用户级 `config.toml` 与 `--profile`
响应慢或断流	网络或超时设置	调整 provider 超时；国内网络可评估合规网关
代码质量下降	模型与任务不匹配	复杂推理可换 `deepseek-v4-pro`；参考 DeepSeek R1 推理指南

重要： Codex 在 2026 年初后倾向于 wire_api = "responses"。若 DeepSeek 官方仅暴露 /chat/completions 而你的 Codex 版本强制 responses，可能需要等待官方 Agent 集成更新、使用 DeepSeek 文档推荐的兼容层，或经团队评估后使用提供 /v1/responses 的合规网关——不要在生产环境硬改 requires_openai_auth 或关闭沙箱来「绕过」报错。

安全与合规

DeepSeek API Key 与 OpenAI Key 分开轮换，不要共用同一 env 名。
公司仓库接入前确认数据出境与供应商政策。
Codex 仍可能读取仓库内的业务逻辑；敏感模块使用 read-only 沙箱或排除目录。
账单以 DeepSeek 控制台为准，与 ChatGPT Codex 订阅独立计费。

常见问题

配好 DeepSeek 后还能用 ChatGPT 登录吗？

可以。model_provider 决定推理后端；ChatGPT 登录用于 Codex 产品授权。两者关系以你当前 Codex 版本说明为准，若冲突以官方文档为准。

deepseek-v4-flash 和 deepseek-v4-pro 怎么选？

pro 适合复杂重构与多文件推理；flash 适合快问快答、注释与小型 patch。用同一仓库各跑 5 个真实任务对比修改行数与测试通过率，比看宣传参数更可靠。

能否在 IDE 扩展里用 DeepSeek 后端？

IDE 扩展与 CLI 共享用户级 config.toml，配置方式相同。改完后重启扩展或重新加载窗口。

国内网页入口的 DeepSeek 与 API 是同一套吗？

不一定。DeepSeek V4 国内入口与 AI Chat Studio 适合体验对话；Codex Agent 必须配置 API Key。参见 DeepSeek 国内使用安全指南。

与直接用 DeepSeek 网页写代码相比有何优势？

Codex 优势在仓库上下文 + 执行测试 + 多文件 patch 闭环；纯聊天更适合单次片段。两者可互补：复杂架构先用 DeepSeek 提示词指南理清思路，再在 Codex 里落地改动。

官方资源

下一步阅读

行动路径

今天：curl 验证 Key 与模型名，再在练习仓库跑一条只读 Codex 指令。本周：用 DeepSeek 后端完成一次 failing test 修复，记录与 OpenAI 默认模型的耗时与 diff 行数。上线前：在团队内文档化 model_provider 切换方式、密钥轮换流程与回滚 Profile（codex --profile openai-default）。

导读