教程Codex

Codex 接入中转站：config.toml 里自定义供应商的写法、验证和常见问题

按 Codex 官方的网关文档整理：在 config.toml 里加一个自定义供应商，把 key 放进环境变量，就能让 Codex 走中转站。讲清中转站必须支持 Responses API、配置文件里顶层项的位置、怎么验证，以及供应商不生效、认证失败、流式卡住等问题怎么查。

发布 · 约 6 分钟读完 · 经人工审核（）· 本站的内容怎么来的

本文根据公开分享整理，本站尚未实测。操作前请对照文末的原始来源。

本页目录（9 节）
  1. 开始之前：从中转站拿到三样东西
  2. 第一步：写配置文件
  3. 第二步：把 key 放进环境变量
  4. 第三步：验证
  5. 桌面应用
  6. 常见问题
  7. 两点容易忽略的事
  8. 想换回官方登录
  9. 接上之后

Codex 接中转站和 Claude Code 不一样：不是设两个环境变量，而是在配置文件 config.toml 里加一个自定义供应商，再把 key 放进一个环境变量。最小的配置是这样：

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

[model_providers.relay]
name = "My Relay"
base_url = "https://你的中转站地址/v1"
wire_api = "responses"
env_key = "RELAY_API_KEY"

下面讲每一项是什么、怎么验证，以及出问题怎么查。

动手之前先确认一件事：中转站必须支持 OpenAI 的 Responses API。 官方文档写得很明确，现在的 Codex 不支持 wire_api = "chat"，只有 Chat Completions 接口的服务接不了；一个能用的 Chat Completions 或 Anthropic Messages 接口，不代表兼容 Responses。中转站的文档里如果没有专门写 Codex 的接法，先问清楚。

如果你还没弄清中转站是什么、有哪些风险，先读中转站是什么和用中转站有什么风险；选站可以看中转站排行榜。

开始之前：从中转站拿到三样东西

需要什么 说明
接口地址 官方的要求是带上 API 路径的完整地址，例如 https://gateway.example.com/v1。有的中转站的文档写的是不带 /v1 的地址，以它的文档为准
模型名 要用 Codex 认识的模型名，例如 gpt-6.1-sol。模型怎么选见Codex 该选哪个模型
API key 在中转站的控制台创建，多数站只显示一次

Codex 只能用 OpenAI 系的模型。想用 Claude 模型，接的应该是 Claude Code，见Claude Code 接入中转站。

1写配置文件

配置文件的位置：

  • Mac、Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

在 Windows 上新建时注意文件名是 config.toml，不要被保存成 config.toml.txt。

把开头那段配置合并进去，换成你自己的地址和模型。逐项说明：

配置项 作用
model 用哪个模型
model_provider 用哪个供应商，值是下面方括号里的那个 id
[model_providers.relay] 定义一个供应商，relay 是它的 id，可以自己起
name 显示用的名字
base_url 中转站的接口地址
wire_api 固定写 "responses"
env_key 环境变量的名字，Codex 从这个变量里读 key。这里填的是名字，不是 key 本身

三个容易出错的地方，都是官方文档特别提醒的：

  • model 和 model_provider 要写在第一个方括号之前。 TOML 里写在方括号后面的项属于那张表，Codex 不会把它当成顶层设置读。供应商“没生效”多半是这个原因。
  • 供应商的 id 不能用 openai、ollama、lmstudio。 这三个是内置供应商保留的。
  • 同一个项不要写两遍。 文件里已经有 model 的话，改它的值，不要再加一行。

你的中转站的文档可能会让你多写几项，比如和 WebSocket 有关的开关。那是它自己的要求，照它的文档写；本文只讲官方文档里有说明的最小配置。

2把 key 放进环境变量

变量名要和 env_key 里写的一致。官方的要求是 key 不要写进 TOML 文件，也不要写进仓库。

Mac、Linux：

export RELAY_API_KEY="你的key"

想长期生效，把这一行加进 ~/.zshrc 或 ~/.bashrc，然后重新打开终端。

Windows（PowerShell）：

