Codex-Switch-Helper (csw)

在 官方 ChatGPT 登录 和 各种第三方 API-key 中转（anyrouter、muyuan、本地代理 …）之间一键切换 Codex 的后端，不丢失任何现有配置。纯 bash、零依赖、Mac / Linux 本地。

• 包名：codex-switch-helper（npm）
• 命令：csw

它只动两样东西，其余 ~/.codex/config.toml（MCP servers、[features]、[projects] 信任列表、 desktop 设置等）一个字不碰：

1. config.toml 里一小段「受管块」（model / model_provider / 鉴权方式）
2. ~/.codex/auth.json（ChatGPT OAuth 令牌 ↔ sk- API key）

🔐 密钥从不进仓库。 真实凭证只存在本机 ~/.codex/profiles/<名字>/auth.json（权限 600）。 本仓库只有脚本、文档和占位示例；.gitignore 还会兜底拦截 auth.json / 备份 / .active。

安装

npm（推荐）

npm install -g codex-switch-helper
csw list

从源码

git clone https://github.com/VicZhang6/codex-switch.git
cd codex-switch
./install.sh            # 把 csw / codex-switch / switch 软链到 PATH（无需 sudo）
csw list                # 验证

install.sh 只创建软链，不碰 ~/.codex/ 里任何现有内容。

首次使用

若 ~/.codex/profiles/ 还不存在，运行 csw / csw list 时会自动根据当前 config.toml + auth.json 建好第一个 profile（例如正在用 anyrouter key 就建 anyrouter；正在用 ChatGPT 登录就建 official），并补上受管标记。密钥只复制到 本机 profiles/<名>/auth.json（权限 600），不会上传。

也可手动：csw init · 再加中转：csw add。

命令速查

| 命令 | 作用 | |---|---| | csw | 交互式选单（↑↓ / j k 移动 · Enter 确认 · 1-9 直选 · q 取消） | | csw <名字> | 直接切到某 profile，如 csw official / csw anyrouter | | csw add [名字] | 向导：新建一个自定义 API-key provider（见下） | | csw list | 列出所有 profile，* 标当前 | | csw status | 显示当前 profile + 受管块 + auth 模式 | | csw init | 无 profile 时从当前 Codex 配置自动初始化（有则只展示） | | csw doctor | 检查/修复 config.toml 受管标记 |

兼容别名：源码安装后也可使用 switch / codex-switch（与 csw 相同能力）。

⚠️ 切换后要重开一个 codex 会话 / 重启 Codex App 才生效 —— Codex 在会话启动时读配置， 已开着的会话不会热加载。

工作机制

一次 csw <名字>：

1. 把当前 live auth.json 存回上一个 profile（这样 ChatGPT 的 token 刷新不会丢）；
2. 备份 config.toml 和 auth.json（带时间戳，各留最近 10 份）；
3. 用 awk 只重写 #__CODEX_SWITCH_BEGIN/END__ 标记之间的内容；
4. 把目标 profile 的 auth.json 装到 ~/.codex/auth.json（install -m 600）；
5. 更新 ~/.codex/profiles/.active。

可逆：csw official 任何时候都能切回原始 ChatGPT 登录（auth.json 来回切已验证字节级一致）。

文件结构

~/.codex/                            # ← 运行时数据（不在本仓库）
├── csw  codex-switch  switch        # 软链到本仓库（install.sh 创建；npm 只装 csw）
├── config.toml                      # 你的原配置 + 受管块 + [model_providers.*] 表
├── auth.json                        # 当前生效凭证（切换时被替换）
├── *.bak.*                          # 自动备份（各留最近 10 份）
└── profiles/
    ├── .active                      # 当前 profile 名
    ├── official/  { provider.env, auth.json }   # auth.json = 原始 OAuth 快照
    └── <其它>/    { provider.env, auth.json }

本仓库:
├── codex-switch      # 主脚本
├── csw               # 短命令入口（npm bin / 默认无参 = 选单）
├── switch            # 兼容别名
├── install.sh        # 软链到 PATH
├── package.json      # npm 包：codex-switch-helper
├── examples/         # provider.env / auth.json.example 模板
└── README.md

