SupaStore

返回博客列表

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 教程(2026)

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

  1. 登录 SupaStore,进入【令牌管理】→【添加令牌】;
  2. 名称填 codex,只勾选准备在 Codex 里用的模型,并设置额度上限;
  3. 复制 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

四个容易踩的坑:

  1. 配置必须写在用户目录:项目里的 .codex/config.toml 会忽略 model_provider、model_providers 等提供商配置;
  2. 不要把 Key 写进 config.toml:Codex 从 env_key 指定的环境变量读取 Key;
  3. 提供商名字别用保留名:不要用 openai、ollama、lmstudio 作为自定义提供商的名字;
  4. 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

  1. 精简 AGENTS.md:Codex 每次会话都会读取项目里的 AGENTS.md,只写构建命令、目录约定等必要信息;
  2. 一个任务一个会话:完成一项任务后新开会话,避免历史上下文越滚越长;
  3. 给 Key 设额度上限:Codex 执行长任务时可能连续调用很多轮,额度上限能兜底;
  4. 定期看使用日志:在控制台的使用日志里按 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 怎么配置?》。