在官方 ChatGPT App 与自建网关之间切换 Codex：一套可回退的 macOS 方案

让 Codex 在官方 ChatGPT OAuth 与自建 OpenAI 兼容网关之间可验证、可回退地切换。

工程笔记 · 2026-07-24 · 约 6 分钟阅读 · 标签：OpenAI Compatible、Codex、ChatGPT、macOS

OpenAI 的 Codex CLI 和 ChatGPT macOS App 中的 Codex 功能会读取用户目录下的配置。只要自建网关兼容 OpenAI Responses API，就可以让 Codex 的代码任务经自定义接口运行；需要官方能力时，再切回 ChatGPT OAuth。

这篇文章记录一套可回退的全局切换方案，同时解释它与隔离 CODEX_HOME 启动方式的区别。

提醒：这不是修改 ChatGPT 普通聊天模型。它影响的是读取 ~/.codex 的 Codex 运行时。自定义 OpenAI 兼容网关通常只适合文本和代码任务，不能保证承载官方 App 内置的浏览器、Computer Use、文档、图片等专有插件。

Codex 读取哪些文件

默认 Codex Home 为：

~/.codex

两个关键文件是：

~/.codex/config.toml
~/.codex/auth.json

config.toml 保存模型、Provider、Base URL、Responses API 类型等配置；auth.json 保存官方 OAuth 或 API Key 鉴权状态。

因此，全局切换的本质就是：成对切换配置和鉴权。

为什么不能只改 Base URL

如果只把 base_url 改成自建网关，但 auth.json 仍是 chatgpt OAuth，Codex 可能继续尝试官方登录逻辑。反过来，如果只写 API Key、不指定自定义 Provider，也不会自动使用自建接口。

可靠切换需要同时处理：

官方模式：官方 config + ChatGPT OAuth auth
网关模式：自定义 config + API Key auth

切换前先验证网关

Codex 默认依赖 /v1/responses，所以不能只测试 /v1/chat/completions。

模型列表

curl https://gateway.example.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

Responses API

curl https://gateway.example.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.6-sol",
    "input":"Reply exactly: RESPONSES_OK",
    "max_output_tokens":20
  }'

至少确认：

  • HTTP 200；
  • 状态为 completed；
  • 返回内容正确；
  • 模型没有被静默替换。

自定义 Provider 配置

网关模式的 config.toml 可以写成：

model = "gpt-5.6-sol"
model_provider = "my-gateway"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.my-gateway]
name = "My OpenAI-Compatible Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
request_max_retries = 3
stream_max_retries = 3
stream_idle_timeout_ms = 300000

API Key 不应写进 TOML。切换脚本把它写进权限为 600 的 auth.json：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "<API_KEY>"
}

为什么要备份官方 OAuth

官方 ChatGPT 登录包含可刷新 Token 和账户信息。切换自建接口前必须完整备份：

~/.codex/profiles/official.config.toml
~/.codex/profiles/official.auth.json

文件权限应限制为当前用户：

chmod 600 ~/.codex/profiles/*

不要把这些文件提交到 Git，也不要把内容发到聊天记录、Issue 或截图里。

全局切换器

可以制作一个简单命令：

codex-switch official
codex-switch sub2api
codex-switch status

它分别执行：

official

  • 恢复官方 config.toml；
  • 恢复 ChatGPT OAuth auth.json；
  • 保持文件权限为 600。

sub2api

  • 写入自定义 Provider 配置；
  • 从受保护的环境文件读取 API Key；
  • 生成 API Key 模式的 auth.json；
  • 不在终端输出 Key。

status

只输出：

current=official-chatgpt

或：

current=sub2api model="gpt-5.6-sol"

不显示任何凭据。

全局切换与隔离启动的区别

这两个方案不要混淆。

全局切换

修改 ~/.codex/config.toml 和 auth.json

特点：

  • 终端 Codex 会改变；
  • ChatGPT App 中读取同一 Codex Home 的运行时也会改变；
  • 切换后建议新建会话；
  • App 已经打开时，最好完全退出并重开。

隔离启动

CODEX_HOME=~/.codex-gateway codex

特点：

  • 只影响这个终端进程；
  • 不覆盖官方 OAuth；
  • 不改变已打开的 ChatGPT App；
  • 适合同时保留多个 Provider。

我的实际使用方式是：日常 CLI 优先隔离启动；需要让 App 的 Codex 走网关时，才执行全局切换。

自定义网关模式下应禁用的插件

官方 App 的部分能力依赖 OpenAI 专用服务，不是标准 Responses API 的一部分。例如：

  • Browser / Chrome；
  • Computer Use；
  • Documents；
  • PDF；
  • Spreadsheets；
  • Presentations；
  • 图像相关工具。

自定义配置中应显式禁用这些插件，避免 Codex 发出网关无法理解的工具调用：

[plugins."browser@openai-bundled"]
enabled = false

[plugins."computer-use@openai-bundled"]
enabled = false

[plugins."documents@openai-primary-runtime"]
enabled = false

切回官方配置后再恢复它们。

真实验收

配置完成后必须运行一次 Codex，而不是只查看文件：

codex exec --skip-git-repo-check \
  'Reply with exactly: CODEX_GATEWAY_OK'

启动信息应明确显示：

model: gpt-5.6-sol
provider: my-gateway

并最终返回：

CODEX_GATEWAY_OK

还应测试切回官方：

codex-switch official
codex-switch status

确认 OAuth 文件完整恢复。

常见问题

1. Missing environment variable

TOML 中配置了 env_key，但官方 App 不是从你的交互式 shell 启动，无法继承该环境变量。

解决方案：全局切换时正确生成 auth.json，不要依赖 shell 临时 export。

2. 终端成功，App 不生效

通常是 App 仍在使用旧进程中的配置。完全退出 App，重新打开并新建 Codex 会话。

3. /chat/completions 正常，Codex 仍失败

大概率是 /responses 不兼容。Codex Provider 应设置：

wire_api = "responses"

同时真实测试 /v1/responses。

4. 官方插件报错

自建网关只能处理标准文本/工具协议，不能等价替代 OpenAI 专有后端。自定义模式下禁用不支持的官方插件。

小结

要让 Codex 在官方 ChatGPT 与自建网关之间可靠切换，需要同时满足四个条件：

  1. 网关真实支持 Responses API；
  2. 模型名与上游保持透明；
  3. config.toml 和 auth.json 成对切换；
  4. 官方 OAuth 有安全备份并能一键恢复。

不要用覆盖官方文件却没有备份的脚本，也不要把 API Key 硬编码进配置。把全局切换和隔离启动分清楚，就能同时保留官方体验与自建路由的灵活性。

全部文章 · 返回 OneMJJ 首页

OneMJJ · 少踩坑，多留传家宝 · Public tools first.