把熟悉的 Codex 工作流，接到另一套模型上：这篇指南带你完成 DeepSeek 直连配置，从准备密钥、备份设置，到核对接口、检查工具调用和恢复原配置。重点不只是“能打开”，而是知道每一步修改了什么、失败时从哪里查起。
先说结论：当前 DeepSeek 已原生支持 Responses API。本教程采用官方直连路径，不要求安装中转网关。
接口依据：DeepSeek 官方 Codex 接入指南。
核对日期：2026 年 10 月 10 日。本文依据下方官方资料编写；封面为原创生成插图，正文配图是配置示意图，不是付费 API 实测截图。本文未使用真实 DeepSeek 密钥进行端到端调用验证，不承诺不同版本的桌面客户端拥有完全相同的界面或能力。
开始之前：先分清你要修改的是什么
这里的“接入”是修改本地 Codex 客户端的模型提供方，不是把 ChatGPT 网页里的模型列表替换成 DeepSeek，也不是在 MCP 设置里添加一个模型服务器。MCP 用于连接工具和数据；模型提供方决定推理请求发到哪里，两者不是同一层。
本文优先说明本地 CLI；桌面应用和 IDE 扩展能否使用同一配置，还取决于客户端版本、配置目录、运行主机和组织限制。不要把本机配置自动套用于云任务。请先阅读 OpenAI 配置参考 中的适用范围。
准备四件事：可运行的 Codex 客户端、DeepSeek 开放平台账户与 API Key、能够访问官方 API 的网络，以及一个不含生产数据的测试目录。API 调用的用量与费用由对应提供方计算，不要把聊天订阅与第三方 API 账户混为一谈。
步骤 1：确认客户端，创建独立密钥
已经安装 CLI 的读者，先运行下面的命令，记下版本。没有 CLI 时，从 OpenAI 官方入门页面 进入对应客户端的安装说明；不要从不明镜像下载包含登录信息的安装包。
codex --version
codex --help前往 DeepSeek 开放平台，检查账户状态、可用额度与 API Key 管理入口，为这次接入建立单独密钥。给密钥取一个能辨认用途的名称，例如“Codex 本机测试”；不要把账户密码当作 API Key。
安全提醒：不要把密钥粘进文章、聊天、截图、工单或 Git 仓库。若曾公开，先撤销旧密钥，再重新生成。
后面的示例不会出现真实密钥，也不会要求把密钥填入项目源码。第一次连接时只做短任务，先确认实际计费账户，再尝试大项目。
步骤 2：备份配置，避免覆盖已有 MCP
通常要处理的是用户配置目录中的 config.toml，而不是项目代码。默认目录是 ~/.codex；如果你设置过 CODEX_HOME，请按实际目录操作。先退出正在运行的相关客户端，再备份现有配置与已有模型目录。
macOS / Linux：下面的命令只复制已存在的两个文件；备份目录带时间戳，不会清空原配置。
ds_config_dir="${CODEX_HOME:-$HOME/.codex}"
ds_backup_dir="$ds_config_dir/backup-before-deepseek-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$ds_backup_dir"
for ds_file in config.toml models.json; do
if [ -f "$ds_config_dir/$ds_file" ]; then
cp -p "$ds_config_dir/$ds_file" "$ds_backup_dir/$ds_file"
fi
done
printf '备份目录：%s\n' "$ds_backup_dir"Windows PowerShell：
$dsConfigDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
$dsBackupDir = Join-Path $dsConfigDir ('backup-before-deepseek-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
New-Item -ItemType Directory -Path $dsBackupDir -Force | Out-Null
foreach ($dsFile in @('config.toml', 'models.json')) {
$dsSource = Join-Path $dsConfigDir $dsFile
if (Test-Path $dsSource) { Copy-Item $dsSource -Destination $dsBackupDir }
}
Write-Host "备份目录：$dsBackupDir"备份可能含已有凭据，请按私密文件保存。写入新设置后，还要检查原来的 MCP、项目信任和其他自定义设置是否仍在；“保留配置”不能只看启动是否成功。
步骤 3：使用 DeepSeek 官方接入工具
DeepSeek 的 Codex 官方接入说明 提供配置脚本，负责写入模型目录并调整必要字段。菜单中可以选择 deepseek-flash、deepseek-v4-pro，也可以恢复配置。不要照抄只支持旧接口的历史教程。
建议先下载、查看，再运行。下载成功并不等于脚本已经执行；如果返回错误，应停止检查，不要跳过下载步骤。macOS / Linux：
ds_setup_file="$(mktemp -t codex-deepseek-setup.XXXXXX)"
curl -fL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh -o "$ds_setup_file"
less "$ds_setup_file"
# 查看完成并确认来源后，再单独执行下一行
bash "$ds_setup_file"在 less 中按 q 退出查看，再决定是否执行。不要把“查看”与“执行”混为一谈；脚本内容可能更新，实际行为以你下载的版本为准。
Windows PowerShell：
$dsSetupFile = Join-Path ([System.IO.Path]::GetTempPath()) ('codex-deepseek-' + [guid]::NewGuid() + '.ps1')
Invoke-WebRequest -Uri 'https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1' -OutFile $dsSetupFile
Get-Content $dsSetupFile
# 检查完成后再执行；如被执行策略阻止，先按系统提示处理
& $dsSetupFile按照终端提示选择模型并完成配置。不要为了让脚本运行而全局关闭系统安全策略。执行结束后查看变更摘要、备份位置和报错；如果你已有自定义模型目录，不应未经比较直接覆盖。
官方脚本可能把 API Key 写入配置文件。本文下一步提供环境变量认证方案；两种认证方式不要同时保留。
步骤 4：核对手动配置，改用环境变量认证
不想运行脚本，也可以按官方接入页面的手动说明准备完整 models.json，然后合并配置。这里不提供精简伪造的模型目录：完整目录包含工具与模型能力信息，应从官方文档获取。已使用脚本的读者，可用下面的内容检查配置结构。
以下是采用环境变量认证的参考片段。把顶层字段放在任何 [小节] 之前；已有同名字段应修改原值，不要重复追加。保留原来的 MCP 和其他小节。Windows 或自定义目录建议把模型目录改成实际绝对路径，Windows 路径可使用正斜杠。
model = "deepseek-flash"
model_provider = "deepseek"
forced_login_method = "api"
model_reasoning_effort = "high"
web_search = "disabled"
model_catalog_json = "~/.codex/models.json"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
requires_openai_auth = false认证方式参考 OpenAI 自定义 Provider 配置 和 字段参考。env_key 写的是环境变量名称，不是密钥本身。如果官方脚本已生成 experimental_bearer_token，采用上面的方案时删除该行，不要混用认证来源。
模型目录路径必须真实存在；示例不是“复制这一段就能省略模型目录”。接口根地址不要自行替换成 /chat/completions，也不要把完整 /responses 路径填写为根地址。Codex 会根据协议构造请求。
macOS 默认 zsh：以隐藏输入读取密钥，供当前终端启动的 CLI 使用。
read -r -s "DEEPSEEK_API_KEY?请输入 DeepSeek API Key（输入不回显）："
printf '\n'
export DEEPSEEK_API_KEY
# 只检查是否存在，不输出密钥
if [ -n "$DEEPSEEK_API_KEY" ]; then printf '密钥已载入当前终端\n'; fiLinux bash 的隐藏输入写法不同：
read -r -s -p "请输入 DeepSeek API Key（输入不回显）：" DEEPSEEK_API_KEY
printf '\n'
export DEEPSEEK_API_KEYWindows PowerShell：通过隐藏输入设置当前进程环境变量，随后在同一个窗口启动 CLI。转换过程会在内存中形成明文，隐藏输入不是加密存储。
$dsSecureKey = Read-Host '请输入 DeepSeek API Key' -AsSecureString
$dsCredential = New-Object System.Management.Automation.PSCredential('deepseek', $dsSecureKey)
$env:DEEPSEEK_API_KEY = $dsCredential.GetNetworkCredential().Password
if ($env:DEEPSEEK_API_KEY) { Write-Host '密钥已载入当前终端' }如果只使用 CLI，以上临时环境变量就够用。退出该终端后重新使用时，需要重新载入。不要把含真实密钥的 export ... 命令直接留在 shell 历史中。
步骤 5：让桌面客户端获得正确的环境
常见误区是：终端测试正常，但从 Dock 或开始菜单打开的应用找不到密钥。原因可能只是两者的环境不同；不要因此把密钥发给第三方排查。
macOS：在上一节已经隐藏输入密钥的终端内，可以把变量传给当前登录会话，再完全退出并重新打开应用。
launchctl setenv DEEPSEEK_API_KEY "$DEEPSEEK_API_KEY"
# 此后完全退出应用，再重新打开
# 不再需要时，可清除会话变量
# launchctl unsetenv DEEPSEEK_API_KEY这不是密码保险箱，也不是永久设置；其他进程可能读取会话环境。若团队有专门的凭据管理机制，应按团队方案处理。Windows / Linux 则先从已载入变量的终端启动相应客户端，或使用系统提供的环境配置机制；不应假定新应用会自动继承另一个终端的临时变量。
重新打开后创建一个新的本地会话，核对提供方和模型名称。如果模型没有出现在列表，优先检查模型目录、客户端版本、配置路径及组织策略，而不是在 MCP 页面重复添加 DeepSeek。
步骤 6：分层验证，不要把“能启动”当作成功
先在一个干净的测试目录启动 CLI，默认模型由刚才的配置决定：
codex第一轮只发送一个短问题，例如：“请用一句话说明二进制是什么，不要执行命令或修改文件。”检查能否收到完整回答；再到 DeepSeek 控制台核对本次 API 用量。模型自我介绍不是可靠证明，应该同时检查客户端所选模型、请求是否成功和计费账户记录。
第二轮再验证本地工具。下面的命令创建一个全新的临时目录，不接触真实项目：
ds_test_dir="$(mktemp -d -t codex-deepseek-check.XXXXXX)"
cd "$ds_test_dir"
codex给它一个范围明确的小任务：“只在当前目录创建 hello.txt，内容为 Hello DeepSeek；完成后读取文件并告诉我结果，不访问网络、不安装依赖、不修改其他目录。”查看它是否真的调用了工具，再人工检查文件。能回答问题与能完成补丁是两项不同测试。
第一次测试保留审批和沙箱，不要为了排错直接启用无约束执行。完整项目、私密仓库和生产操作应等小任务验证通过后再考虑。
如需进一步验证，再用一个可丢弃的小项目测试读取文件、修改一行代码和运行现有测试。每一步都检查实际差异，不接受“我已经完成”作为唯一证据。
步骤 7：遇到错误时，按层排查
模型没出现，或者仍然调用原来的模型
检查当前客户端是否读取了你编辑的目录；确认模型目录路径可用、JSON 没有截断、TOML 没有重复字段。重新启动后用新会话验证。远程主机、容器和本机通常拥有不同配置；修改本机文件不代表远端也改变了。
认证失败，或提示缺少环境变量
不要打印密钥。先确认环境变量非空，再检查应用是不是在设置变量之前已启动；核对提供方小节名称是否与顶层一致。若密钥被撤销或复制时包含空白，请在平台重新确认；不要反复尝试来源不明的 Key。
接口 404、协议不兼容或请求参数错误
优先核对接口根地址和 wire_api = "responses"。如果曾使用代理、旧 Provider 或启动参数覆盖地址，需要逐项检查，不能只看配置文件中的一个字段。参数错误时阅读完整错误说明，并与当前 DeepSeek Responses API 参考 对照；不要盲目增加旧配置字段。
请求过慢、中断或额度不足
先确认网络、账户额度与服务状态，再减少测试任务长度。不要用不断重试长任务的方式诊断问题；这可能增加用量。向服务商求助时提供时间、客户端版本和脱敏错误，不发送密钥、私密代码或完整提示内容。
回答正常，但某个工具无法执行
先区分提供方能力、客户端工具配置与沙箱权限。当前 Responses 接口支持函数调用，但不等于支持所有 OpenAI 内置工具；例如不能把原平台的内置联网能力默认视为可用。本例关闭内置 web search。客户端 MCP 暴露出的函数工具则属于另一条链路，要单独测试，不能一概认定 MCP 不可用。
步骤 8：恢复原配置，保持可回退
若用官方脚本安装，可重新运行同一个已检查的脚本，根据其恢复菜单操作。恢复后完全退出并重启相关客户端，用新的短会话确认原来的模型与工具设置。
手动修改的读者，应从第 2 步的备份中逐项恢复实际改变的字段和文件。恢复之前先保留现在的文件，以免丢失安装后新增的设置；不要删除整个 .codex 目录。如果原来没有模型目录，应先移走本次新建文件，而不是删掉所有配置。
如果不再使用 DeepSeek，清理专用环境变量，并按需要撤销平台上的专用 API Key。恢复模型并不会自动撤销密钥，两者需要分别处理。
常见问题 FAQ
现在还需要 LiteLLM 等中转网关吗？
本文核对的 DeepSeek 官方接口已经原生支持 Responses API，因此本教程采用直连。团队已有统一网关时可以另行评估，但不应把中转当作这里的必选前提。
这是给 Codex 添加 MCP 吗？
不是。模型 Provider 负责推理接口，MCP 负责工具和数据连接。修改提供方配置不会自动替你新增或重新授权 MCP。
为什么终端可用，桌面应用提示没有密钥？
桌面应用可能没有继承该终端的环境变量。需要检查应用启动环境，设置后完全退出重开，并确认配置目录一致。隐藏输入不代表环境变量或配置已经加密保存。
可不可以只复制 config.toml 片段？
不建议省略模型目录。请先按官方接入说明准备完整 models.json，再合并配置；不要覆盖已有 MCP、项目信任和自定义设置。
API 接通后，所有 Codex 功能都一样吗？
不能这样保证。基础回复、图片输入、函数调用、内置搜索和其他工具应分别验证；不同提供方、客户端版本和运行环境可能存在差异。
本教程是否已经用真实密钥跑通？
没有。本文核对了官方资料并检查了示例配置与文章格式，配图是示意图，不是付费 API 实测记录。实际接入仍应按文中的三层检查自行验收。
官方资料与更新说明
接口、模型名称和客户端设置会更新。遇到本文与当前官方页面不一致时，先确认资料日期与客户端版本，再按当前官方说明调整。不要套用未经核实的旧 Key、旧模型名或旧协议设置。
