99% 的人以为“能在下拉框里选到 DeepSeek 模型”就算配置成功,其实那只是第一步。真正可靠的接入,还牵涉到客户端版本、权限边界、密钥存放位置,以及 Responses API 的一堆细节。稍不留神,一个配置文件就会同时影响 CLI、桌面端和 VS Code 扩展,连带把你的代码和密钥一起送出门。
据一位在团队里负责工具链的工程师反馈,他们在没备份 config.toml 的情况下直接跑脚本,结果整组人的 Codex 行为都变了,花了半天才恢复。这个坑完全可以提前避开。
本文先按 DeepSeek 官方文档还原“标准接入路径”,再给出一个更“护密”的 env_key 替代方案。中间会明确哪些行为已经有证据支撑,哪些仍然是“文档级”而非“实测级”。如果你打算在生产环境前先做一轮安全试跑,可以照着一步步来。
快速结论与当前模型目录
一句话版操作清单
遇到这种跨工具共享配置的场景,大多数人的第一反应是“先装上再说”,但更稳的顺序是:
- 先查 DeepSeek 在线 Codex 目录里的
minimal_client_version,确认你本地 Codex 版本不落后。 - 备份
~/.codex/config.toml,因为这个用户级文件会被 CLI、桌面端和 VS Code 扩展一起使用。 - 在“官方脚本/手动配置”和“env_key 安全方案”之间二选一,改完后再整体检查生效配置,不要混搭字段。
- 首次跑 DeepSeek 时,把本地权限收紧:
sandbox_mode = "read-only"、approval_policy = "on-request"。 - 发送首个请求前,确认“实际生效的模型 ID 和 provider”,而不是只看 UI 里有没有 DeepSeek 选项。
- 使用图片时,选
deepseek-v4-flash-vision-exp,并对你用的那一条 Codex 使用路径做端到端验证;Flash 和 Pro 仍是纯文本模型。
数据点:2026 年 8 月 20 日保留的目录对比中,Flash 和 Pro 的
minimal_client_version都是0.144.0,而本地codex-cli 0.148.0能正常启动。Vision 当时还没在这次检查里覆盖,所以现在要重新看在线models.json。
当前 DeepSeek 模型目录与版本要求
DeepSeek 当前托管目录中包含三个对 Codex 暴露的 API ID:
deepseek-v4-flash:V4-Flash-0731,Public Beta,文本模型。deepseek-v4-pro:V4-Pro-0813,GA,文本模型。deepseek-v4-flash-vision-exp:Experimental,Vision,多模态模型。
官方文档都以 Responses API 为主入口,只有 Vision 支持图像输入。那次保留的目录检查只确认了 Flash 和 Pro 的 minimal_client_version,并没有覆盖 Vision,所以现在选 Vision 前,需要重新查看在线 models.json 和你实际使用的 Codex 客户端版本。
这组数据只说明“客户端能启动 + 目录里有这俩模型”,并不自动证明认证、路由、工具行为、质量、延迟或计费都没问题。
四层边界:别把权限和路由混在一起
先看清这四个分层

