Codex 配置中转 API：CLI、VS Code、桌面 App 与换回官方配置

Codex 配置中转 API要同时配好五样东西：Provider、API 根、Key 来源、模型 ID 和 Responses 协议。任何一项不对，都会表现为 401、404、unsupported parameter 或流式中断。

先把 CLI 跑通，VS Code 插件和桌面 App 只需要读到同一个环境变量。中转站必须提供 /v1/responses；只有 Chat Completions 的接口不能直接给 Codex 用。

mkdir -p ~/.codex
if [ ! -f ~/.codex/config.toml.bak ]; then
  if [ -f ~/.codex/config.toml ]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.bak
  else
    touch ~/.codex/config.toml.bak
  fi
fi
export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
if (-not (Test-Path "$HOME\.codex\config.toml.bak")) {
  if (Test-Path "$HOME\.codex\config.toml") {
    Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.bak"
  } else {
    New-Item -ItemType File "$HOME\.codex\config.toml.bak" | Out-Null
  }
}
$env:GPTZZZ_API_KEY = "YOUR_GPTZZZ_API_KEY"

# 顶层键要写在第一个 [表] 之前
model = "gpt-6-sol"
model_provider = "gptzzz"

[model_providers.gptzzz]
name = "GPTZZZ"
base_url = "https://gptzzz.ai/v1"
env_key = "GPTZZZ_API_KEY"
wire_api = "responses"

mkdir -p /tmp/codex-probe && cd /tmp/codex-probe
codex exec --skip-git-repo-check --json "Reply with exactly: CODEX_OK"

New-Item -ItemType Directory -Force "$env:TEMP\codex-probe" | Out-Null
Set-Location "$env:TEMP\codex-probe"
codex exec --skip-git-repo-check --json "Reply with exactly: CODEX_OK"

“—”表示该分组不含这个模型。表中除 gpt-5.3-codex-spark 外，其余 ID 都在 Codex 0.162.0 的内置模型目录里；codex-auto-review 在价格页注明为 Codex 内部使用的审核模型。价格以 GPTZZZ 模型价格页和控制台实时显示为准。

config.toml 放哪里、Provider 字段怎么填

Codex CLI API Key 配置：env_key 只写变量名，真实 Key 留在环境变量里。Codex CLI API URL：base_url 只填 API 根，由 Codex 追加 /responses。CODEX_HOME 改过的话，目录必须已经存在。

只想改内置 OpenAI Provider 的地址时，官方另有顶层 openai_base_url；不要声明 [model_providers.openai]。中转站自己的 Key 用独立 Provider 加 env_key，不要设置 requires_openai_auth = true，否则 Codex 会忽略 env_key。想确认哪一层配置生效，在 CLI 里运行 /debug-config。

Windows / macOS 设置环境变量

Codex 只从启动它的进程环境里读 env_key 指定的变量。export 和 $env: 只对当前终端有效；要让新终端、VS Code 和桌面 App 都读到，就写成持久变量，再重开终端或应用。

macOS（从 10.15 起默认 shell 是 zsh）：

echo 'export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"' >> ~/.zshrc
source ~/.zshrc
echo "${GPTZZZ_API_KEY:0:6}"

最后一行只显示 Key 的前 6 位，用来确认变量已加载。Linux（bash）：

echo 'export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"' >> ~/.bashrc
source ~/.bashrc
echo "${GPTZZZ_API_KEY:0:6}"

Windows PowerShell，写入当前用户的环境变量（二选一）：

# 方式一：写入 HKEY_CURRENT_USER\Environment
[Environment]::SetEnvironmentVariable("GPTZZZ_API_KEY", "YOUR_GPTZZZ_API_KEY", "User")

# 方式二：setx（只对之后新开的窗口生效，值超过 1024 个字符会被截断）
setx GPTZZZ_API_KEY "YOUR_GPTZZZ_API_KEY"

关掉当前 PowerShell，新开一个窗口检查：

$env:GPTZZZ_API_KEY.Substring(0, 6)

macOS 上从 Dock 或启动台打开的 App，不一定读得到只写在 ~/.zshrc 里的变量。给桌面 App 用时，再执行一次 launchctl setenv，它只对之后由 launchd 启动的进程生效：

launchctl setenv GPTZZZ_API_KEY "YOUR_GPTZZZ_API_KEY"

注意：launchctl setenv 不是永久设置，注销或重启后就失效。每次登录后、打开 App 之前要重新执行一次；已经开着的 App 读不到新值，要按 ⌘Q 完全退出再打开。

Key 不要写进 config.toml、仓库、截图或工单。在 Windows 上让 VS Code 插件跑在 WSL 里时，按 Linux 处理：配置放在 WSL 里的 ~/.codex/config.toml，环境变量也要在 WSL 里设置。

VS Code 里的 Codex 插件怎么用中转

