SuperAPI 教程

Codex CLI 配置 ​

新人入口注册 / 登录 / IP 加白创建 API 令牌
Base URLhttps://superapi.buzz

1. 安装 Codex ​

确保已安装 Node.js，然后安装或更新 Codex CLI：

bash
npm install -g @openai/codex

如果 npm 安装失败，先看 网络与代理，确认命令行能访问 npm 源。

启动：

bash
codex

如果你明确知道自己在做什么，也可以使用跳过权限确认的模式：

bash
codex --dangerously-bypass-approvals-and-sandbox

或者

bash
codex --yolo

权限提醒

跳过权限确认会让 Codex 直接执行命令。只建议在可信目录、可信机器上使用。

2. 配置 Base URL 和 Token ​

建议直接使用CC Switch，不需要管下面的繁琐配置

两种鉴权方式，二选一

本节用环境变量（OPENAI_API_KEY / OPENAI_BASE_URL）配置，简单直接。第 9 节「最终模板」走另一条路——在 ~/.codex/config.toml 里设 requires_openai_auth = true，令牌改放 ~/.codex/auth.json。两者二选一：一旦开了 requires_openai_auth = true，Codex 就会忽略这里的 OPENAI_API_KEY 环境变量。

Codex 使用 OpenAI 兼容接口时，通常需要：

临时使用可以直接在当前终端里导出：

bash
export OPENAI_API_KEY="sk-你的令牌"
export OPENAI_BASE_URL="https://superapi.buzz/v1"

Windows PowerShell：

powershell
$env:OPENAI_API_KEY="sk-你的令牌"
$env:OPENAI_BASE_URL="https://superapi.buzz/v1"

如果你要长期使用，不要只靠当前终端里的临时导出。按系统持久化保存：

macOS / Linux（zsh）：

bash
echo 'export OPENAI_API_KEY="sk-你的令牌"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://superapi.buzz/v1"' >> ~/.zshrc
source ~/.zshrc

用 Bash 就把 ~/.zshrc 换成 ~/.bashrc。

Windows PowerShell：用 setx 写入用户环境变量（需重开终端才生效）：

powershell
setx OPENAI_API_KEY "sk-你的令牌"
setx OPENAI_BASE_URL "https://superapi.buzz/v1"

或写进 PowerShell 配置文件，每次启动自动加载：

powershell
Add-Content $PROFILE '$env:OPENAI_API_KEY="sk-你的令牌"'
Add-Content $PROFILE '$env:OPENAI_BASE_URL="https://superapi.buzz/v1"'
. $PROFILE

3. 本地鉴权缓存 ​

Codex 还会在本地保存 ~/.codex/auth.json 作为鉴权缓存，由客户端自动创建和更新。不要手动编辑；如果清掉它，就需要重新登录或者重新配置API KEY。

如果你走第 9 节的 requires_openai_auth = true 方案，令牌就存在这里。用客户端命令写入（不要手编）：codex login --api-key "sk-你的令牌"（之前登过 ChatGPT 先 codex logout）。这种模式下 auth.json 优先，OPENAI_API_KEY 环境变量会被忽略。

4. 模型选择 ​

进入 Codex 后，通过客户端的模型设置选择可用模型。若提示模型元数据缺失，不影响使用，但可能影响 token 估算或体验。

在 CLI 里输入图片

把图片复制到剪贴板，然后在输入框按 Alt+V 粘贴——终端的 Ctrl+V 通常粘不了图片，所以用 Alt+V。也可以把图片文件直接拖进终端窗口，或在提示里写出图片的本地路径。

如果是在 IDE 集成终端里连接远程服务器（如 VS Code Remote-SSH），Alt+V 通常贴不了图（剪贴板在本地、终端在远程）；这种情况改用对应的 VS Code 插件贴图。

5. fast 和百万上下文 ​

Codex fast 可以在 Codex 里执行：

text
/fast

GPT / Codex API 层对应：

json
{
  "service_tier": "fast"
}

SuperAPI 会按请求里的 fast / service_tier 动态计费。

GPT 百万上下文超过 272k 的部分会额外计费。不要默认把整个仓库、超长日志一次性塞进上下文。

详见 fast 与百万上下文。

6. multi_agent 与 goal 特性 ​

按下图在 Codex 配置里开启这两项：

multi_agent 与 goal

  • multi_agent（多 agent 协作）：让 Codex 同时派生多个子 agent 分工处理、再汇总结果，适合可拆分、需要并行推进的大任务。直接用自然语言描述需求即可驱动，不需要专门命令。
  • goal：把一句话目标变成「规划 → 执行 → 验证」的自循环代理，适合迁移、重构等长任务。用 /goal 命令触发，用前先给出清晰的成功判据。