很多人配置 Codex 时,会把“DeepSeek API 密钥”“ChatGPT 登录”“本地文件/命令权限”混成一团。其实 OpenAI 的配置参考已经给了一个很清晰的分层:
env_key:只负责告诉 Codex“去哪个环境变量里拿这个 provider 的 API key”。experimental_bearer_token:可以直接写 token,但官方已经明确标注为“不推荐”。wire_api:当前只支持responses,也就是 Codex 和自定义 provider 之间的协议层。- 本地权限:
sandbox_mode、approval_policy等,完全是宿主侧的控制,不由 DeepSeek 模型决定。
OpenAI 的配置参考里,
wire_api目前唯一支持值就是responses,这意味着任何“自定义 provider”想走 Codex 的官方路径,都得遵守 Responses 协议形状。
改配置前先做这几件事
在动 config.toml 之前,建议先把环境打扫干净:
- 至少启动过一次 Codex CLI 或 ChatGPT 桌面端,让
~/.codex目录先生成出来。 - 用
codex --version或 UI 信息确认当前版本不低于 DeepSeek 在线models.json里标的minimal_client_version。 - 备份
~/.codex/config.toml,并记下当时哪个客户端是打开状态。 - 首次联通 DeepSeek 时,用一个一次性仓库,里面不要放生产密钥、客户数据或任何敏感文件。
- 提前想清楚:这个仓库里的代码和对话内容,是否允许被发送到
https://api.deepseek.com。
OpenAI 文档说明:用户级配置在 ~/.codex/config.toml,项目级 .codex/config.toml 不能覆盖 model_provider 或 model_providers。也就是说,provider 和认证相关的设置应该放在用户级,而不是仓库里。
配置方案一:DeepSeek 官方一键脚本
脚本入口与平台命令
DeepSeek 在集成文档中把脚本标成“推荐路径”,当前官方命令是:
macOS 或 Linux
bash 供应链风险提示:在受控工作站上,更稳的做法是先下载脚本文件,校验内容和哈希,再执行本地那一份,而不是直接把网络响应管道进 shell。
### 官方脚本声称会做什么
DeepSeek 文档里对脚本行为的描述包括:
- 备份 `~/.codex/config.toml` 到 `~/.codex/backup-deepseek/`。
- 写入 `~/.codex/models.json`,并更新必要的配置字段。
- 保留与 provider 无关的设置,比如 MCP 服务器、项目信任级别等。
- 在写入前对配置和目录文件做校验。
- 支持切换模型或恢复安装前的配置。
这部分是厂商自述行为,本次文档更新并没有实际执行脚本做二次验证。我自己也不太确定脚本在不同平台、不同旧配置下的边界情况是否完全一致,所以如果你对环境敏感,建议先在隔离环境里试跑。
## 配置方案二:DeepSeek 官方手动配置
### 手动模式需要的文件与注意点
如果你不想直接跑脚本,DeepSeek 也提供了手动配置路径。第一步是从其 Codex 集成页面下载当前完整的 `~/.codex/models.json`:
- 不要从第三方文章里复制旧版目录文件。
- 这个文件里不仅有模型 ID,还有推理等级、工具格式、上下文信息和最小客户端版本等元数据。
> 有用户反馈,他们用了一份几周前的 `models.json`,结果 UI 里能看到模型,但请求一发就报错,最后发现是目录和服务端不匹配。
### 官方示例 config.toml 片段
DeepSeek 文档中的手动配置示例大致如下(密钥位置已用占位符替换):
```toml
model = "deepseek-v4-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = ""
凭证风险提示:这个官方示例把 API key 直接写进了
config.toml。OpenAI 的配置参考已经明确说experimental_bearer_token不推荐直接使用,并建议改用env_key。无论哪种方式,都不要把配置或目录文件提交到仓库,也不要把 key 出现在截图或工单里。
配置方案三:更“护密”的 env_key 变体
把密钥移出 config.toml
下面是基于官方脚本和手动示例改写的“安全优先”版本。它保留 DeepSeek 的模型目录和 Responses 路由,但把密钥从 config.toml 中挪到环境变量里,通过 OpenAI 文档里的 env_key 字段引用:
model = "deepseek-v4-flash"
model_provider = "deepseek"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"
approval_policy = "on-request"
sandbox_mode = "read-only"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
requires_openai_auth = false
这不是 DeepSeek 脚本实际写入的配置,本次更新也没有通过它发起真实模型请求。它的目的只有两个:
- 继续使用 DeepSeek 官方的 Responses 接入方式和模型目录。
- 避免在
config.toml里直接暴露明文密钥。
只在当前 shell 加载密钥
在 Windows PowerShell 中,可以用下面的方式把 key 读入当前进程树,而不在屏幕上回显:
$codexDeepSeekSecret = Read-Host "DeepSeek API key" -AsSecureString
$env:DEEPSEEK_API_KEY = [System.Net.NetworkCredential]::new("", $codexDeepSeekSecret).Password
Remove-Variable codexDeepSeekSecret
if ($env:DEEPSEEK_API_KEY) { "DEEPSEEK_API_KEY is set for this process" }
明文环境变量依然对当前进程及其子进程可见,所以:
- 团队长期使用时,建议接入合适的密钥管理服务,而不是靠个人 shell 变量。
- 一旦怀疑 key 暴露,立刻在 DeepSeek 控制台里旋转或吊销。
- 临时测试用的 key,跑完就撤销,不要长期遗留。
多客户端共享同一份配置
CLI、桌面端和 VS Code 的关系
DeepSeek 文档说明:Codex CLI、ChatGPT 桌面应用和 VS Code 的 Codex IDE 扩展,共享同一份用户级配置文件。换句话说:
- 你在
~/.codex/config.toml里改一次 provider,三端都会受影响。 - 改完配置后,需要完整重启对应客户端,才能看到新的 DeepSeek 模型选项。
- 某些平台上,桌面端模型选择器可能只显示“Custom”,而不是具体模型名。
这只是“配置被读取”的信号,不是“请求一定成功”的证据。要确认的话,还是得跑一轮小范围 handshake。
工具与权限仍需逐端验证
虽然三端共用配置文件,但它们的工具集和权限表面并不完全一致:
- 有的端支持更多本地命令或 MCP 连接,有的则更受限。
- Codex cloud 目前不在这套“本地自定义 provider”流程里。
- 真正要在某个端上长期跑 DeepSeek,还是要对那一端做单独的工具和权限检查。
首次接入时的权限建议
approval_policy 与 sandbox_mode 的组合
OpenAI 文档目前列出的选项包括:
approval_policy:untrusted、on-request、never等。sandbox_mode:read-only、workspace-write、danger-full-access。
这些都是宿主侧的控制开关,DeepSeek 模型本身不会自动放大或缩小这些权限。更稳的做法是:
- 初次验证认证和路由时,把
sandbox_mode设为read-only。 - 用
on-request让任何写操作都先弹出审批边界,方便你观察行为。 - 只有在任务确实需要改动仓库时,再考虑切到
workspace-write。 - 不要在第一次测试 provider 时就用
danger-full-access或never。 - MCP 服务器、插件、浏览器访问、网络访问等能力,需要单独审查,provider 配置块不会自动关掉它们。
一位朋友在
danger-full-access下测试新 provider,结果模型直接改了他本地的构建脚本,虽然问题不大,但排查起来非常费时间。
已有证据与尚未验证的部分
已经做过、但边界有限的检查
有一组单独授权的“桥接运行”记录值得一提:
- Flash 和 Pro 各有一条 case artifact,状态是
PASS / HANDSHAKE_PASS。 - 整体运行并未成功结束,最终记录为
BLOCKED_STOPPED,主错误码INVALID_JSON,在两次上游请求事件之后停止。 - 记录中还有
INDETERMINATE_UPSTREAM_MAY_HAVE_STARTED,说明上游是否真正开始处理并不确定。
这组桥接测试:
- 使用的是锁定的最小重建请求路径,而不是直接的
env_key配置。 - 不是“原样转发”路径,且没有覆盖文件、命令、补丁、审批、恢复、质量、延迟、成本、可靠性等维度。
换句话说,它只能证明“在特定条件下,最小请求路径曾经跑通过”,不能被当成“完整 Codex–DeepSeek 直连配置已验证”的证据。
还需要补完的验证矩阵
如果你打算严肃地验证 env_key 方案,可以按下面的矩阵来跑:

- 把“直接 env_key 配置矩阵”和“桥接测试结果”严格分开,不要混用结论。
- 在这轮矩阵中,只使用上文标注清楚的
env_key变体,不执行 DeepSeek 脚本,也不在 TOML 里写明文 token。 - 对 Flash:每个用例都用全新的客户端 home、进程和测试夹具,
sandbox_mode = "read-only",approval_policy = "on-request"。 - 跑完以下六类用例:缺失 key 的拒绝、精确文本 handshake、只读文件检查、被拒绝的写入审批、确定性的本地测试命令、预期命令失败后的恢复。
- 对 Pro 重复同样的六个用例,同样使用全新 home、进程和夹具。
- 为每个用例单独记录:路由、请求、原生事件、用量值、错误、重试、清理结果和事后阻塞点,不要把 Flash 和 Pro 的结果混在一起。
- 在单独授权的清理步骤中取消设置并吊销临时 key,确认正常 Codex 配置没有被覆盖。
这些用例的提示词、通过标准、版本、配置哈希和停止条件,都应该在第一次跑模型前就冻结下来。现有的两条桥接 case 只能证明它们自己的最小路径,不涉及直连配置、文件访问、命令执行、审批、补丁或恢复。
Flash 和 Pro:该选哪个?
现有证据能告诉你的,和不能告诉你的
目前保留的桥接证据里:
deepseek-v4-flash和deepseek-v4-pro各有一条 case,artifact 状态都是 PASS。- 但运行级别记录仍然是 BLOCKED,说明流程在本地收尾阶段就停住了。
官方目录把两者都描述为“面向智能编码的代理型模型”,不过:
- 本指南没有对它们的相对质量、延迟、成本或可靠性做过实测对比。
- 任何未来的付费运行前,都应该重新确认当前可用性和价格。
延伸阅读与更细粒度建议
如果你想要更偏“工作流设计”的建议,可以参考:
- DeepSeek 编码工作流指南:
https://chat-deep.ai/guide/deepseek-for-coding/ - VS Code 专用配置指南:
https://chat-deep.ai/guide/deepseek-v4-vscode/ - Responses API 兼容性审计:
https://chat-deep.ai/research/deepseek-responses-api-compatibility-audit/
这些内容会比本文更关注“怎么用好模型”,而不是“怎么把线接对”。
Responses API 在 Codex 里的关键限制
Vision 输入的三种形态
DeepSeek 文档中,deepseek-v4-flash-vision-exp 在 Responses API 下支持三种图像输入形态:
// 公共图片 URL
{
"model": "deepseek-v4-flash-vision-exp",
"input": [{
"role": "user",
"content": [
{"type": "input_text", "text": "Describe this image."},
{"type": "input_image", "image_url": "https://example.com/image.png"}
]
}]
}
// Base64 data URL
{"type": "input_image", "image_url": "data:image/png;base64,iVBORw0KGgo..."}
// 通过 DeepSeek Files API 预先上传的图片
{"type": "input_image", "file_id": "file-api-..."}
这些只是 provider 侧的 API 形状说明,并不能自动推导出“某个 Codex UI、剪贴板流程或本地附件功能”一定会按同样方式序列化请求。要确认的话,还是得做端到端测试。
Files API 与 input_file 的边界

关于文件输入,有几个容易踩坑的点:
file_id只对“通过 DeepSeek Files API 上传的受支持图片”有效。- 通用的 Responses
input_file部件目前不在支持范围内。 - Files API 不会把 PDF、Office 文档或任意文件自动转成可用的模型输入。
层次区分很关键:
- DeepSeek 文档描述的是“请求到达 Responses 端点”之后的行为。
- Codex 在模型外面还包了一层本地文件、命令、审批、沙箱、MCP 等工具。
- 某个 API 工具类型被忽略,并不能证明宿主里同名的能力就不存在。
常见配置故障与排查思路
模型缺失或被拒绝
遇到模型选不到、或一选就报错,可以按下面顺序排查:
- 对比本地 Codex 版本和 DeepSeek 当前目录里的
minimal_client_version。 - 确认
model_catalog_json指向的是最新的~/.codex/models.json。 - 在重启客户端前,用 JSON/TOML 校验工具检查文件格式是否有效。
- 确认模型 ID 精确为
deepseek-v4-flash、deepseek-v4-pro或deepseek-v4-flash-vision-exp。Vision 是 Experimental,要先确认 Codex 目录里真的暴露了它。 - 改完共享配置后,完整重启 CLI、桌面端或 IDE 扩展。
401 或认证失败
如果你采用的是 env_key 方案,401 大多和环境变量或字段拼写有关:
- 确认
DEEPSEEK_API_KEY在启动 Codex 的同一进程树中存在。 - 确认
env_key填的是“环境变量名”,而不是直接把密钥写进去。 - 自定义 provider 场景下,把
requires_openai_auth设为false。 - 如果用的是 DeepSeek 手动示例里的明文 token,检查是否多了空格或换行,一旦怀疑泄露就旋转 key。
- 不要在日志或截图中打印环境变量或原始认证头。
桌面端只显示“Custom”
DeepSeek 提到:ChatGPT 桌面端的模型选择器在某些平台上,会在启用自定义 DeepSeek provider 时显示“Custom”。
- 把这个标签当成“当前使用的是自定义 provider”的提示。
- 不要把它当成“请求一定已经成功发到 DeepSeek”的证明。
- 仍然需要通过一次小范围 handshake 来确认实际路由和模型。
之前的会话好像“消失了”
有用户会在切换 provider 后发现“历史会话不见了”,DeepSeek 的说法是:
- Codex 会按“登录方式”把会话分组。
- 用 ChatGPT 订阅创建的会话,和用第三方 API 创建的会话,可能显示在不同分组里。
- 恢复之前的配置并重启客户端,通常就能看到另一组会话。
这意味着:
- 切换 provider 只是切换了“可见会话组”,并不等于会话被删除。
隐私与收尾清理清单
路由与数据范围的心理预期
在把 DeepSeek 接入 Codex 之前,先把这几件事想清楚:
- 任何通过
https://api.deepseek.com路由的提示词和代码,都会受 DeepSeek 自己的隐私政策约束,而不是你的 ChatGPT 工作区策略。 - 首次测试时,不要把生产密钥、客户记录、私钥或受监管数据放进仓库或对话。
- 本地沙箱和审批设置要和 provider 兼容性分开看,别因为“路由通了”就放松权限。
测试结束后的清理动作
做完一轮测试后,可以按下面顺序收尾:
- 只保留脱敏后的证据,去掉用户名、本地路径、token、账号 ID 和请求头。
- 退出 Codex 客户端,从当前 shell 中移除
DEEPSEEK_API_KEY,并在 DeepSeek 控制台吊销临时 key。 - 用之前的备份恢复你真正想长期使用的配置。
- 重启所有共享这份配置的本地客户端,确认 provider 和会话分组都恢复正常。
# PowerShell,仅当前进程
Remove-Item Env:DEEPSEEK_API_KEY -ErrorAction SilentlyContinue
# macOS 或 Linux,仅当前 shell
unset DEEPSEEK_API_KEY
更多关于 DeepSeek API 的通用说明,可以看:https://chat-deep.ai/docs/api/;其他客户端的接入方式,可以查 https://chat-deep.ai/integrations/。这些内容不会替代本文里对 Codex provider 和权限边界的拆解,但能帮你从更高一层理解整个生态。
这些官方文档最近一次统一复核是在 2026 年 8 月 22 日。Codex CLI 启动检查和 Flash/Pro 桥接证据停留在 8 月 20–21 日,Vision 没有在那次检查中重跑。期间没有做任何“已认证的 Codex→DeepSeek 请求”,模型 ID、目录元数据、客户端要求、价格、脚本和兼容性都可能继续变化。
常见问题
Q:Codex 能在不登录 ChatGPT 的情况下直接用 DeepSeek 吗?
A:可以,本地 Codex 客户端支持用 DeepSeek 的 API key 直接认证,而不依赖 ChatGPT 账号登录。原因是 Codex 在配置里允许为自定义 provider 设置 requires_openai_auth = false,再通过 env_key 指向专用环境变量即可。实操时,建议在启动 Codex 的同一 shell 中临时设置 DEEPSEEK_API_KEY,测试完后用 unset 或 Remove-Item 清理,并在 DeepSeek 控制台旋转或吊销测试用 key,避免长期遗留。
Q:当前 DeepSeek 目录要求的 Codex 最低版本是多少?
A:已有的 2026 年 8 月 20 日检查记录显示,Flash 和 Pro 的 minimal_client_version 为 0.144.0,而 codex-cli 0.148.0 能正常启动。这组数据是在 Vision Exp 发布前记录的,并不能推断 Vision 的最低版本要求。更稳的做法是,每次配置前都重新下载最新的 DeepSeek models.json,逐条查看三个模型的 minimal_client_version,再对照你本地 CLI 或桌面端的实际版本号,必要时先升级 Codex 再接入 DeepSeek。
Q:DeepSeek 的一键脚本具体会改哪些东西?
A:DeepSeek 文档称脚本会备份现有 config.toml,写入或更新 models.json,只修改 provider 所需字段并保留其他设置,同时对两个文件做格式校验,并提供模型切换和配置恢复功能。原因在于脚本需要在不破坏你现有 MCP、项目信任级别等设置的前提下,插入 DeepSeek 相关配置。实操建议是在隔离环境或备份充分的前提下先试跑一次,并在运行前后对比 config.toml 和 models.json 的差异,确认没有意外改动关键字段。
Q:DeepSeek 的 API key 最好放在哪里?
A:从安全角度看,不建议把 key 直接写进 config.toml 的 experimental_bearer_token 字段。OpenAI 文档已经把这种直写方式标为不推荐,并给出了 env_key 作为替代,用来指向一个环境变量名。更好的做法是:在用户级配置中只写 env_key = "DEEPSEEK_API_KEY",实际的 key 通过环境变量或团队级密钥管理服务注入。这样一来,即便配置文件被误传或误提交,也不会直接暴露密钥本身,后续轮换和吊销也更方便。
Q:CLI、桌面端和 VS Code 扩展会共享这套 DeepSeek 配置吗?
A:会的,根据 DeepSeek 当前的集成文档,这三种本地客户端都会读取同一份 Codex 用户级配置文件。原因是 Codex 把 provider 和模型目录视为“用户环境级”设置,而不是单一应用的私有配置。实操时,每次切换 provider 或更新 models.json 后,都要分别重启 CLI、桌面端和 VS Code 扩展,并在每个端上单独测试工具和权限表面,确认没有出现某个端工具更多、权限更大的“意外差异”。
Q:为什么 wire_api 必须是 responses?
A:因为 OpenAI 当前的 Codex 配置参考里,只把 responses 列为支持的 wire_api 值,而 DeepSeek 也在文档中明确声明对 Responses API 的原生支持。原因在于 Codex 和自定义 provider 之间需要一个统一的协议层,Responses 就是这个约定。实操上,你需要确保 DeepSeek 侧的 Responses 合约(包括 Vision 的图像输入形态)和 Codex 生成的请求结构一致,同时记住:即便 Vision 支持图片,通用的 input_file 文档输入仍然不在支持范围内。
Q:切换 provider 会改变 Codex 的本地权限吗?
A:不会。provider 路由和本地权限是两套完全不同的控制面板。sandbox_mode、approval_policy、工作区范围、网络访问、MCP 服务器、插件和其他连接器,都需要单独审查和配置。原因是 Codex 把“能不能访问本地文件/命令”视为宿主责任,而不是交给模型或 provider 决定。实操建议是在每次接入新 provider 时,重新过一遍本地权限清单,避免因为“换了模型”而误以为权限也自动收紧或放宽。
Q:为什么我切换到 DeepSeek 后,之前的会话好像都不见了?
A:这通常是因为 Codex 会按“登录方式”对会话做分组展示。用 ChatGPT 订阅创建的会话和用第三方 API key 创建的会话,会被放在不同的分组里。切换 provider 后,你看到的是另一组会话,而不是原来的那组被删除。解决办法是:恢复之前的配置(例如改回 OpenAI provider),重启客户端,就能重新看到旧会话分组。实操上,建议在切换前记下关键会话的标记或导出方式,避免在 UI 分组切换时产生“数据丢失”的错觉。
结尾:把这套检查表留在手边
DeepSeek 和 Codex 的组合,真正棘手的地方不在“能不能跑起来”,而在“跑起来之后,你到底给了它多大权力、暴露了多少东西”。这里的版本要求、env_key 方案、权限组合和验证矩阵,都是反复踩坑后才沉淀下来的判断标准。下次你或同事要在新机器上接入 DeepSeek 时,把这篇当成 checklist 翻一遍,往往比临时去问人靠谱得多。
如果你现在正准备在团队环境里做第一次 DeepSeek 接入,这些步骤可以帮你少走几圈弯路;而当你哪天忘了某个细节,只要还记得这篇放在哪,就还有机会把风险拉回来一点。

