「切回官方登录」是怎么实现的：CC Switch 里 official 类预设的机制

把某个 CLI 从第三方供应商切回官方账号——这个动作听起来应该是「写入一份官方配置」。但把 CC Switch 的仓库翻开会发现，它做的事情基本是反过来的：official 类预设本身几乎是空的，而切过去之后，后端还得再跑一段专门的清理代码，把上一家留下的凭据从本机文件里擦掉。

下面这些位置都来自我们采集的仓库快照：farion1231/cc-switch，HEAD c39c903，采集日 2026-08-10，package.json 与 src-tauri/Cargo.toml 里的版本号是 3.19.2。文中提到的行号按这个快照写，你可以自己 clone 下来逐行对。

一、official 预设的正文，是三处「空」

先看 Claude Code 那条。src/config/claudeProviderPresets.ts:77-93 的官方预设，settingsConfig 写的是 { env: {} }——一个空的环境变量对象，isOfficial: true、category: "official"。也就是说这条预设不携带 base_url、不携带 key、不携带模型映射，它的全部内容就是「什么都不设」。

Grok Build 那条更明确，而且它不在预设数组里，是数组外的一个单独常量 grokBuildOfficialPreset（src/config/grokBuildProviderPresets.ts:42-54）：config: ""、auth: {}。它上面那段注释把语义写死了——空 config 意味着不写自定义模型表，Grok CLI 会回落到它自带的 xAI OAuth 登录；并且这条预设的 id 复用了固定的 provider id，添加供应商的对话框据此走 ensure seed 流程。

这是理解整套机制的钥匙：「切回官方」不是让 CC Switch 替你登录，而是让它把手从配置文件上拿开，让 CLI 自己回到原来的登录路径上去。 所以预设内容当然是空的——写任何一个字段进去都是在继续接管。

src/config/grokBuildProviderPresets.test.ts:12-74 里那六个 vitest 用例还给这件事加了两道锁：一条断言预设数组内不含 official / cn_official 分类，也不含 isOfficial；另一条断言官方常量保持空 config 与空 auth。也就是说「官方条目必须留在数组外，而且必须是空的」这件事，在仓库里是有测试兜底的。

二、切过去之后，还要擦一遍

真正反直觉的一段在切换流程里。src-tauri/src/services/provider/mod.rs:3148-3175：当应用类型是 Codex、回填成功、且目标供应商的 category 是 official 时，后端会额外调一次 clear_stale_codex_live_auth_after_official_switch。

代码注释把原因写得很直白：一个不带任何材料的 official Codex 供应商，落盘时只会写配置，不会覆盖 ~/.codex/auth.json，于是上一家第三方供应商的 key 会原样留在那个文件里——用户会卡在 401，而且没有登录界面可回。这段清理还挂着两个前提：一是它只在回填成功之后才做，回填这一步没成功就不动 auth.json；二是清理本身失败只降级为一条日志，不会让整次切换报错。

这一段是 official 机制里最容易被忽略、也最值得记住的地方：空配置只能保证不写入新的东西，不能保证旧的东西被清掉。 它落在 Codex 这条路径上，是因为 Codex 的凭据与配置分在 auth.json 与 config.toml 两个文件里，写其中一个不会动另一个。

顺带说清一件事：~/.codex/auth.json 是你本机上的真实凭据文件，CC Switch 会读写它。任何涉及这个文件的操作，包括上面这段清理，动的都是本机敏感数据。仓库里也没有承诺过什么「清干净了就安全」，我们同样不做这种保证。

三、「官方」这个身份，各应用是靠不同字段认出来的

如果你以为全仓有一个统一的「是不是官方」标记，翻一圈会有点意外。就我们读到的这几处，至少有三套判定：

• 靠分类与布尔字段：Claude Code 的官方预设用 category: "official" 加 isOfficial: true（src/config/claudeProviderPresets.ts:77-93）。
• 靠固定的 provider id：后端在 src-tauri/src/database/dao/providers_seed.rs:15-16 定义了 CODEX_OFFICIAL_PROVIDER_ID = "codex-official" 与 GROKBUILD_OFFICIAL_PROVIDER_ID = "grokbuild-official" 两个常量；前端在 src/utils/providerCapabilities.ts:10-11 有同名同值的一份。
• 靠推广标记：Gemini 的官方预设 partnerPromotionKey 取值 "google-official"，description 写的是「Google 官方 Gemini API (OAuth)」（src/config/geminiProviderPresets.ts:36-51）；后端的认证类型检测 GeminiAuthType 有三个取值，其中两个是 GoogleOfficial 与 Generic，还有一个是针对某个具体第三方服务的特判（本文不列服务商名称），判定时优先看 meta.partner_promotion_key（src-tauri/src/services/provider/gemini_auth.rs:13-50）。

