在 Codex 里接入 DeepSeek：配置步骤与切换方法

Codex 默认只认自家模型。想用 DeepSeek 的 API，需要在配置里加一个 provider，并让 Codex 知道 DeepSeek 有哪些模型。

下面记录完整做法：怎么加、怎么切换、要注意什么。原有通道的配置不需要改动。

一、先确认三件事

API 地址。 DeepSeek 兼容 OpenAI 协议：

https://api.deepseek.com/v1

模型名。 会变，不要凭记忆写，查一次：

curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

返回里 data[].id 就是模型名。目前是 deepseek-flash 和 deepseek-v4-pro，都是 1M 上下文。旧名字 deepseek-chat、deepseek-reasoner 已不在列表里。

接口类型。 Codex 走 responses 协议，先确认目标服务支持：

curl -X POST https://api.deepseek.com/v1/responses \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-flash","input":"hi","max_output_tokens":20}'

返回 "object":"response" 就可以用 wire_api = "responses"。只支持 /v1/chat/completions 的话，改 wire_api = "chat"。

二、添加 provider

配置文件是 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml）。在原有 [model_providers.xxx] 段后面追加：

[model_providers.deepseek]
name = "DeepSeek"
wire_api = "responses"
requires_openai_auth = false
base_url = "https://api.deepseek.com/v1"
experimental_bearer_token = "sk-你的key"

• base_url：接口地址，带 /v1
• wire_api：协议类型，上面验证过是 responses
• requires_openai_auth：设 false，不走 OpenAI 账号认证
• experimental_bearer_token：内联 key

三、补一份模型目录

这一步不能跳过。Codex 的模型清单由 model_catalog_json 指向的 JSON 文件决定，目录里有什么，界面上才显示什么。原通道的目录里只有它自己的模型，必须另建一份，否则 Codex 不认识 deepseek-flash。

做法：复制现有目录，改这几个字段。

• slug：模型名，必须和 /v1/models 返回的一致
• context_window、max_context_window：1048576
• supported_reasoning_levels：只支持 low / high / max
• default_reasoning_level：建议 high
• input_modalities：deepseek-flash 为 ["text","image"]，v4-pro 只有 ["text"]

存为 ~/.codex/model-catalogs/deepseek-models.json。

四、切换要改四个键

只用一个通道，改完上面两步，把 model_provider 和 model_catalog_json 指过去就行。

两个通道来回切，必须同时改四个，少一个都会失败：

• model_provider：走哪条通道
• model：模型名，两边不通用
• model_reasoning_effort：档位要在目标模型的范围内（DeepSeek 没有 medium）
• model_catalog_json：换成对应那一份目录

PROFILES = {
    "relay": {
        "model_provider": "relay",
        "model": "gpt-6.x",
        "model_reasoning_effort": "medium",
        "model_catalog_json": "model-catalogs/relay-models.json",
    },
    "deepseek": {
        "model_provider": "deepseek",
        "model": "deepseek-flash",
        "model_reasoning_effort": "high",
        "model_catalog_json": "model-catalogs/deepseek-models.json",
    },
}

写盘前先校验，解析不过就中止：

import tomllib
tomllib.loads(new_text)     # 抛异常说明配置有问题，不要写盘
open(cfg, "w", encoding="utf-8", newline="\n").write(new_text)

newline="\n" 别省。Python 在 Windows 上默认写 CRLF，改一遍文件行尾全变，以后 diff 看不出改了什么。

五、操作步骤

1. 完全退出 Codex。 不是关窗口，是退出进程。

2. 运行切换脚本。

python switch-provider.py deepseek     # 切到 DeepSeek
python switch-provider.py relay        # 切回原通道
python switch-provider.py              # 查看当前通道

3. 启动 Codex。 读取新配置，加载对应模型目录。

4. 新建对话。 旧对话仍绑定切换前的模型，在旧对话里试会看到旧的报错。

六、注意事项

切换前必须退出应用。 Codex 运行时会把界面上选中的模型写回 config.toml。应用还开着就切换，它下一次写盘会覆盖你的改动。判断方法：对比文件修改时间和你的操作时间。

model_reasoning_effort 要和模型对齐。 不同模型支持的档位不同，超出范围请求会失败。

配置字段有归属。 http_headers 属于 MCP 服务器，experimental_bearer_token 才属于 model provider。写错位置不报错，只是不生效。

模型目录要跟着 provider 一起换。 只换 provider 不换目录，Codex 会把旧模型名发出去，服务端返回 400。

改配置前先备份。 复制一份 config.toml.bak，改坏了直接覆盖回去。

动已有文件时保持原行尾符。 用脚本改配置尤其注意，Windows 上很容易把 LF 写成 CRLF。

七、验证

codex doctor          # 看 model 和 provider 是否已切换、配置能否解析
codex debug models    # 看当前目录里有哪些模型被识别

doctor 重点看三行：model 应显示新模型名；config.toml parse 应为 ok；startup warning 若提示有未识别的配置项，说明字段名拼错了。

debug models 列出当前目录的全部模型。这里没有 DeepSeek 的模型，就说明 model_catalog_json 指错了文件。

两条通道各验一遍再投入使用。

小结

整套改动只有三处：config.toml 加一个 provider 段、加一份模型目录、加一个切换脚本。原通道的配置一行都不用动，随时可以切回去。

三个关键点：配置和模型目录必须配套、切换前退出应用、写盘前先校验再备份。