Codex 桌面版接入 DeepSeek API 配置指南

本文档记录如何将 Codex 桌面版（OpenAI Codex / ChatGPT 桌面应用内的 Codex）从 OpenAI 官方 API 切换到 DeepSeek API，实现免代理直连 DeepSeek-V4 系列模型。

1. 概述

Codex 桌面版本质上是微软商店安装的 MSIX 应用（包名 OpenAI.Codex），其配置目录与 Codex CLI 完全一致，均位于：

复制代码

C:\Users\<用户名>\.codex\
├── config.toml      # 主配置（模型、Provider、认证方式等）
├── models.json      # 模型目录（声明 DeepSeek 模型元数据）
└── auth.json        # API Key 认证信息

DeepSeek 官方已原生支持 Codex 所需的 Responses API（wire_api = "responses"），因此无需本地中转代理，可直接在 config.toml 中配置 base_url = "https://api.deepseek.com/" 实现直连。

2. 适用环境

项目	值
Codex 版本	`codex-cli 0.147.0-alpha.6.5`（桌面版 26.803.5235.0）
操作系统	Windows（本文以 Windows 为例）
DeepSeek 模型	`deepseek-v4-flash`（默认）、`deepseek-v4-pro`
API 要求	账户已开通 API，且密钥以 `sk-` 开头

3. 配置步骤

3.1 修改 config.toml

编辑 C:\Users\<用户名>\.codex\config.toml，在文件顶层（任意 [xxx] 节之前）加入以下键：

toml 复制代码

model = "deepseek-v4-flash"      # 默认模型
model_provider = "deepseek"      # 默认 Provider
preferred_auth_method = "apikey" # 优先使用 API Key 认证
forced_login_method = "api"      # 强制使用 API 登录方式（绕过 ChatGPT 账号登录）
model_reasoning_effort = "high"  # 推理强度
model_catalog_json = "C:/Users/<用户名>/.codex/models.json"  # 模型目录（注意正斜杠）

然后在文件末尾追加 Provider 定义：

toml 复制代码

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "sk-你的DeepSeek密钥"

注意

experimental_bearer_token 直接以明文存放 API Key（与 DeepSeek 官方一键脚本行为一致），请勿将 config.toml 提交到公开仓库。

model_catalog_json 在 Windows 上必须使用正斜杠路径。

若已有其他 [model_providers.xxx]，仅追加 [model_providers.deepseek]，不要改动原有内容。

3.2 创建 models.json

Codex 需要通过模型目录（model catalog）识别 DeepSeek 模型元数据（上下文窗口、工具能力、系统提示词等），该文件内容由 DeepSeek 官方提供。

方式一：官方一键脚本（推荐，最省事）

powershell 复制代码

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

该脚本会：写入 config.toml、生成 models.json、询问 API Key，并自动备份原配置。

方式二：手动获取

下载官方脚本后，从中提取 $ModelsJson 区块写入 models.json：

powershell 复制代码

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 -OutFile "$env:TEMP\setup.ps1"

models.json 的结构如下（包含 deepseek-v4-flash 与 deepseek-v4-pro 两个模型的完整元数据）：

json 复制代码

{
  "models": [
    {
      "slug": "deepseek-v4-flash",
      "display_name": "DeepSeek-V4-Flash",
      "description": "Latest frontier agentic coding model.",
      "context_window": 1048576,
      "wire_api": "responses",
      "priority": 1
    },
    {
      "slug": "deepseek-v4-pro",
      "display_name": "DeepSeek-V4-Pro",
      "description": "Most capable frontier agentic coding model.",
      "context_window": 1048576,
      "priority": 2
    }
  ]
}

实际完整文件远超上面示例，含 model_messages.instructions_template、base_instructions 等长文本字段，请以官方脚本产出的完整内容为准。

3.3 重启生效

修改完成后重启 Codex 桌面版 （完全退出再打开）。启动后在模型选择器中应能看到 DeepSeek-V4-Flash。

4. 验证配置

方式一：API Key 连通性测试

powershell 复制代码

Invoke-RestMethod -Uri "https://api.deepseek.com/models" `
  -Headers @{ Authorization = "Bearer sk-你的DeepSeek密钥" }

正常返回模型列表即代表 Key 有效。

方式二：实际对话测试

powershell 复制代码

codex exec "say OK"

若日志中出现 model=deepseek-v4-flash auth_mode="ApiKey" 且最终返回 response.completed，说明已成功通过 DeepSeek 响应。

注：在受限沙箱/终端环境中运行 codex 可能报"拒绝访问 .codex\tmp"之类的会话写入错误，这是环境权限问题，与配置无关。

5. 本机配置状态（2026-08-08）

本机已按上述步骤完成配置并验证通过：

文件	路径	状态
主配置	`C:\Users\admin\.codex\config.toml`	已加入 DeepSeek Provider
模型目录	`C:\Users\admin\.codex\models.json`	已创建（含 flash/pro 两模型）
原配置备份	`C:\Users\admin\.codex\backup-deepseek\config.toml`	切换前备份

6. 备份与恢复

恢复原 OpenAI 配置：

powershell 复制代码

Copy-Item "C:\Users\admin\.codex\backup-deepseek\config.toml" "C:\Users\admin\.codex\config.toml" -Force

离线安装包备份：

Codex 桌面版为微软商店 MSIX 应用，本机离线安装包已备份至：

复制代码

C:\Users\admin\Downloads\Codex-Backup\
├── OpenAI.Codex_26.803.5235.0_x64__2p2nqsd0c76g0.msix      # 667 MB 官方安装包
└── OpenAI.Codex_26.803.5235.0_x64__2p2nqsd0c76g0.msix.sha256

重装命令：

powershell 复制代码

Add-AppxPackage -Path "C:\Users\admin\Downloads\Codex-Backup\OpenAI.Codex_26.803.5235.0_x64__2p2nqsd0c76g0.msix"

7. 常见问题

Q1：切换后 Codex 仍提示需要登录 ChatGPT？

检查 forced_login_method = "api" 与 preferred_auth_method = "apikey" 是否已写入 config.toml 顶层。

Q2：报错 model not found 或找不到模型？

确认 model_catalog_json 路径正确（正斜杠），且 models.json 中确实包含对应 slug。

Q3：报错 wire_api = "chat" 已不受支持？

新版 Codex（≥0.138）已移除 Chat Completions 支持，请确认 Provider 中 wire_api = "responses" 且 DeepSeek 版本支持 Responses API。

Q4：如何切换 flash / pro 模型？

修改 config.toml 中的 model = "deepseek-v4-flash" 或 model = "deepseek-v4-pro"，或在 Codex 桌面版模型选择器中直接切换。

Q5：配置丢失后如何一键重配？

重新运行官方脚本：irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

8. 参考链接

DeepSeek API 文档（Codex 集成）：https://api-docs.deepseek.com/quick_start/agent_integrations/codex/
DeepSeek 官方一键配置脚本：https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1
DeepSeek 开放平台：https://platform.deepseek.com/