Codex CLI 怎么配置中转 API?Codex config.toml 自定义 Base URL 教程(2026)
Codex CLI 怎么配置中转 API?本文讲清 Codex config.toml 的位置与写法,用 model_providers 自定义 Base URL、env_key 和 wire_api,让 Codex 通过中转 API 在国内稳定使用,并附验证命令、Windows 配置与常见报错排查。
SupaStore 开发者体验组 ·

Codex CLI 配置中转 API 的核心只有一个文件:~/.codex/config.toml。在里面定义一个自定义模型提供商,写上中转站的 Base URL 和存放 Key 的环境变量名,Codex 的请求就会发往中转站,不需要 ChatGPT 账号,也不依赖国外网络。
本文用 SupaStore 演示完整的 Codex 中转配置:Codex config.toml 怎么写、Key 放在哪里、怎么验证生效,以及常见报错的处理方法。还在比较中转服务商的话,可以先看《API中转站是什么?AI中转站选型避坑指南》。
Codex CLI 是什么
Codex CLI 是 OpenAI 推出的终端 AI 编程工具,可以在本地项目里阅读代码、修改文件、执行命令。它和 Claude Code 定位类似,区别在于 Codex 主要调用 OpenAI 的模型,并且使用 OpenAI 的 Responses 协议通信。
所以,给 Codex 配置中转 API 时,中转站必须提供 /v1/responses 接口,只兼容 Chat Completions 是不够的。SupaStore 同时提供这两种接口。
第一步:安装 Codex CLI
Codex CLI 通过 npm 安装,需要先装好 Node.js:
npm install -g @openai/codex
codex --version
Windows 用户建议在 WSL2 中安装和运行,各系统的完整安装步骤见文档《OpenAI Codex CLI 接入》。
第二步:创建 Codex 专用 API Key
- 登录 SupaStore,进入【令牌管理】→【添加令牌】;
- 名称填
codex,只勾选准备在 Codex 里用的模型,并设置额度上限; - 复制
sk-开头的密钥。
第三步:编写 Codex config.toml
编辑用户目录下的 ~/.codex/config.toml(Windows 在 WSL 中同样是 ~/.codex/config.toml),文件不存在就新建:
model = "gpt-5.6-luna"
model_provider = "supastore"
[model_providers.supastore]
name = "SupaStore"
base_url = "https://api.supastore.cc/v1"
env_key = "SUPASTORE_API_KEY"
wire_api = "responses"
逐项说明:
| 配置项 | 含义 |
|---|---|
model |
默认使用的模型 ID,以模型广场中的 ID 为准 |
model_provider |
使用哪个提供商,对应下方 [model_providers.xxx] 的名字 |
base_url |
中转站接口地址,以 /v1 结尾,Codex 会自动拼接 /responses |
env_key |
存放 API Key 的环境变量名,不是 Key 本身 |
wire_api |
通信协议,填 responses |
四个容易踩的坑:
- 配置必须写在用户目录:项目里的
.codex/config.toml会忽略model_provider、model_providers等提供商配置; - 不要把 Key 写进 config.toml:Codex 从
env_key指定的环境变量读取 Key; - 提供商名字别用保留名:不要用
openai、ollama、lmstudio作为自定义提供商的名字; wire_api填responses:据多份 2026 年的配置指南,新版 Codex 已不再支持chat,网上不少旧教程仍在用wire_api = "chat",照抄会在启动时报错。
第四步:设置 API Key 环境变量
macOS / Linux / WSL,把 Key 写进 Shell 配置文件,之后每次打开终端都会生效:
echo 'export SUPASTORE_API_KEY="sk-your-supastore-api-key"' >> ~/.bashrc
source ~/.bashrc
使用 zsh 的话,把 ~/.bashrc 换成 ~/.zshrc。
Windows PowerShell(不在 WSL 中运行时):
setx SUPASTORE_API_KEY "sk-your-supastore-api-key"
setx 只对新打开的终端生效,设置后要重新打开 PowerShell。
第五步:验证 Codex 中转 API 是否生效
先用 cURL 测试 Responses 接口
curl https://api.supastore.cc/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUPASTORE_API_KEY" \
-d '{"model": "gpt-5.6-luna", "input": "Ping"}'
能返回包含 output 字段的 JSON,说明 Key、模型和 Responses 接口都可用。
再启动 Codex
cd /path/to/your/project
codex
输入"说明这个项目的目录结构",Codex 能正常读取文件并回答,就说明 Codex CLI 配置中转 API 已经成功。Codex 只在启动时读取配置,修改 config.toml 后需要退出重开。
Codex 中转配置常见报错
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 401 / 提示缺少 API Key | 环境变量没生效,或 env_key 写成了 Key 本身 |
运行 echo $SUPASTORE_API_KEY 检查,env_key 只写变量名 |
| 仍然要求登录 ChatGPT | 提供商配置写在了项目级 .codex/config.toml |
移到用户目录 ~/.codex/config.toml |
| 404 Not Found | base_url 少了 /v1,或手动加了 /responses |
严格填写 https://api.supastore.cc/v1 |
| 启动时报 wire_api 错误 | 沿用了旧教程的 wire_api = "chat" |
改成 wire_api = "responses" |
| 模型不存在 | 模型 ID 拼写错误,或 Key 未勾选该模型 | 在模型广场核对 ID,检查 Key 的可用模型 |
| 改了配置不生效 | Codex 只在启动时读取配置 | 退出 Codex 后重新启动 |
更多错误码的含义见《Claude API 报错怎么办?》,其中 401、402、429 的处理方法对 Codex 同样适用。
用 Codex 如何省 Token
- 精简 AGENTS.md:Codex 每次会话都会读取项目里的
AGENTS.md,只写构建命令、目录约定等必要信息; - 一个任务一个会话:完成一项任务后新开会话,避免历史上下文越滚越长;
- 给 Key 设额度上限:Codex 执行长任务时可能连续调用很多轮,额度上限能兜底;
- 定期看使用日志:在控制台的使用日志里按 Key 查看每天的消耗,找出最费 Token 的任务。
常见问题 (FAQ)
Q: Codex CLI 不登录 ChatGPT 能用吗?
答: 能。在 config.toml 中配置自定义提供商并设置好 API Key 环境变量后,Codex 直接用中转站的 Key 调用模型,不需要登录 ChatGPT 账号,也不消耗 ChatGPT 订阅的额度。
Q: 环境变量 OPENAI_BASE_URL 还能用吗?
答: 不建议依赖它。新版 Codex 推荐在 config.toml 里配置提供商,环境变量的方式在部分版本、桌面应用和 IDE 插件中可能不生效,写进配置文件最稳定。
Q: Codex 能用 Claude 模型吗?
答: Codex 主要针对 OpenAI 模型调优。想用 Claude 写代码,更推荐 Anthropic 官方的 Claude Code,安装和配置见《Claude Code 教程:2026 Claude Code 安装与使用指南》。
Q: Codex、Cline 和 Cursor 能共用一个 API中转站吗?
答: 可以。同一个中转站同时提供 Responses、Chat Completions 和 Claude 原生接口。建议每个工具单独创建 Key,方便区分消耗。Cline 的配置见《Cline 怎么配置 API?》,Cursor 的配置见《Cursor 中转 API 怎么配置?》。