开发工具接入
ChatGPT 与 Codex 接入第三方 API 指南:config.toml 完整配置教程
配置 Codex 与 ChatGPT CLI 的 ~/.codex/config.toml 自定义供应商。掌握 wire_api responses 协议规范、auth.json 权限配置、CC Switch 一键导入与排坑排查。
修改 config.toml 前的准备工作
OpenAI Codex CLI 与桌面客户端为开发者提供了强大的代码生成与自动化仓库重构能力。通过在 config.toml 中配置自定义模型供应商,开发者可以将 Codex 的全部流量分发至独立的 API Route 聚合网关,按价格页选择 GPT-5 系列、Claude Sonnet 与 DeepSeek 等模型,并保留可审计的调用记录。带日期的 Claude 价格对比见博客,本文不给出节省比例。
在动手修改配置文件前,请先在 API 接入 复制有效的 API Route 密钥,前往 模型价格页 核对目标模型的启用状态与分组,并确认本机已安装 Codex CLI。官方供应商接口协议规范可结合标准 OpenAI Chat Completions 规范 相互对照。
协议关键机制:为什么 wire_api 必须设为 responses
在较新版本的 Codex 中,一个极其关键的技术改动是官方完全移除了对旧版 Chat Completions 协议的支持。在 config.toml 的供应商段落中,必须显式声明 wire_api = "responses"。若误写为旧版 wire_api = "chat",Codex 在启动执行时会直接抛出不支持该传输协议的致命异常。
Codex 严重依赖 OpenAI 的 Responses API 格式来完成工具调用流式下发、多步 Agent 任务调度与客户端文件系统的实时更新。API Route 网关原生支持并完整实现了 Responses API 协议转换,无需依赖外置的 sidecar 转换代理即可无缝运行。
| 配置键名 | 必填值 / 建议值 | 技术说明与约束 |
|---|---|---|
| model_provider | "api_route" | 顶层全局配置项,指定 Codex 启动时默认激活哪一个供应商段落。 |
| base_url | "https://global.api-route.com/v1" | 网关调用地址。注意末尾必须带 /v1,且不能有斜杠尾巴。 |
| wire_api | "responses" | 强制协议格式。当前 Codex CLI 版本已完全弃用旧版 "chat"。 |
| requires_openai_auth | true | 告知 Codex 按照 OpenAI 标准格式传递 Bearer 凭据。 |
| disable_response_storage | true | 隐私与安全保护项,禁止在上游服务商处缓存会话记录。 |
必须特别注意:出于安全隔离限制,放置在本地代码仓库 .codex/config.toml 里的自定义供应商段落会被 Codex 完全忽略。所有第三方供应商必须统一配置在用户主目录下的全局配置文件中。
分步实操:修改 config.toml 与 auth.json
Codex 的配置文件存储在用户根目录,不同操作系统的路径如下:
- macOS / Linux:
~/.codex/config.toml与~/.codex/auth.json - Windows:
%USERPROFILE%\.codex\config.toml与%USERPROFILE%\.codex\auth.json
首先,如果目录不存在则自动创建,并在打开编辑器前备份已有配置:
mkdir -p ~/.codex
test -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.toml使用以下内容完整替换 ~/.codex/config.toml,切勿与旧供应商配置混杂:
# ~/.codex/config.toml
model_provider = "api_route"
model = "gpt-5.6-sol"
disable_response_storage = true
[model_providers.api_route]
name = "API Route"
base_url = "https://global.api-route.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false接下来,将你的 API Route 密钥写入 ~/.codex/auth.json。Codex 会读取其中的 OPENAI_API_KEY 作为认证 Token:
{
"OPENAI_API_KEY": "sk-your-api-route-key"
}在 Linux 或 macOS 系统上,建议锁定该文件的读取权限,仅限当前系统用户访问:
chmod 600 ~/.codex/config.toml
chmod 600 ~/.codex/auth.jsonLinux 环境下的专属命令与说明,也可参阅 Codex 自定义供应商文档。
进阶方式:使用 CC Switch 桌面端一键导入与切换
如果你倾向于通过图形界面管理而不是手动编辑 TOML,推荐使用独立社区维护的开源工具 CC Switch。它支持在 Codex、Claude Code 等多个开发客户端之间一键切换供应商与凭据。
- 登录 API Route 后进入 API 接入,选择已启用的密钥、目标模型和首选节点。
- 目标应用选择 Codex,连接方式保持为 CC Switch。
- 确保本地已打开 CC Switch 客户端,点击页面的“一键导入到 CC Switch”。
- 在 CC Switch 中进入 Codex 供应商列表,将刚导入的
api-route切换为“使用中”。 - 重启 Codex,界面左下角将出现
api-route标识。
CC Switch 会自动在底层写入上述标准 config.toml 和 auth.json 内容,避免手工排版导致的缩进与格式错误。
连接验证与故障排查自查矩阵
完成配置后,在终端运行 Codex 的内置诊断命令,核对连通性与模型响应:
codex doctor
codex "Reply in one sentence: What model are you?"如果启动或调用时出现异常,请对照下表进行诊断:
| 现象 / 错误提示 | 可能诱因 | 核验与修复措施 |
|---|---|---|
| Unsupported wire_api error | config.toml 中误填了 wire_api = "chat" | 修改为 wire_api = "responses"。新版 Codex 严格禁止使用旧版 chat 协议。 |
| 401 Unauthorized | auth.json 中的密钥无效或格式损坏 | 检查 ~/.codex/auth.json,确认 JSON 键名为 OPENAI_API_KEY 且填入了正确的 API Route 密钥。 |
| 404 Not Found | base_url 路径多写或遗漏了 /v1 | 核对 base_url 是否精确为 https://global.api-route.com/v1,不要添加尾部斜杠。 |
| 配置不生效 / 仍走官方 | config.toml 放在了项目仓库局部目录 | 将配置移动至用户主目录 ~/.codex/config.toml,局部仓库配置文件不支持定义供应商。 |
| 403 Forbidden / 模型不可用 | 配置的 model 未在当前密钥分组中启用 | 通过 /v1/models 查看可用模型列表,或在 API 接入中检查密钥权限组。 |
每次排查测试后,可在 调用日志 中查看请求详情、扣费 Token 计数与响应延迟。
生产环境上线检查清单
- 原配置安全备份:修改前务必生成
config.toml.bak,确保随时能一键回退到官方环境。 - 免费测试额度:新用户享有 $0.20 测试金,通过 创建账户 并在 快速入门 中完成首笔低成本调用验证。
- 显式锁定模型名:在
model = "..."中明确指定如gpt-5.6-sol等具体版本,避免浮动别名引入预期外变更。 - 严禁提交密钥:切勿将
~/.codex/auth.json提交到公网 Git 仓库。 - 用量与日志核对:在完成复杂编码任务后,前往 调用日志 对照扣费金额与 token 计量。
按照上述规范配置,即可兼顾 Responses API 的高保真 Agent 能力与 API Route 极低成本的按量计费优势。