Codex 接中转站 / 第三方 API 配置教程（2026）：config.toml 写法、接 DeepSeek、桌面版与插件、常见报错

model = "gpt-6.1-sol"
model_provider = "relay"

[model_providers.relay]
name = "我的中转站"
base_url = "https://中转站地址/v1"
env_key = "RELAY_API_KEY"

再把密钥设成环境变量 RELAY_API_KEY，重新运行 codex 就能用。最常见的三个坑：中转站只支持 Chat Completions、不支持 Codex 要的 Responses 接口；base_url 少了 /v1；model 写在了 [model_providers.relay] 下面，被悄悄忽略。

下面每一步都在 2026 年 10 月 17 日用最新的 Codex CLI 0.163.0 实测过：我们在本机搭了一个模拟中转站，把 Codex 实际发出的地址、请求头和请求内容抓了下来；报错原文来自真实服务的返回。还没装 Codex 的，先看 Codex 安装与使用教程。

先确认：中转站必须支持 Responses 接口

这是 Codex 和 Claude Code、Cherry Studio 这类软件最大的不同。Codex 只会用 OpenAI 的 Responses 接口（/v1/responses）发请求：

• 以前可以写 wire_api = "chat" 走 Chat Completions，新版已经不支持，写了会直接报错（见文末报错）。
• 官方的网关兼容说明写得很明确：服务商必须接受 POST /v1/responses，完整地、边生成边转发流式事件，包括最后的 response.completed；还要支持多轮对话和工具调用的来回。Chat Completions 或 Claude 接口能用，不代表 Responses 能用。

所以选服务商时先问一句：「支持 Codex 吗？支持 Responses 接口吗？」只写「兼容 OpenAI」的不一定行。很多人遇到的「能连上但用不了」「聊一句就断」，根源都在这里。

api.foo 支持 Responses 接口，Codex 的地址填 https://api.foo/v1。

三种写法，选一种

三种写法都只改用户目录里的配置。项目文件夹里的 .codex/config.toml 改不了服务商：官方规定 model_provider、model_providers、openai_base_url 写在项目配置里会被忽略。

写法 A：自定义服务商 + 环境变量

第一步，编辑 ~/.codex/config.toml。以 api.foo 为例：

model = "gpt-6.1-sol"
model_provider = "apifoo"

[model_providers.apifoo]
name = "api.foo"
base_url = "https://api.foo/v1"
env_key = "APIFOO_API_KEY"

• model_provider = "apifoo"：用哪个服务商，要和下面 [model_providers.apifoo] 的名字一致。名字自己起，用英文，不能叫 openai、ollama、lmstudio（这三个是内置的，不能覆盖）。
• base_url：服务商地址，要带 /v1（原因见下文）。
• env_key：密钥放在哪个环境变量里。

第二步，设置环境变量。Mac（zsh）：

echo 'export APIFOO_API_KEY="sk-你的密钥"' >> ~/.zshrc && source ~/.zshrc

Linux（bash）把 ~/.zshrc 换成 ~/.bashrc。Windows PowerShell 运行下面这行，然后关掉终端重新打开：

setx APIFOO_API_KEY "sk-你的密钥"

第三步，运行 codex。启动信息里能看到 model: gpt-6.1-sol 和 provider: apifoo，就说明配置生效了。

写法 B：密钥直接写进配置文件

把写法 A 里的 env_key 换成 experimental_bearer_token：

model = "gpt-6.1-sol"
model_provider = "apifoo"

[model_providers.apifoo]
name = "api.foo"
base_url = "https://api.foo/v1"
experimental_bearer_token = "sk-你的密钥"

我们实测，这样不设任何环境变量，请求也会带上 Authorization: Bearer 密钥。好处是桌面版、VS Code 插件这些不从终端启动的程序也能读到。

代价是密钥明文写在文件里，官方配置说明里也标注了「不推荐，建议用 env_key」。用这种写法就别把 config.toml 发给别人、传到网上，也别放进 Git 仓库。

写法 C：改内置 OpenAI 的地址 + API Key 登录