能用，不用另写一份配置。插件的“Codex 设置”（模型、推理强度、权限、沙箱、MCP）就是从 config.toml 读的，和 CLI 共用；编辑器自己的 chatgpt.* 设置只管界面行为，不写进 config.toml。

1. 在扩展市场安装 OpenAI 的 Codex 扩展（扩展 ID openai.chatgpt）。Cursor、Windsurf 等兼容 VS Code 的编辑器装的是同一个扩展。
2. 按上文写好 ~/.codex/config.toml，并把 GPTZZZ_API_KEY 设成持久环境变量。
3. 完全退出编辑器再打开：macOS 按 ⌘Q，Windows / Linux 关掉所有窗口。VS Code 第一个实例的环境变量继承自启动它的父进程，之后开的窗口沿用这个实例的环境，只关窗口不会刷新。
4. 打开 Codex 侧栏；找不到图标时，在命令面板运行 Codex: Open Codex Sidebar。点侧栏齿轮 → Codex Settings → Open config.toml，确认打开的就是刚才改的那份文件。
5. 发一句 Reply with exactly: CODEX_OK 验证；要换模型，在输入框用 /model。

Windows 上打开了 chatgpt.runCodexInWindowsSubsystemForLinux（让 Codex 跑在 WSL 里）时，插件读的是 WSL 里的配置，见上一节最后一段。

Codex 桌面 App 怎么用中转

OpenAI 现在的桌面端是 ChatGPT 桌面 App，在里面切到 Codex 使用。官方网关文档写明：macOS 版读同一份 ~/.codex/config.toml，Windows 版读 %USERPROFILE%\.codex\config.toml，保存后要重启 App。

1. 按“直接复制”一节写好 config.toml。
2. 让 App 进程拿到 GPTZZZ_API_KEY：Windows 用上文的用户级环境变量；macOS 用 launchctl setenv，它在注销或重启后失效，每次登录后、打开 App 前重新执行。官方提醒，只在终端里设置的变量，从桌面启动的 App 可能读不到。
3. 彻底退出 App 再打开。macOS 上按 ⌘Q，只关窗口不算。
4. 新建一个 Codex 对话，先看选中的模型，再发 Reply with exactly: CODEX_OK。

官方设置文档还写明：桌面 App 里的 Codex 继承与 VS Code 插件、CLI 相同的配置；桌面 App 和 VS Code 插件打开同一个项目时，会共享对话和编辑器上下文。

用 CC Switch 切换

CC Switch 是开源（MIT）的桌面工具，支持 Windows、macOS、Linux，可以管理 Codex、Claude Code、Gemini CLI 等工具的供应商，不用手改 TOML。项目 README 写明唯一官网是 ccswitch.io。

1. 安装：macOS 用 brew install --cask cc-switch；Windows、Linux 从 GitHub Releases 下载安装包。
2. 首次启动时，它会把现有 Codex 配置导入为名为 default 的供应商，并添加官方供应商 OpenAI Official。第一次改写配置文件前，原文件会备份到 ~/.cc-switch/backups/live-first-write/。
3. 侧栏选 Codex，点右上角“+”新建自定义供应商，填 https://gptzzz.ai/v1、GPTZZZ Key 和模型 ID（如 gpt-6-sol），然后点“启用”。
4. 切换后要重启终端或 Codex 才生效。

供应商卡片上的“检测连通”只测地址能不能连上，不发真实请求，验证不了 Key 和模型名，最后仍用上面的探针确认。

用 GPTZZZ 客户端一键配置

不想手改文件，可以用 GPTZZZ 桌面客户端（macOS / Windows）。按 v3.21.0 的更新说明：客户端只开放 Claude Code、Codex、小龙虾、爱马仕、Grok；登录后只写入列表、不再自动切换；原配置可以一键恢复。这个版本还修复了切换供应商后 Codex 对话消失的问题。

用 curl 预检 Responses 请求与响应

启动 Codex 前，直接请求同一个 API 根，能把服务端问题和 CLI 配置问题分开：

export GPTZZZ_BASE_URL="https://gptzzz.ai/v1"
export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"

curl --fail-with-body -sS -D /tmp/codex-relay-headers.txt \
  "$GPTZZZ_BASE_URL/responses" \
  -H "Authorization: Bearer $GPTZZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"Reply with exactly: CODEX_OK"}'

Windows PowerShell：

