Codex CLI(OpenAI 的终端编程智能体)在 2026 年的新版本中,自定义模型提供商只支持 OpenAI Responses 协议(wire_api = "responses"),而 DeepSeek 官方端点仅提供 Chat Completions,所以网上大量"Codex 直连 DeepSeek"的旧教程现在会直接打空。国内可直连且支持 Responses 的路径主要有腾讯云 TokenHub、阿里云百炼、MiniMax、火山方舟四条,另有用 Codex 0.80 老版本走 Chat 协议的兜底方案。本文给出逐条可复制的配置与避坑说明。 codex 国内 api 配置前先弄清协议与版本
Codex CLI 通过 config.toml 里的 wire_api 字段决定用哪种协议跟你的 API 服务对话。这是 2026 年配置翻车的头号原因:
- 新版 Codex(主流版本)只认 responses:官方配置文档明确 wire_api 唯一支持值是 "responses"(缺省即此值),你在老教程里看到的 wire_api = "chat" 已失效。后果是:目标端点如果只实现了 Chat Completions,Codex 发过去的 Responses 请求会打中一个不存在的路由,症状是会话刚开始就 404、"unknown endpoint" 或空流——但同一个端点你用 curl 测 /chat/completions 却完全正常。主机没挂,是协议不对。
- 旧版 Codex 0.80.0 及更早支持 chat:腾讯云官方文档在说明其 Token Plan(仅兼容 Chat 协议)时,明确要求安装 @openai/codex@0.80.0 或更老版本才能配合使用。所以"老 Codex + Chat 协议"是一条真实存在的路,只适用于非 Responses 端点。
- 确认自己的版本:codex --version 可查看当前版本;安装用 npm install -g @openai/codex(国内网络可配合 npmmirror 镜像源加速)。
另一个前置:Codex 依赖工具调用(tool calling)能力来完成"读代码、改文件、跑命令"的智能体闭环,本地小模型通常不具备,所以本文的方案都限定在支持函数调用的云端模型范围内。
codex 配置文件怎么写:位置、层级与三个必填参数
Codex 的配置读取有层级,优先级从高到低:命令行 -c 参数 > 配置文件(--profile 指定)> 项目级 .codex/config.toml > 用户级 ~/.codex/config.toml。其中有一条安全边界:项目级配置不能覆盖 provider、鉴权等设置——你 clone 一个仓库不可能把请求和 Key 悄悄导向第三方端点。所以自定义提供商必须写在用户级文件里:
- macOS / Linux:~/.codex/config.toml
- Windows:C:\Users\<你的用户名>\.codex\config.toml
自定义提供商由三件套组成,其余都是可选项:
关键规则:model_provider 的值要与 [model_providers.xxx] 的表名逐字一致;env_key 指向的环境变量名可以自己起,但必须在调用 Codex 前注入;Key 通过 Authorization: Bearer 头发送。若不想走 ChatGPT 登录,可加 preferred_auth_method = "apikey" 与 requires_openai_auth = false。
codex 直连腾讯云 TokenHub 的配置示例
腾讯云 TokenHub 是聚合混元、DeepSeek、GLM、Kimi、MiniMax、Qwen 等模型的统一 API 平台,大陆端点 https://tokenhub.tencentmaas.com/v1 可直连,且官方提供了 Codex 接入文档(Hy3 模型 + Responses 协议),是最省事的方案: 接入步骤:先在腾讯云控制台创建 API Key(若设了"限定范围"需勾选 Hy3 等目标模型),并把模型服务开通——未开通的模型调用会返回 402 类错误;然后把 Key 注入环境变量(macOS 可用 launchctl setenv HY3_API_KEY "...",Windows 用 setx HY3_API_KEY "...");最后完全退出 Codex 再重启(仅关闭窗口不生效),官方说明重新启动后才会读取新 Key 与配置。
TokenHub 的协议覆盖并非所有模型一致:据腾讯云官方文档,Hy3、MiniMax-M3、Qwen3.5 等原生支持 Responses,DeepSeek-V4、GLM-5.x、Kimi K3 等通过平台"兼容模式"支持(功能有部分限制)。模型名一律用平台标识(如 hy3、minimax-m3、deepseek-v4-pro),不要填厂商原生名。
直连 MiniMax、百炼、方舟的端点与价格对照
不想绑腾讯云的,下面三家也原生支持 Responses 协议、国内可直连(端点与模型经 2026 年 9 月核查):
| | | |
|---|
| https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3.5-plus / qwen3.7-plus 等 | 约 2 / 8(据第三方 2026 年 6 月整理,以官网为准) |
| https://api.minimaxi.com/v1(内地) | | 2.1 / 8.4(M3 输入 512k 以内档,官方按量页 2026-09 核查) |
| https://ark.cn-beijing.volces.com/api/v3 | | |
| https://api.deepseek.com(仅 Chat) | | |
以 MiniMax 为例,config.toml 的写法和腾讯方案同构——把 base_url 换成 https://api.minimaxi.com/v1、env_key 换成自己定义的变量、model 填 MiniMax-M3、保持 wire_api = "responses" 即可。需要提醒的是:MiniMax 要求手机号注册 + 实名认证;阿里云百炼按平台文档其 Responses 兼容端点的服务端状态保留期为 7 天;各平台新用户通常有免费体验额度(百炼宣传每模型有 100 万免费 tokens,TokenHub 官方同样宣传每模型 100 万免费 tokens),具体以控制台开通页为准。
DeepSeek 官方 API 接 codex 的两个姿势
先泼冷水:截至 2026 年 9 月核查,DeepSeek 官方文档只提供 OpenAI 兼容的 /chat/completions 与 Anthropic 兼容路径,没有 Responses(/responses)端点,因此新版 Codex 无法直连 DeepSeek 官方 API——那些 base_url = "https://api.deepseek.com/v1" + wire_api = "responses" 的教程,要么过时、要么缺了中间的转换层。
仍想用 DeepSeek 模型,有两条路:
- 姿势一:装老版本 Codex 走 Chat 协议。安装 @openai/codex@0.80.0,把 wire_api 设为 "chat"、base_url 指向 https://api.deepseek.com、模型填 deepseek-v4-pro。这是腾讯云官方在 Token Plan 兼容说明里亲自示范过的用法,适合"手里只有 DeepSeek Key、不想再开新平台"的场景;代价是用不了新版 Codex 的功能演进。
- 姿势二:经聚合平台调 DeepSeek 模型。腾讯云 TokenHub、百度千帆等平台对 DeepSeek-V4 提供 Responses 兼容模式,Codex 直连平台端点即可,等于把协议转换交给平台做。这也是推荐姿势——模型没变,但能用新版 Codex。
codex 国内 api 配置常见报错排查
| | |
|---|
会话开始即 404 / unknown endpoint / 空流 | 端点只支持 Chat,不支持 Responses(协议不匹配) | 换支持 Responses 的平台模型,或装 Codex 0.80 老版本改用 wire_api=chat |
401 unauthorized / invalid api key | env_key 环境变量没注入或键名不符;Key 与区域不匹配 | 检查环境变量是否生效(新开终端再试);TokenHub 广州/新加坡 Key 不互通 |
| | 登录控制台开通模型(如 TokenHub 的 hy3)并充值 |
| | 按 Retry-After 指数退避重试,或升级套餐 |
| | 对照平台文档填写(hy3 / minimax-m3 / deepseek-v4-pro 等) |
| Codex 未完全退出,或改到了项目级 config | 彻底退出重启;provider 定义必须写在 ~/.codex/config.toml |
| | 选带 function calling 的模型;可加 model_context_window 与 model_auto_compact_token_limit 调优 |
codex 国内配置的注意事项
- 先核对 Codex 版本再抄配置:新版与 0.80 老版的 wire_api 取值相反,网上教程鱼龙混杂,抄之前先 codex --version。
- Key 只放服务端环境变量:env_key 指向的变量不要在 config.toml 里写明文(曾有 experimental_bearer_token 这类内联字段,官方不推荐);Key 泄露可随时在控制台吊销重建。
- 聚合平台的协议兼容是"兼容模式"不等于全功能:TokenHub 对部分模型标的是 Responses 兼容模式,个别参数与内置工具受限;跑复杂 agent 任务优先选原生支持(hy3、MiniMax-M3、Qwen3.5 等)。
- 免费额度有门槛:各家宣传的"每模型 100 万免费 tokens"通常要求先开通模型服务、且与实名/新用户资格绑定,别把生产预算建立在免费额度上。
- 实名与合规:内地平台普遍要求实名;涉及企业代码库与敏感数据时,评估数据出境与供应商合规要求后再决定用哪家。
codex 国内 api 配置常见问题
Q:为什么照着网上的教程配 DeepSeek 一直报错?
A:大概率是协议不匹配——新版 Codex 只走 Responses API,而 DeepSeek 官方端点只提供 Chat Completions。要么装 0.80 老版 Codex 用 wire_api=chat,要么改走 TokenHub、千帆等提供 Responses 兼容模式的平台。
Q:Codex 装哪个版本合适?
A:想用最新功能就保持新版(responses 协议);必须直连只有 Chat 端点的服务(如 DeepSeek 官方)时,装 @openai/codex@0.80.0。
Q:config.toml 应该改哪个文件?
A:用户级 ~/.codex/config.toml(Windows 为 C:\Users\用户名\.codex\config.toml)。项目级 .codex/config.toml 出于安全设计不能覆盖 provider 配置。
Q:model_provider 和 [model_providers.xxx] 对不上会怎样?
A:Codex 会报找不到提供商配置。两者必须逐字一致,包括大小写。
Q:用国内平台要 ChatGPT 登录吗?
A:不需要。配置里加 preferred_auth_method = "apikey" 和 requires_openai_auth = false,全程走 API Key 鉴权。
Q:改完配置还是老模型/老行为?
A:Codex 只在完全退出后重新启动时才重新加载配置与 Key——"仅关闭窗口无效"是腾讯云官方文档原话,进程要彻底退出。
Q:哪家平台的模型最适合跑 Codex 的 agent 任务?
A:优先选 Responses 原生支持且工具调用稳定的模型:腾讯云 TokenHub 的 Hy3、MiniMax-M3、通义 Qwen3.5 系;同时按平台文档设置好上下文窗口参数,避免长任务中途截断。
Q:DeepSeek 价格便宜,能不能省着用?
A:能。走 TokenHub 等平台的 deepseek-v4-pro(输入 3 元、输出 6 元/百万 token 官方刊例)即可,等于用便宜模型驱动新版 Codex,但要注意兼容模式下部分 Responses 特性受限。
Q:TokenHub 的广州端点和新加坡端点有什么区别?
A:广州 https://tokenhub.tencentmaas.com/v1 面向大陆、新加坡端点面向海外,API Key 相互独立不通用,选错会报 401 类错误。国内网络环境用广州端点。
Q:这些配置会过时吗?
A:会。Codex 的 wire_api 策略、各平台协议支持与价格都在快速变化(2025 年还能用的 chat 配置 2026 年就废了)。以 OpenAI Codex 官方配置文档和各平台文档的最新版为准。
Codex 版本策略、各平台端点与价格可能随时调整,请以 OpenAI Codex 官方文档及各平台最新公告为准。