CC Switch 中 Codex 第三方切换机制解析：config.toml 承载密钥、auth.json 只管官方登录-育师

CC Switch 中 Codex 第三方切换机制解析：config.toml 承载密钥、auth.json 只管官方登录

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

本文基于 CC Switch 仓库中的 CHANGELOG.md、codex_config.rs、Codex 官方认证保留攻略与 v3.20.1 / v3.16.1 Release Note 整理。读完你能判断：把 Codex 切到 DeepSeek、Kimi、GLM 等第三方 API 时，密钥到底写进哪个文件、auth.json还会不会被覆盖、什么情况下切换会被提前拒绝，以及这些行为对"边用第三方模型、边保留官方远程操作"的用户意味着什么。

一个决定：密钥跟着 provider 走，不再借用 ambient 登录

核心变化是第三方 Codex 切换从"写auth.json"改为"写config.toml的 provider 表"，且这一行为在 v3.20.1 起成为无条件默认。在 v3.20.1 之前，默认模式下第三方密钥被写进~/.codex/auth.json，provider 靠"环境里恰好有一份登录"来继承凭据；从 v3.20.1 起，密钥改写入config.toml当前 provider 下的experimental_bearer_token，auth.json退回为"纯粹的官方 ChatGPT 登录文件"。CHANGELOG.md 的 v3.20.1 一节把这一改动列为本版本主线，并直接点名了触发它的上游变更。

为什么旧写法会坏：Codex 0.149 关掉了凭据继承

旧写法不是 CC Switch 主动想改，而是被 Codex 0.149 的一个上游变更逼出来的。CHANGELOG.md 记载：Codex CLI 0.149 起，自定义 provider 不再从auth.json继承环境凭据——而旧默认模式恰好只把密钥写进auth.json，于是第三方切换在客户端侧变成 401。换句话说，auth.json曾经是"官方登录 + 第三方密钥"的共用槽位，一旦上游不再读它来给第三方鉴权，这条继承链就断了。

从这条记录可以推断，CC Switch 选择把密钥下沉到 provider 自己的config.toml表，而不是继续往auth.json里塞——这样既修掉 401，又让auth.json重新只承担官方登录一种职责，两种身份不再挤在同一个文件里。experimental_bearer_token自 Codex 0.48 起被官方读取，这是该字段可用的前提，CHANGELOG.md 在 v3.20.1 升级提醒里也据此要求旧于 0.48 的 Codex 升级。

机制核心：两个文件、一条 provider-scoped 令牌、一个占位符

理解这套机制只需盯住两个文件和一处占位符。

两个文件各管一件事

Codex 的配置分两个文件，职责被刻意拆开（见攻略"背后的原理"一节）：

~/.codex/auth.json：官方 ChatGPT / Codex 登录缓存，Codex App 识别官方账号、手机远程操作、官方插件都靠它。
~/.codex/config.toml：当前模型、base URL、模型目录，以及 provider 级 token 等运行配置。

切换第三方供应商后，写出来的config.toml形态如下（取自攻略）：

model_provider = "custom" [model_providers.custom] name = "DeepSeek" base_url = "https://api.deepseek.com" wire_api = "responses" experimental_bearer_token = "sk-..."

auth.json保持官方登录不变，模型请求则按config.toml的model_provider与base_url走第三方 API。provider 表用的是固定 idcustom，由 codex_config.rs 中的CC_SWITCH_CODEX_MODEL_PROVIDER_ID常量定义。

接管场景下的 PROXY_MANAGED 占位符

当 CC Switch 的本地路由接管 Codex 时，真实第三方密钥并不落进 live 文件，而是用占位符PROXY_MANAGED顶替，请求经过本地代理时再按请求注入真实 token。该占位符由 codex_config.rs 的CODEX_PROXY_AUTH_PLACEHOLDER定义，同时被extract_codex_managed_oauth_account_id用作判断"这是代理托管、可被清空"的信号之一。设计取舍在于：占位符是 CC Switch 的所有权标记——它只清理自己写入的值，绝不动用户手填的 key。

一个开关决定 auth.json 的去留

"Keep official login for direct switches"（切换第三方时保留官方登录）这个开关，只决定auth.json在第三方切换时是被保留还是被删除，不再决定密钥写到哪里。v3.20.1 之后密钥恒定进config.toml，开关的语义被收窄为对auth.json的处置（见 CHANGELOG.md v3.20.1 Changed 一节）：