provider.env：

MODE=apikey            # 或 chatgpt（official）
MODEL=gpt-5.5
PROVIDER=anyrouter     # apikey 时必填，且 == config.toml 里 [model_providers.<这里>]

受管块（脚本只改这对标记之间）：

#__CODEX_SWITCH_BEGIN__
model = "gpt-5.5"
model_provider = "anyrouter"      # 切到 official 时这两行消失 → 走默认 ChatGPT
preferred_auth_method = "apikey"
#__CODEX_SWITCH_END__

provider 端点定义一次，平时惰性（只有被 model_provider 指向才生效）：

[model_providers.anyrouter]
name = "Any Router"
base_url = "https://anyrouter.top/v1"
wire_api = "responses"

新增 provider —— csw add

$ csw add CPA
显示名 (provider name=, 默认 CPA):
base_url (如 https://anyrouter.top/v1): http://localhost:8317/v1
wire_api [responses/chat] (默认 responses): chat
模型 model (如 gpt-5.5): gpt-5.5
API key (sk-...): sk-....
用 GET .../models 验证 key? [Y/n]
现在就切到 CPA? [y/N]

向导会：写好 profiles/<名>/{provider.env,auth.json}（600）→ 往 config.toml 追加 [model_providers.<名>]（已存在则跳过）→ 追加前先备份 config → 可选 GET /models 验证 → 可选当场切过去。名字只允许 字母/数字/-/_，挡保留字，已存在会问是否覆盖。

base_url / wire_api 怎么填（重要）

新版 Codex（codex#7782）只支持 wire_api = "responses"， chat 已废弃 —— 配了 chat 整个 config.toml 会拒绝加载（codex 起不来）。 因此 provider 必须支持 Responses API（<base_url>/responses）；只提供 /v1/chat/completions 的中转用不了。

| 配置 | 填法 | |---|---| | base_url | 带版本前缀，如 https://host/v1（codex 会 POST 到 <base_url>/responses） | | wire_api | 固定 responses |

• 漏了 /v1 → codex POST 到错路径报 404。
• 验证某中转是否支持 Responses： curl -X POST http://host/v1/responses -H "Authorization: Bearer <key>" -H 'content-type: application/json' -d '{"model":"gpt-5.5","input":"hi"}' → 200 即可用。

排错

| 现象 | 处理 | |---|---| | ⚠ MCP client for 'paper' failed to start | 无害，与切 provider 无关；Codex 桌面端 paper MCP 没在跑而已，codex 照常继续。要消掉就在 config.toml 把 [mcp_servers.paper] 设 enabled = false。 | | wire_api = "chat" is no longer supported（codex 起不来） | 新版 Codex 删了 chat（codex#7782）；把该 provider 改 wire_api = "responses"（provider 须支持 Responses API）。 | | unexpected status 404 ... /responses | base_url 漏 /v1；codex 会 POST 到 <base_url>/responses，确认中转支持该端点，再重开 codex 会话。 | | 改了配置但没变 | 旧会话不热加载，重开 codex / 重启 App。 | | csw add 里 GET /models 非 200 | 不一定 key 无效 —— 有些中转不实现 /models 或严格校验格式。anyrouter 这类 /responses 通道只能用真实 codex 客户端验证（手搓 curl 会被判 invalid codex request 假阴性）。最终以 codex 真跑一把为准。 | | 验证某中转能用 | csw <名> 后：codex exec --skip-git-repo-check -c 'mcp_servers={}' "print: OK" |

和 Loongphy/codex-auth 的区别

• codex-auth：多 ChatGPT/OpenAI 账号切换（换身份、看额度），不改 config.toml，做不到指向第三方中转。
• Codex-Switch-Helper（csw / 本项目）：多 provider 切换（官方登录 ↔ 第三方中转 key，连 base_url/模型一起换）。 解决的是不同问题，命令也不撞名，可共存。