在 Codex 中配置 ZetaAPI

在 Codex（桌面端 / CLI）里把模型 provider 指向 ZetaAPI。最常见的失败是只写了 provider 配置块却没有选中它，导致请求仍打向 api.openai.com 并报 401「提供的 API 密钥不正确」。

更新于 2026-09-29

适用场景

Codex 支持把模型 provider 指向任意 OpenAI 兼容端点。指向 ZetaAPI 后，Codex 的对话、工具调用、Agent 任务继续可用，按 ZetaAPI 的倍率计费，余额与用量在控制台实时可查。

⚠️ 最容易踩的坑：config.toml 里只写了 [model_providers.xxx] 配置块，却没有加 model_provider = "xxx" 这一行。Codex 会继续使用默认的 OpenAI provider，把请求发往 api.openai.com —— 用 ZetaAPI 的 Key 打 OpenAI 官方，必然返回 401「提供的 API 密钥不正确」。这不是 Key 有问题，是请求根本没到 ZetaAPI。

准备工作

已安装 Codex（桌面端或 CLI）
已在 ZetaAPI 控制台获取 API Key（以 sk- 开头）
建议先在控制台开启「低余额提醒」

配置步骤

第 1 步：编辑 `~/.codex/config.toml`

model_provider = "zetaapi"        # ← 关键：必须有这一行，否则走默认 OpenAI
model = "gpt-5.5"                 # 填 ZetaAPI 支持的模型名

[model_providers.zetaapi]
name = "zetaapi"
base_url = "https://api.staging.cosmos-router.com/v1"   # ← 必须带 /v1
wire_api = "responses"
requires_openai_auth = true

model_provider 的值要和 [model_providers.<名字>] 里的名字完全一致。

Windows 上这个文件在 C:\Users\<你的用户名>\.codex\config.toml。注意：在 WSL 里写的配置只对 WSL 里运行的 CLI 生效，Windows 上的桌面端读的是 Windows 用户目录下的那一份。

第 2 步：填入 API Key

任选一种：

# 方式 A：写进 ~/.codex/auth.json
echo '{"OPENAI_API_KEY": "sk-你的Key"}' > ~/.codex/auth.json

# 方式 B：用环境变量
export OPENAI_API_KEY=sk-你的Key

⚠️ 用桌面端请选方式 A。 方式 B 的环境变量只对从这个终端启动的程序生效；从 Dock、开始菜单或托盘打开的桌面端读不到它，会不带 Key 直接发请求。

第 3 步：重启 Codex

配置文件不会热加载，必须完全退出后重新启动，否则改动不生效。

怎么确认请求真的打到了 ZetaAPI

配置是否生效，不用猜 —— 看报错信息里的这三个特征就能判定：

特征	打到了 OpenAI 官方（配置未生效）	打到了 ZetaAPI（配置正确）
URL	`https://api.openai.com/v1/responses`	`https://api.staging.cosmos-router.com/v1/...`
`CF-RAY` 头	有（如 `a319cb0f7bc37d9d-LAX`）	无
请求 ID	`req_ef53625be1cb...`	`X-Oneapi-Request-Id`，形如 `20260827...`
提示文案	引导你去 `platform.openai.com/account/api-keys`	不会提到 platform.openai.com

只要报错里出现 api.openai.com 或 CF-RAY，就说明请求没有经过 ZetaAPI，问题一定在本地配置，重新检查第 1 步的 model_provider 那一行。

在 Codex 里生图

Codex 自带的 image_gen 对本平台不可用，别去配置里找开关 —— 那个开关（[features] image_generation）默认就是开的，只是对 API Key 会话不生效。

原因是 image_gen 属于 hosted tool，Codex 把它硬编码限制在 ChatGPT 登录态。凡是用 API Key + 自定义 base_url 接入的会话（本页讲的正是这种），这个工具根本不会出现在模型的工具列表里。OpenAI 官方 issue #24465 正在跟进，目前无解。

我们提供了一个 Codex 插件来补这个洞，走标准的 OpenAI Images 接口，用你现有的 Key 即可：

codex plugin marketplace add Hermerz/zetaapi-codex-plugins
codex plugin add zeta-imagegen@zetaapi
export ZETAAPI_KEY=sk-你的Key

装完在 Codex 里直接说「画一张 …」，改图也支持。详见生图 API。

常见问题

Q：报 401「提供的 API 密钥不正确」，但 Key 明明是刚从控制台复制的

先按上表确认请求发给了谁。如果 URL 是 api.openai.com，那是配置没生效（多半缺 model_provider 那一行，或者改完没重启）。ZetaAPI 的 Key 只能在 ZetaAPI 上使用。

如果确认 URL 已经是 api.zetaapi.ai 仍然 401，请检查：Key 是否被复制完整（控制台列表里显示的是脱敏串，要点「复制」按钮取完整值）、Key 是否已被删除或禁用、账户余额是否为 0。

Q：报 401 Missing bearer or basic authentication in header，URL 是 api.openai.com

比上一条多了一层问题：请求不仅发去了 OpenAI 官方，而且没带任何 Key —— Codex 既没读到 model_provider = "zetaapi"，也没读到 Key。桌面端最常见，按下面逐项排查：

改完配置后没有完全退出：托盘或后台进程还在，用的仍是旧配置；
Key 是用 export 设的环境变量：桌面端读不到，改用第 2 步的方式 A 写进 auth.json；
配置写错了位置：Windows 上应在 C:\Users\<你的用户名>\.codex\，在 WSL 里写的配置对 Windows 桌面端无效。

排查完完全退出再重新打开。配置生效后如果仍有报错，报错里的 URL 会变成 api.zetaapi.ai，再按上一条继续排查。

Q：报 404 或 Invalid URL

base_url 漏了 /v1。OpenAI 兼容模式必须写成 https://api.staging.cosmos-router.com/v1。

Q：模型名报错 model_not_found

该模型名在你所在的分组下没有可用渠道。以价格页的型号列表为准，或联系客服确认分组。

Q：改了配置没反应

Codex 不会热加载 config.toml，必须完全退出进程后重启。桌面端要确认托盘/后台进程也已退出。

Q：想在 Codex 里生成图片，但找不到 image_gen 的配置

那个配置不存在，也不需要找 —— Codex 把内置生图工具限制在 ChatGPT 登录态，API Key 会话拿不到它。见上方在 Codex 里生图。