开关 ON：ChatGPT 登录在第三方切换中完全不被触碰，auth.json原样保留——这正是"第三方模型 + 官方远程操作"共存用户需要的状态。
开关 OFF（默认）：切换第三方时删除auth.json，而不是像更旧版本那样用 API key 覆盖它；删除失败会给出"官方登录仍在盘上"的警告。

这一开关的默认值有过一次明确的回调。v3.16.0 让官方认证保留默认开启，但部分用户不希望它改变配置文件写入方式，于是 v3.16.1 Release Note 把它改成默认关闭，以维持 v3.16.0 之前的兼容行为。从这条回调可以推断，项目对"是否动auth.json"采取保守策略：拿不准就保持旧行为，把选择权交给用户。

开关只影响auth.json，不影响"密钥进config.toml"这一事实。即便 OFF，第三方模型照常可用，区别仅在于切换后官方登录态是否还在盘上。

两道前置安全门：宁可拒绝切换，也不留半成品

每次第三方切换前都会跑两道 preflight，命中即拒绝，而不是写出一个 Codex 起不来的"看似成功"的切换。CHANGELOG.md v3.20.1 列出了这两道门，源码测试在 provider/mod.rs 中有对应断言（"third-party switches are config-only: auth.json is removed"）：

前置检查	拒绝条件	为什么必须拒
无处安放密钥	密钥存在，却没有 provider 表来承载它	没有`experimental_bearer_token`的落点，密钥只能回到`auth.json`，等于退回旧坏路径
无凭据借用官方登录	`requires_openai_auth = true`但无自身凭据，或仅一个裸`openai_base_url`重定向	这种配置靠"官方登录兜底"才能工作，一旦`auth.json`被删就彻底失效，属静默失败

此外，live 写入的校验被移到了current指针移动之前执行。旧顺序是先移动指针、再在写入层被拒，导致被拒 provider 的存储配置被回填成旧的 live 值；新顺序保证"指针没动 = 存储没被污染"。CHANGELOG.md 把这条列为独立修复。

配置与行为速查

项	类型 / 取值	默认	作用
`experimental_bearer_token`	`config.toml`字符串	无	provider 级密钥，自 Codex 0.48 被读取，v3.20.1 起第三方切换的密钥落点
`model_provider`	`config.toml`字符串	`custom`	指向`[model_providers.custom]`表，常量见 codex_config.rs
`requires_openai_auth`	`config.toml`布尔	按登录态	ON 表示"无自身凭据时借用官方登录"，是安全门检测的字段之一
`PROXY_MANAGED`	live 文件占位符	接管时写入	代理接管期的所有权标记，请求时注入真实 token
Keep official login	设置开关（布尔）	OFF	ON 保留`auth.json`，OFF 删除`auth.json`
Codex 版本下限	客户端版本	0.48	低于 0.48 不读 provider 表 token，第三方鉴权失效

你需要做什么

多数用户什么都不用做：只要把 Codex 升到 0.48 以上（建议直接跟最新），第三方切换就会自动走 config-only 路径。

要"第三方模型 + 官方远程操作 / 官方插件"共存：先把 Codex 切回OpenAI Official完成一次官方登录，再到设置 → 通用 → Codex 应用增强打开"切换第三方时保留官方登录"，然后切第三方供应商（步骤见攻略）。
第三方供应商只支持 Chat Completions（DeepSeek / Kimi / MiniMax 常见路径）：额外开启本地路由并启用 Codex 接管，让 CC Switch 把 Responses 请求转成 Chat 请求；原生 Responses 上游则可直连，无需接管。
改完模型映射记得重启 Codex：模型目录在客户端启动时加载，/model菜单通常要重启才刷新。
若你的卡片是"空配置第三方"或"裸openai_base_url重定向"，切换会在 preflight 被拒——这类卡片以前是骑在auth.json上静默工作的，现在需要补一个真正的[model_providers.<id>]表或 API key。

测试与证据链

该行为被多层测试锁住，可作为复核入口：

provider/mod.rs 的managed_codex_switch_adopts_outgoing_cli_rotation_before_account_or_key_overwrite等用例，断言"第三方切换是 config-only、auth.json被移除"，并覆盖切走前采纳 CLI 自行轮换的 refresh token 的顺序。
proxy.rs 的热切换与接管系列用例（如codex_takeover_hot_switches_between_builtin_official_and_third_party、codex_active_takeover_hot_switch_failure_restores_native_official_auth）锁定接管/非接管两条路径下auth.json的保留、替换与失败回滚。
codex_config.rs 中CodexLiveStateSnapshot::restore_preserving_newer_same_account_auth的"代次比较"逻辑，保证跨账号写入失败时精确回滚，而不会把同账号刚刷新的 token 一并卷回。