$env:GPTZZZ_BASE_URL = "https://gptzzz.ai/v1"
$body = @{ model = "gpt-6-sol"; input = "Reply with exactly: CODEX_OK" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "$env:GPTZZZ_BASE_URL/responses" `
  -Headers @{ Authorization = "Bearer $env:GPTZZZ_API_KEY" } `
  -ContentType "application/json" -Body $body

最低验收：HTTP 2xx、object 为 response、status 为 completed、输出文本非空、响应里的模型和 usage 可读，并记下请求 ID。curl 成功仍不能证明 Codex 需要的工具调用和 SSE 全部兼容。

为什么 Chat Completions 不能替代 wire_api

截至 2026-10-09，官方配置参考写明 model_providers.<id>.wire_api 唯一支持值是 responses，省略时也默认 Responses。官方网关兼容要求也写明：Chat Completions 或 Anthropic Messages 接口能用，不代表 Responses 兼容。把聊天文本包装成相似 JSON，撑不起 Codex 的 SSE、工具调用和多轮续接。

Codex CLI 验证指标与可复现实验

1. 在固定测试仓库运行 codex exec --json 的只读问答；
2. 执行一次单文件修改并运行固定测试；
3. 记录首个 JSONL 事件、首个 agent message、turn.completed 和总耗时；
4. 记录工具成功率、命令退出码、重试次数、最终 diff 与网关 request ID；
5. 主动取消一次长任务，确认恢复后不会重复执行工具。

官方基线和中转实验用同一 Codex 版本、仓库快照、提示、模型和超时。只比较回答文风或“看起来会改代码”，不能说明兼容。

401、404、参数错误与 SSE 中断排查

状态码含义见 GPTZZZ 错误码速查手册。先用 OpenAI API 接入探针验证 Responses；协议变更参考 OpenAI 兼容迁移清单；密钥隔离见 API Key 安全指南；工具与 SSE 用 流式和工具兼容矩阵复验。

用了中转怎么换回官方配置

换回官方就三件事：Codex 不再用自定义 Provider、清掉中转 Key、确认官方登录还在。

1. 停掉 Codex。退出 CLI、VS Code 插件和桌面 App 里正在跑的任务。
2. 恢复配置。有备份就复制回去（macOS / Linux：cp ~/.codex/config.toml.bak ~/.codex/config.toml；PowerShell：Copy-Item "$HOME\.codex\config.toml.bak" "$HOME\.codex\config.toml" -Force）。没有备份就删掉 model_provider = "gptzzz" 这一行和整个 [model_providers.gptzzz] 表；model_provider 不写时默认就是官方 openai。model 改成你官方账号能用的模型，不确定就删掉这行，进入 Codex 后用 /model 选。
3. 清掉中转 Key。macOS / Linux 删掉 ~/.zshrc 或 ~/.bashrc 里的那行 export，再执行 unset GPTZZZ_API_KEY；macOS 设过 launchctl 的执行 launchctl unsetenv GPTZZZ_API_KEY。Windows 见下方命令。
4. 确认官方登录。运行 codex login status。没有凭据就 codex login，在浏览器里用 ChatGPT 登录。如果你以前用 codex login --with-api-key 登录过中转 Key，先 codex logout（会清掉已保存的 API Key 和 ChatGPT 凭据）再重新登录。VS Code 插件在头像菜单里 Log out，再选 Sign in with ChatGPT；桌面 App 在头像菜单里 Log out，再选 Continue to sign in。
5. 验证。新开终端运行 codex，用 /status 看模型和 Provider；出问题时 codex doctor 会检查安装、配置和登录状态。

Remove-Item Env:GPTZZZ_API_KEY -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("GPTZZZ_API_KEY", $null, "User")
codex login status

官方登录缓存放在 ~/.codex/auth.json 或系统凭据库里，CLI 和插件共用。auth.json 里是访问令牌，按密码对待，不要提交或贴进工单。

用 CC Switch 的：切到 OpenAI Official 并重启 Codex。CC Switch 切到第三方时会把 Codex 官方登录暂存起来，切回官方时还原；用 codex login status 确认，显示未登录再运行 codex login。用 GPTZZZ 客户端配置的：在客户端里一键恢复原配置。

如果只想在 CLI 里按需用中转，可以把 [model_providers.gptzzz] 留在 config.toml，把 model_provider = "gptzzz" 和 model 挪到单独的 profile 文件 ~/.codex/gptzzz.config.toml。平时运行 codex 走官方，需要中转时运行 codex --profile gptzzz。profile 靠 CLI 的 --profile 参数选择。

官方资料

• OpenAI Codex Advanced configuration（自定义 Provider、profile）
• OpenAI Codex Configuration reference（wire_api、env_key）
• OpenAI Codex Environment variables（CODEX_HOME）
• OpenAI Codex Authentication（login、logout、auth.json）
• Codex IDE extension settings
• Use API/provider credentials through a gateway（CLI、macOS 与 Windows App）
• Gateway compatibility requirements
• OpenAI Codex Non-interactive mode
• Codex 0.162.0 内置模型目录
• OpenAI Codex Responses API proxy
• CC Switch 仓库与 README
• Microsoft setx 命令说明
• Microsoft Environment.SetEnvironmentVariable