[Environment]::SetEnvironmentVariable("RELAY_API_KEY", "你的key", "User")

设置后重新打开 PowerShell 才生效，可以用 echo $env:RELAY_API_KEY 确认。

如果中转站要求把 key 放在 X-API-Key 这样的自定义请求头里，而不是 Bearer token，官方的写法是把 env_key 换成：

env_http_headers = { "X-API-Key" = "RELAY_API_KEY" }

3验证

改完配置后重新启动 Codex。

  1. 运行 codex，输入 /status，确认当前的模型和供应商是你刚配的。启动前也可以先跑一遍 codex doctor 检查配置。

  2. 新开一个任务，发一句官方建议的测试提示词：

    Reply with exactly: gateway-ok

    回复是 gateway-ok 就说明接通了。

也可以不进交互界面，直接用一条命令测。写法来自酷站AI 的接入文档，模型名换成你用的：

codex exec --skip-git-repo-check -m gpt-6.1-sol "只回复 OK"

官方在这里有两句提醒，对用中转站的人很要紧：

  • 有回复，不能证明请求走的是哪条线路。
  • 不要靠问模型“你是什么模型”来判断。 模型的自我介绍不可靠。

所以接通只是第一步，给你的是不是它声称的模型，要另外验证，见文末。

只测通一句话还不够

官方的兼容性要求里，中转站除了能回一句话，还要做到：流式输出是一段段转发的，并且带着结束事件；追问时能接上前面的对话；工具调用能走完“收到调用、执行、交回结果、得到最终答案”这一整圈。

实际的检查办法很简单：让 Codex 做一件要读文件、要执行命令的小事，再追问一句。这三样都正常，才算真的能用。

桌面应用

Mac 和 Windows 的桌面应用读的是同一份 config.toml，改完后重启应用。要注意的是环境变量：在终端里设的变量，从桌面启动的应用不一定拿得到。 应用里认证失败而命令行正常，多半是这个原因。

常见问题

前六行取自官方的排查表。

现象 检查什么
生效的不是你配的供应商 顶层的 model、model_provider 是不是被写进了某张表里；是不是选了别的 profile
认证失败 环境变量有没有传到 Codex 的进程：变量名和 env_key 是否一致，设置后有没有重开终端
找不到模型 模型名是否和中转站提供的一致
模型的表现和预期的能力不符 中转站这个名字背后接的实际是什么模型，要问中转站
流式输出卡住，或者追问失败 中转站或它前面的代理有没有缓冲输出、有没有转发结束事件。这是中转站一侧的问题
提示找不到文件 配置里写的路径在运行 Codex 的环境里是否存在

下面几条来自酷站AI 的接入文档，是中转站一侧的常见情况，别家可能不同：

  • 提示供应商配置错误：检查文件名是不是 config.toml，以及 [model_providers.xxx] 里的 id 和 model_provider 的值大小写是否完全一致。
  • 出现和 WebSocket 有关的警告：把它文档里让你打开的 WebSocket 开关关掉，改走普通的 HTTPS。
  • 提示不支持 Claude 模型：Codex 只能用 OpenAI 系的模型。

向中转站求助时，贴报错信息之前先把 key 和敏感的提示词去掉。

两点容易忽略的事

你的代码会经过中转站。 官方文档画的路径是“Codex 客户端 → 网关 → 模型提供方”，并且写明：提示词、源码片段、工具的参数和结果，只要包含在模型请求里，都会经过网关。把仓库交给 Codex 之前，要清楚这一点，见用中转站有什么风险。

中转站的 key 只管模型请求。 MCP 服务器、插件有各自的网络路径和凭据，要另外配置，模型供应商的设置不会给它们授权。

想换回官方登录

删掉或注释掉顶层的 model_provider 那一行，Codex 就回到内置的供应商，重启后按原来的方式登录。供应商的定义可以留着，下次要用时改回来。

接上之后

来源

通过 API 中转站使用这些模型？到 Veridrop 免费检测中转站给你的是不是它声称的模型，或者看看中转站排行榜前 100 名。

相关文章