不定义新服务商，直接把内置 OpenAI 的地址改掉：

model = "gpt-6.1-sol"
openai_base_url = "https://api.foo/v1"

然后把密钥「登录」进去（Mac / Linux）：

printf 'sk-你的密钥' | codex login --with-api-key

Windows PowerShell：

"sk-你的密钥" | codex login --with-api-key

看到 Successfully logged in 就好了，密钥保存在 ~/.codex/auth.json。缺点是和 ChatGPT 订阅登录互相顶替，来回切换要重新登录。经常切换的用写法 A 加 profile，或者用 CC Switch。

地址为什么必须带 /v1

我们抓到的请求显示，Codex 直接在 base_url 后面拼上 /responses：

所以 Codex 的地址要带 /v1，Claude Code 的地址不带 /v1，两者正好相反，同时用两个工具的人最容易填混。

Codex 实际发出了什么请求

用写法 A 运行 codex exec "say hi"，模拟中转站收到的请求是这样的（密钥已打码）：

POST /v1/responses
Authorization: Bearer sk-…
user-agent: codex_exec/0.163.0 (Mac OS 27.2.0; arm64) …
另有 session-id、thread-id、x-codex-turn-metadata 等 Codex 自己的请求头

请求内容（节选）：
  "model": "gpt-6.1-sol",
  "stream": true,
  "store": false,
  "include": ["reasoning.encrypted_content"],
  "reasoning": {"effort": "low", "context": "all_turns"},
  "text": {"verbosity": "low"},
  "prompt_cache_key": "…",
  "parallel_tool_calls": false

这对排查问题很有用：

• 服务商报 400，说不认识某个参数（比如 store、include、reasoning.context、text.verbosity），说明它对 Responses 接口的支持没跟上新版 Codex，只能等服务商更新或者换一家。用户这边改不了 Codex 发出的字段。
• 自定义服务商不会先尝试 WebSocket，我们没抓到任何升级连接的请求；codex exec 也不会先请求模型列表。所以服务商只要把 /v1/responses 做好就行。
• prompt_cache_key 是给服务商做缓存用的。服务商支持的话，长对话里重复的部分会按缓存价计费；具体看服务商的使用记录里有没有「缓存读取」。

模型名怎么填

model 填服务商模型列表里的名字，一字不差。Codex 自己认识一批 OpenAI 模型名（比如官方推荐的 gpt-6.1-sol、gpt-6-luna），用这些名字时，上下文长度、推理档位等信息 Codex 都知道。

用 Codex 不认识的名字也能发请求，但启动时会提示：

warning: Model metadata for `my-model` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.

意思是它不知道这个模型的能力，只能按默认值猜，可能用得不顺（比如上下文长度估错）。要消除这个提示，得像 DeepSeek 官方那样提供一份模型说明文件（model_catalog_json），见下一节。

api.foo 上能给 Codex 用的 GPT 模型有 gpt-6.1-sol、gpt-6-sol、gpt-6-astra、gpt-5.6-sol、gpt-5.6-terra，都是 Codex 认识的名字，直接填就行。每个模型的价格见模型广场。

其他常用的模型设置，写在文件最前面：

model_reasoning_effort = "medium"   # 推理强度：low / medium / high 等，越高越慢越贵
review_model = "gpt-6.1-sol"        # /review 代码审查用的模型，不写就用默认

Codex 接 DeepSeek（官方 API）

搜「codex 接入 deepseek」的人很多，这里单独说。DeepSeek 官方 API 原生支持 Responses 接口，可以直接接，不需要中转。DeepSeek 文档给了两种方法：

方法一：官方一键脚本（运行前先装好 Codex 并至少启动过一次）。Mac / Linux：

bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)

Windows PowerShell：

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

按菜单选：1 用 deepseek-flash（支持图片输入），2 用 deepseek-v4-pro，9 恢复原来的配置。脚本会先把 config.toml 备份到 ~/.codex/backup-deepseek/，再写入模型说明文件 ~/.codex/models.json 和服务商配置。