这里还有一处数字上的差异，照实记下、不做推断：我们对八个预设文件做字段出现次数统计时，isOfficial 只在 Claude（1 次）、Codex（2 次）、Hermes（1 次）出现；而 category: "official" 的条目在 Claude、Codex、Gemini、Grok Build、Hermes、Claude Desktop 六个应用里各是 1 条。也就是说这两个信号并不总是成对出现——isOfficial 是可选字段，我们把两组统计并列在这里，不做推断。

另外，ProviderCategory 一共 8 个取值，official 是其中之一；而 OpenClaw 与 OpenCode 两个应用的预设里没有任何 official 分类条目（各 60 条的分类分布统计）。

四、official 的另一面：它是「不接管」

official 分类在这套代码里还承担了一个反向作用——把本地代理路由关掉。

路由的权威判定在 src/utils/providerCapabilities.ts:39-82 的 providerNeedsRouting()，函数体的第一条分支就是：category === "official" 直接返回 false。UI 上对应的是一枚「不支持路由」徽章，i18n key 为 claudeCode.noRoutingSupport（src/components/providers/ProviderCard.tsx:370-400）。

后端更进一步。src-tauri/src/services/provider/mod.rs:3020-3031：当代理接管已经开启时，切到 official 分类的供应商会被直接拒绝，返回错误 key switch.official_blocked_by_proxy，中文文案是「代理接管模式下不能切换到官方供应商，使用代理访问官方 API 可能导致账号被封禁」。

这条拒绝有一个例外口子：后端的 official_provider_supports_proxy_takeover（src-tauri/src/services/provider/mod.rs:49），前端有条同源规则 supportsOfficialProxyTakeover（src/utils/providerCapabilities.ts:14-23），后者只在 appId === "codex"、provider.id === "codex-official"、category === "official" 三个条件同时成立时返回 true。也就是说，整套 official 里目前只有 Codex 官方这一条留了口子，其余一律挡下。同一条例外规则在后端与前端各存了一份，属于需要手工对齐的两处，改一边就得看另一边。

五、想自己核一遍，做这几个动作

1. 打开 src/config/claudeProviderPresets.ts:77-93，确认 settingsConfig 是不是 { env: {} }，以及 isOfficial 与 category 两个字段是否同时存在。
2. 打开 src/config/grokBuildProviderPresets.ts:42-54，看官方常量是不是在预设数组之外，config 与 auth 是不是空的；再翻 src/config/grokBuildProviderPresets.test.ts:12-74 里对应的两条断言。
3. 把 src-tauri/src/database/dao/providers_seed.rs:15-16 与 src/utils/providerCapabilities.ts:10-11 两处并排看，确认前后端两份 provider id 常量的字符串值一致——这是跨语言的手工对齐点，值得盯。
4. 读 src-tauri/src/services/provider/mod.rs:3148-3175 这段调用点，特别注意「回填成功才清理」与「清理失败只记日志」这两条前提。
5. 读 src/utils/providerCapabilities.ts:39-82 的第一条早退分支，再对照 src-tauri/src/services/provider/mod.rs:3020-3031 的拒绝逻辑与 :49 的例外函数，看两侧结论是否一致。

如果你查到的现象与上面对不上，先确认版本：这些行号绑在 c39c903 这个快照上，仓库仍在快速迭代，行号与默认值都可能已经变了。

六、边界：有几件事本文不写

• 不给规避条款的建议。 上面所有内容都只是在描述仓库源码与文档写了什么。官方账号怎么用、能不能多开、代理访问官方 API 的后果如何，请以各平台自己的服务条款为准；仓库里那句「可能导致账号被封禁」是代码里的原文，不是我们的建议。
• 不做调参建议。 official 这条路径上没有可调阈值，真正需要你决策的是「要不要开代理接管」，而这取决于你的用法，项目没给通用值。
• 分类字段本身的漏填问题另有专文。 我们统计到 Codex 67 条预设里有 3 条没有 category、Grok Build 37 条里有 2 条没有 category，而 official 判定与路由徽章都依赖这个字段——这条线索这里只点到为止。
• 我们没读到的部分照实说。 providers_seed.rs 我们只读了那两行常量，seed 的完整内容没读；mod.rs 全文 4722 行，我们只精读了切换、删除、通用配置提取等约 600 行；clear_stale_codex_live_auth_after_official_switch 的函数体实现本身也没有展开读，本文只采信调用点的注释。

---

本文依据 CC Switch 官方仓库（github.com/farion1231/cc-switch）的 README、docs/ 下的用户手册与发布说明、src/config/ 的预设定义与 src-tauri/src/ 的后端源码整理，核对日 2026-08-10，对应仓库快照 c39c903。本文内容为仓库源码与文档口径，我们没有安装或运行过这个桌面应用，因此不涉及界面外观、操作手感与切换速度的任何描述。文中出现的阈值与默认值均为源码中的默认配置，不构成对实际运行结果的保证。该项目仍在快速迭代，版本与默认值随时可能变动，请以仓库最新内容为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。