Codex 怎么接中转站？从 Responses 验证到 CLI 配置
简答：Codex CLI 接入中转站的最短路径是：确认服务商支持 Responses API，准备准确的 Base URL 和模型 ID，用一个不含真实代码的最小请求验证 2xx，再写入用户级 config.toml。当前官方配置参考确认自定义 provider 使用 `model_providers.<id>`，`wire_api` 的支持值为 `responses`；但具体网关是否支持该协议、模型名和路径，仍必须以服务商当前接入文档或实际响应为准。
定义：Codex 中转接入，是让 Codex CLI 通过自定义 provider 使用第三方 API 网关的 Base URL、API Key 和模型，而不是通过 ChatGPT 账户登录路径调用。
先用 30 秒判断能不能接：三项核验卡
本文只讲 Codex CLI，不覆盖桌面端、VS Code 扩展或 app-server。页面按 2026年10月31日 访问到的官方配置参考整理；Codex CLI 和服务商网关都会更新，实际配置前应再次查看当前文档和本机版本。
| 项目 | 应确认什么 | 没有证据时怎么处理 |
|---|---|---|
| 协议 | 服务商是否直接支持 Responses API，以及最终路径是否为 /responses | 不要把 Chat Completions 示例当成 Responses 兼容证明 |
| Base URL | 服务商提供的 API 根地址是否已经包含版本路径，例如 /v1 | 按文档填写，不要反复猜测是否删除或追加 /v1 |
| 模型 ID | 服务商允许的精确模型字符串 | 使用控制台或接入文档中的值，不自行猜测别名 |
| 认证 | API Key 是否有效、是否需要 Bearer 认证、是否有权限或预算限制 | 先用同一把 Key 发最小请求 |
官方 Codex 配置参考确认：用户级配置位于 ~/.codex/config.toml；model_provider 指向 model_providers 中的 provider ID；自定义 provider 可以配置 base_url、env_key、name 和 wire_api。其中 wire_api 的官方支持值是 responses，省略时默认也是该值。可查看Codex 配置参考。
最短判定：Base URL、API Key、模型 ID 三者准确，向最终的 Responses 地址发送请求并返回 2xx，才值得继续配置 Codex；仅仅能访问服务商首页、能调用 Chat Completions，或返回一段 JSON，都不足以证明 Codex 可用。
第一步：用最小 Responses 请求验证地址、Key 和模型
先不要修改 Codex 配置。把下面的占位符替换为服务商提供的值：BASE_URL 应是 API 根地址，MODEL_ID 应是服务商明确公布的模型 ID，CODEX_API_KEY 是本地环境变量名。若服务商给出的 Base URL 已经是 https://example.com/v1，最终请求通常应拼成 https://example.com/v1/responses；是否如此必须以服务商路径说明为准。
macOS 或 Linux 可以用一次性读取方式，避免把 Key 直接写进命令行：
read -s CODEX_API_KEY
printf '\n'
export CODEX_API_KEY
BASE_URL='https://api.example.com/v1'
MODEL_ID='替换为服务商确认的模型ID'
curl -i "$BASE_URL/responses" \
-H "Authorization: Bearer $CODEX_API_KEY" \
-H "Content-Type: application/json" \
--data "{\"model\":\"$MODEL_ID\",\"input\":\"Reply with exactly CODEX-OK\"}"这里的示例只验证认证、地址、模型和 Responses 请求，不验证文件读取、工具调用、MCP、审批或长连接能力。成功判定包括三点：HTTP 状态为 2xx；响应不是 HTML 错误页；响应中能找到有效的输出或服务商明确的 Responses 响应结构。若服务商提供请求记录，可以把它作为辅助证据，但不能把“后台有日志”作为所有服务商都具备的通用条件。
- 401：检查变量是否为空、Bearer 前缀是否由客户端自动添加、Key 是否被截断或撤销。
- 403：检查 Key 权限、账户状态、区域策略或服务商访问控制；不要自动归因于 Codex 配置。
- 404 或 405：检查 Base URL 的版本路径和最终请求路径，确认不是把 Chat Completions 地址用于 Responses。
- 429：检查限速、并发、账户额度或服务商预算窗口。
- 超时或流式中断：先用短输入排除内容复杂度，再确认服务商是否支持 Codex 所需的流式响应和连接保持。
OpenAI 的 Responses API 参考说明了 Responses 请求、响应状态和流式事件的结构；这能帮助你区分真正的 API 响应与网关返回的普通错误文本，可查看Responses API 概览和Responses API 参考。
第二步：按官方字段写入 Codex CLI 配置
确认最小请求通过后，再把 provider 写入用户级配置。官方文档明确说明，项目目录下的 .codex/config.toml 不能覆盖 model_provider 和 model_providers 等 provider 设置，因此中转配置应优先放在用户级 ~/.codex/config.toml。
下面是通用模板，不包含任何特定服务商的真实地址或模型名：
model = "MODEL_ID"
model_provider = "relay"
[model_providers.relay]
name = "兼容 API 网关"
base_url = "https://api.example.com/v1"
env_key = "CODEX_API_KEY"
wire_api = "responses"
requires_openai_auth = false字段含义如下：
model：服务商确认可用的模型 ID，不要因为某个模型名称看起来像兼容模型就直接使用。model_provider：必须与下面的 provider 表名一致，本例为relay。base_url：API 根地址，不要预先写入完整的/responses，除非服务商文档明确要求。env_key：Codex 从哪个环境变量读取 API Key。wire_api：当前官方配置参考列出的唯一支持值是responses。requires_openai_auth：官方配置参考说明其默认值为false。对于使用自有兼容网关 API Key 的场景，可省略该字段，避免把 app-server 示例中的字段误当成 CLI 必填项。
保存后，在同一个终端临时设置 Key，再运行最小测试：
export CODEX_API_KEY
codex exec "只回答 CODEX-OK，不读取文件，不执行命令"如果你需要多个 provider，官方配置参考确认 profile 文件位于 $CODEX_HOME/profile-name.config.toml，并可使用 codex --profile profile-name 选择。这里的 profile 是官方支持的独立配置文件机制；不要把 provider 配置写入项目级文件后，再期待它覆盖用户级 provider 设置。可查看官方文档中的config.toml 与 profile 说明。
Windows 的路径、环境变量继承和安装方式可能因 CLI 安装渠道而不同。本文不把某个固定 Windows 目录当成所有版本的保证；更稳妥的做法是先确认当前 CODEX_HOME，再在对应目录放置 config.toml，并用同一启动环境执行测试。
第三步：把 API Key 安全地交给 Codex
最安全的顺序是：优先使用操作系统密钥管理器或团队的 Secret Manager；临时测试时只在当前进程环境中注入；不要把真实 Key 写入 config.toml、Git 仓库、截图、复制链接、工单或 CI 输出。
macOS/Linux 的临时测试可以使用：
read -s CODEX_API_KEY
printf '\n'
export CODEX_API_KEY
codex exec "只回答 CODEX-OK"这种方式仍可能让 Key 留在当前 shell 进程直到窗口关闭，因此测试结束后可以执行：
unset CODEX_API_KEY如果使用 PowerShell，建议从系统凭据管理工具或企业密钥管理方案读取；临时调试时至少避免把 Key 写进脚本文件和命令历史，并在测试后关闭终端。不要为了方便把 experimental_bearer_token 直接写入配置：官方参考明确把直接 bearer token 标为不推荐，优先使用 env_key。
还要注意代码隐私边界：请求经过第三方网关时，API Key、提示词、代码片段、错误日志以及可能的工具输入都可能受该服务商处理。接入前应逐项查看其可核验的隐私和服务条款，确认数据留存期限、是否用于训练、是否跨区域处理、删除机制、日志访问范围以及企业合规选项。若找不到公开说明，就标记为“未核实”，不要根据宣传语推断。
Codex CLI 接通后如何确认请求没有走错
建议按“配置层—请求层—业务层”三层检查，不要只看终端是否出现回复。
- 配置层：确认
model_provider = "relay"与[model_providers.relay]完全一致；env_key与当前环境变量名称完全一致；模型 ID 没有多余空格或拼写差异。 - 请求层：用同一环境变量执行 curl，检查最终 URL、HTTP 状态码和响应类型。若 curl 失败，先不要继续改 Codex。
- 业务层：运行不读取文件、不调用工具的短提示。若服务商提供请求日志，再对照时间、请求 ID 或脱敏记录辅助确认。
如果 curl 成功但 Codex 失败，优先排查 Codex 实际读取的配置根目录、profile 是否选错、环境变量是否被启动方式继承，以及当前进程是否在修改配置后完全重启。如果 curl 和 Codex 都失败，则回到 Base URL、模型 ID、Key 和 Responses 支持四项核验。
官方帮助中心也区分了 ChatGPT 登录和 Codex CLI 的使用路径：使用 ChatGPT 账户登录时，遵循 ChatGPT 计划和工作区规则；使用自有 API Key 接入兼容网关时，计费、限速、预算和停用规则应以该 API 服务方为准，不能默认等同于 ChatGPT 订阅额度。相关背景可查看在 ChatGPT 套餐中使用 Codex。
常见错误的证据化排查
| 报错或现象 | 先收集的证据 | 下一步 |
|---|---|---|
| Missing environment variable | 打印变量是否为空，但不要打印变量值 | 核对 env_key，完全重启 Codex，并确认启动进程继承了变量 |
| 401 Unauthorized | 同一 Key 的 curl 状态码、Key 是否被撤销 | 重新生成或更换 Key，检查 Bearer 认证方式 |
| 403 Forbidden | 账户、权限、区域和服务商策略 | 查看服务商控制台或帮助文档，不要仅修改 TOML |
| 404/405 | 最终 URL 是否为服务商要求的 Responses 路径 | 按文档重新确认 Base URL 是否含 /v1，不要盲目删改 |
| Model not found | 模型 ID 的官方原文、控制台模型列表或返回体 | 改用已核实的精确 ID；查不到就标记为未核实 |
| Responses 不支持 | 服务商是否只提供 Chat Completions 文档或返回 404/405 | 向服务商确认是否实现 Responses；不能靠设置 wire_api 强行转换协议 |
| 429、预算或额度耗尽 | 响应头、错误体、账户用量和并发设置 | 按服务商规则降低并发、等待窗口恢复或补充额度 |
| 超时、SSE 中断 | 短请求与长请求的差异、网关超时和流式响应行为 | 先关闭工具与复杂输入，再确认服务商是否支持 Codex 所需的流式传输 |
状态码只能帮助缩小范围，不能单独证明故障归因。例如 404 可能来自错误路径，也可能来自服务商未开放该接口；429 可能是速率限制，也可能与账户预算有关。保留脱敏后的状态码、最终路径、响应摘要和时间，通常比反复修改配置更容易定位问题。
切回官方登录前要记住的边界
第三方 API Key 和 ChatGPT 登录是两套认证路径。需要切回官方登录时，先退出当前 Codex 进程，停用或切换自定义 provider，再按照当前 Codex CLI 的登录提示完成官方登录；不要把第三方 Key 当作 ChatGPT 登录凭据。切换前后，建议分别运行一个不涉及项目文件的短测试，避免把两套认证状态混在同一次排错中。
本文是独立的第三方接入指南，不代表任何服务商的官方配置页面。服务商的实际 Base URL、模型 ID、Responses 支持、区域、数据处理、预算、限速和日志能力均应以其当前公开文档、控制台响应或账户条款为准；无法核验的内容不要写入配置。
如果你已经完成协议、Base URL、模型和 Key 的核验，可查看犀速 AI 官网的 API 接入说明，并沿用本文的“先最小请求、再写 Codex 配置、最后做错误分流”流程。
常见问题
Codex 接中转站一定要写 wire_api = "responses" 吗？
按当前官方 Codex 配置参考，`wire_api` 的支持值是 `responses`，省略时默认也是 `responses`。但这只说明 Codex 的 provider 配置方式，不代表任意网关都支持 Responses；仍需用服务商文档或最小请求确认。
Base URL 应该填到 /v1，还是填到 /v1/responses？
通常 `base_url` 填 API 根地址，再由客户端访问 Responses 路径；但最终规则取决于服务商的路由设计。先查看服务商接入说明，再用 curl 检查实际最终 URL，不要仅凭 404 猜测。
为什么 curl 成功，Codex 仍然提示缺少 API Key？
常见原因是 Codex 与 curl 不在同一个进程环境中，或 `env_key` 写的变量名与实际变量不一致。先在同一终端确认变量非空，再完全退出并重启 Codex；如果使用 profile，也要确认选择的是预期配置。
可以把真实 API Key 直接写进 config.toml 吗？
技术上可能存在直接 bearer token 字段，但官方配置参考将直接 bearer token 标为不推荐。更稳妥的是使用 `env_key`、操作系统密钥管理器或 Secret Manager，并避免把 Key 放入仓库、截图、日志和命令历史。
中转网关只展示 Chat Completions 示例，Codex 能不能直接用？
不能直接推断。Codex 当前自定义 provider 使用 Responses 协议；如果网关没有明确说明 Responses 支持，或对 `/responses` 返回 404/405，应先向服务商确认，而不是只修改模型名或 `wire_api`。
使用第三方 API Key 会不会消耗 ChatGPT 订阅额度？
不能默认这样认为。ChatGPT 登录和自有 API Key 是不同认证路径；第三方 API 的计费、预算、限速和停用规则应以对应服务商的当前说明为准，查不到的部分应标记为未核实。