方法二：手动配置。先按 DeepSeek 文档把 models.json 的内容保存到 ~/.codex/models.json（内容很长，直接从官方页面复制）。然后在 config.toml 里写：

model = "deepseek-flash"
model_provider = "deepseek"
model_reasoning_effort = "high"
web_search = "disabled"
model_catalog_json = "/Users/你的用户名/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

和 DeepSeek 官方示例相比，这里有三处小改动：

• 密钥用 env_key 读环境变量 DEEPSEEK_API_KEY。官方示例用 experimental_bearer_token 直接写密钥，两种都行，区别见写法 B。
• model_catalog_json 写完整路径（Windows 用单引号写成 'C:\Users\你的用户名\.codex\models.json'，单引号里的反斜杠不用转义）。DeepSeek 示例写的是 ~/.codex/models.json，但 Codex 官方文档要求用完整路径，按官方的来更稳。
• 用 ChatGPT 桌面版的，再照 DeepSeek 示例加上 forced_login_method = "api"（只用 API 密钥，不弹 ChatGPT 登录），以及 [desktop] 段里的推理档位设置。

几点注意：

• 联网搜索只有 deepseek-v4-pro 支持，用它时可以把 web_search 改成 "live"，搜索按 DeepSeek 的 Search 接口单独计费。
• DeepSeek 默认开着思考模式，思考过程按输出 token 计费，价格和省钱方法见 DeepSeek 官方价格页。
• Kimi、智谱、MiniMax 等其他模型：先确认它们的接口支持 Responses。只支持 Chat Completions 的，Codex 接不了。

ChatGPT 桌面版和 VS Code 插件

官方说明里，命令行、ChatGPT 桌面版（Mac / Windows）、VS Code 里的 Codex 插件共用同一份配置文件：Mac 是 ~/.codex/config.toml，Windows 是 %USERPROFILE%\.codex\config.toml。改一次，几个地方都生效。

要注意两件事：

1. 改完要重启应用，桌面版不会自动重新读配置。
2. 从程序坞、开始菜单打开的应用，可能读不到你在终端里设的环境变量。写法 A 在命令行里正常、在桌面版或插件里报 Missing environment variable，就是这个原因。解决办法是改用写法 B 或写法 C。

换了服务商，以前的对话记录不见了？

没有删掉。DeepSeek 的官方文档专门提醒过这一点：Codex 按登录方式分组存放会话，用 ChatGPT 订阅聊的和用第三方 API 聊的分属两组，界面上只显示和当前配置匹配的那一组。切回原来的配置并重启，就能看到以前的会话；这时第三方 API 的会话又会被隐藏起来。

和 ChatGPT 订阅随时切换

平时用 ChatGPT 订阅、偶尔换到中转站的，用 profile（配置档）最方便：

1. 新建 ~/.codex/apifoo.config.toml，内容就是写法 A 的那几行。
2. 想用中转站时运行 codex --profile apifoo，不加 --profile 就还是原来的设置。

旧版本的写法是在 config.toml 里写 [profiles.apifoo]，从 0.134 起不再支持，会报错（见文末）。

也可以用图形界面的 CC Switch 管理多个服务商，见 CC Switch 安装与配置教程。api.foo 控制台里每把密钥的「⋯」菜单都有「CC Switch」，能把地址和密钥一键导入，Codex 的地址会自动填成 https://api.foo/v1。

超时、重试和长任务

和网络有关的三个设置都写在服务商那一段里（[model_providers.xxx] 下面）：

我们用错误的密钥实测：Codex 依次显示 Reconnecting... 1/5 到 5/5，大约 21 秒后才报 401。排查问题时可以把两个重试次数临时设成 0，错误马上就出来。

很多服务商前面套了 Cloudflare，单个请求 100 秒没有任何数据返回会被断开（524）。Codex 用流式输出，一般碰不到；真遇到了，问服务商有没有不经过 Cloudflare 的地址。api.foo 的直连线路是 https://dc.api.foo/v1，没有这个限制。