实际使用时，默认用 /goal 驱动即可——goal 执行过程中通常会自动调用 multi_agent，不用你手动编排。

Claude Code 默认就有

Claude Code 默认就具备多 agent 协作（子 agent / 团队）与规划能力，不需要额外开启。详见 CC Switch 高级设置。

7. 防止跳转官方 ​

如果 Codex 没走中转、直接打到了 OpenAI 官方，通常是 Base URL / Token 配置没生效。最典型的信号是报错里出现 platform.openai.com，类似：

text
401 Incorrect API key provided: sk-****.
You can find your API key at https://platform.openai.com/account/api-keys.

你的 SuperAPI 令牌在官方那边是无效的，所以会 401——出现这个就说明请求跑到了 api.openai.com，而不是 SuperAPI。

排查：

  • Base URL 是否生效：OPENAI_BASE_URL 是否为 https://superapi.buzz/v1；或 ~/.codex/config.toml 里 [model_providers.*] 的 base_url 是否填对。
  • 是否同一个终端：环境变量要和启动 codex 的是同一个终端会话。
  • 是否被残留的 OPENAI_API_KEY 覆盖：系统环境变量、或项目目录下的 .env（被 shell 自动加载）里若残留了别的 OPENAI_API_KEY，会覆盖你的配置、把 key 发去官方。先用 echo $OPENAI_API_KEY（PowerShell 用 $env:OPENAI_API_KEY）检查并清掉无关的。
  • config.toml 位置：Codex 读 ~/.codex/config.toml（或 $CODEX_HOME/config.toml），别改错文件。
  • 本地鉴权缓存：~/.codex/auth.json 可能缓存了旧 key，与自定义 base_url 不匹配也会 401（见「本地鉴权缓存」一节）。

在 Codex 里输入 /status 可以查看当前实际生效的 provider / Base URL / 模型，确认是不是 SuperAPI。

8. 常见问题 ​

Unexpected status 404 Not Found ​

通常是 URL 填错。Codex 请求 /v1/responses 时，Base URL 应该类似：

text
https://superapi.buzz/v1

不要填成：

text
https://superapi.buzz/v1/responses

Service temporarily unavailable ​

表示当前模型 / 分组 / 上游账号暂时不可用。处理方式：

  1. 换同系列模型。
  2. 换支持的分组。
  3. 等待账号池恢复。

context too large ​

上下文太大时，新开会话或减少附加文件。可以让 Codex 先读关键文件，不要一次性塞入整个项目。

9. 最终模板 ​

前面讲的临时变量、长期固化、auth.json、fast，最终落地是两个文件：配置写进 ~/.codex/config.toml，令牌写进 ~/.codex/auth.json——令牌不能写在 config.toml 里。

~/.codex/config.toml：

toml
model_provider = "custom"
service_tier = "fast"          # 可选：开启 fast

[model_providers.custom]
name = "custom"
base_url = "https://superapi.buzz/v1"
wire_api = "responses"
requires_openai_auth = true

令牌（写入 ~/.codex/auth.json）：

requires_openai_auth = true 时，Codex 会忽略 OPENAI_API_KEY 环境变量和 env_key，令牌只从 ~/.codex/auth.json 读取。别手动编辑这个文件，用登录命令写入即可：

bash
codex login --api-key "sk-你的令牌"

之前用 ChatGPT 账号登录过的话，先 codex logout 再执行上面的命令，否则会卡在旧登录态。

执行后 Codex 会自动生成 ~/.codex/auth.json（形如 {"OPENAI_API_KEY":"sk-你的令牌"}），也就是第 3 节说的本地鉴权缓存。

各项含义：

  • model_provider = "custom"：告诉 Codex 真正启用下面定义的 custom provider。漏了这一行，[model_providers.custom] 等于白写，请求仍会打到官方 openai（典型表现就是第 7 节的 platform.openai.com 401）。
  • base_url = "https://superapi.buzz/v1"：指向 SuperAPI 的 OpenAI 兼容地址（带 /v1）。
  • wire_api = "responses"：Codex 走 Responses 接口。
  • requires_openai_auth = true：用 OpenAI 风格鉴权（API Key 或 ChatGPT 登录），适合走中转/代理。开启后令牌只认 auth.json，所以必须用上面的 codex login --api-key 写入；第 2 节那套 export OPENAI_API_KEY 在这种模式下不生效（环境变量那套是「不开 requires_openai_auth、改用 env_key」时才用，二选一）。
  • service_tier = "fast"：可选，启用 fast 模式，会带来 2 倍或 2.5 倍计费（用 GPT-5.5 时）。注意 TOML 字符串要带引号。

SuperAPI 文档仅用于帮助用户正确配置客户端。

Copyright © 2026 SuperAPI