常见报错和解决办法

报错原文可以直接复制到页面里搜索（Mac 按 Cmd+F，Windows 按 Ctrl+F）。

unexpected status 401 Unauthorized：密钥不对

ERROR: unexpected status 401 Unauthorized: 无效的令牌 (request id: …), url: https://api.foo/v1/responses

url 后面是服务商的地址，说明请求已经发到了服务商，只是密钥不被认可：复制错了、多了空格，或者密钥已删除、过期、额度用完。前面会先出现几次 Reconnecting... n/5。怎么办：重新完整复制密钥；到服务商控制台看密钥状态。

Missing environment variable

ERROR: Missing environment variable: `APIFOO_API_KEY`.

用了写法 A，但 Codex 读不到这个环境变量。设完变量后没有重开终端，或者是在桌面版、插件里用的。怎么办：重开终端再试；桌面版和插件改用写法 B 或 C。

wire_api = "chat" is no longer supported

Error loading config.toml: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

老教程里的写法。怎么办：改成 wire_api = "responses"，或者直接删掉这一行（默认就是 responses）。如果服务商只支持 Chat Completions，改了也用不了，得换服务商。

--profile cannot be used while … legacy

Error loading config.toml: --profile `apifoo` cannot be used while …/config.toml contains legacy `profile = "apifoo"` or `[profiles.apifoo]` config; …

config.toml 里还留着旧版的 [profiles.xxx] 或 profile = "xxx"。怎么办：把那一段内容挪到单独的 ~/.codex/xxx.config.toml 文件里，再从 config.toml 里删掉。

string values must be quoted

Error loading config.toml:
…/config.toml:1:9: string values must be quoted, expected literal string
  |
1 | model = gpt-6.1-sol
  |         ^^^^^^^^^^^

TOML 里的文字要加英文双引号。怎么办：改成 model = "gpt-6.1-sol"。报错会指出第几行第几个字符。

404 或 405：地址不对

ERROR: unexpected status 404 Not Found: …, url: https://中转站地址/responses

看 url 那一段：少了 /v1，或者服务商根本没有 /v1/responses 这个接口。路径写错时有的服务商返回 405（我们把 api.foo 的地址故意写成 /v2 时，收到的是 405 Method Not Allowed）。怎么办：base_url 写成 https://域名/v1；确认服务商支持 Responses 接口。

400，说不认识某个参数

报错用服务商自己的话说某个字段不支持，比如 store、include、reasoning、text.verbosity。服务商的 Responses 接口没跟上新版 Codex。怎么办：联系服务商更新，或者换一家。

Model metadata … not found

warning: Model metadata for `xxx` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.

只是提示，用了 Codex 不认识的模型名，见模型名一节。

回复到一半卡住，或者第二轮对话就出错

服务商没有边生成边转发（把整段回复攒完才发），或者没有正确处理多轮对话、工具调用。官方排错表的建议是让服务商检查代理缓冲和 response.completed 事件。怎么办：联系服务商；同时可以调大 stream_idle_timeout_ms 看是不是只是慢。

余额不足、无可用渠道

用户额度不足, 剩余额度: ¥…
分组 xxx 下模型 xxx 无可用渠道

前者是账户余额不够；后者是这把密钥用不了这个模型，或者模型名写错了。这些中文原文是 api.foo 这类基于 New API 搭建的服务返回的，更多见 API 报错排查大全。

相关阅读

• Codex 安装与使用教程：一键安装、npm 国内镜像
• Claude Code 接中转站 / 第三方 API 配置教程
• CC Switch 安装与配置
• API 中转站是什么？怎么选不踩坑
• API 报错排查大全

参考资料

• Codex 官方文档：高级配置（自定义服务商）、配置项参考、连接 LLM 网关、网关兼容性要求、模型
• DeepSeek 官方文档：接入 Codex
• 本文实测：2026-10-17，macOS（Apple 芯片），Codex CLI 0.163.0；请求记录来自本机模拟中转站，报错原文来自 api.foo 的真实返回。