🔀 CC Switch

版本：v3.19.1 / macOS

官网：ccswitch.io ｜ 仓库：farion1231/cc-switch

CC Switch 是一个 Tauri 写的跨平台桌面工具，用来统一管理 Claude Code、Codex、Gemini CLI、OpenCode、Grok Build 等多款 AI CLI 工具的配置。

核心能力是一键切换供应商：把官方 Anthropic、各类中转站的 base URL + API Key + 模型 存成配置档，选中后它直接改写对应 CLI 的配置文件，下次启动就用新供应商，不用手动改环境变量。

下面按软件自身的界面结构逐块记录，包含实测验证和踩到的认知误区。

🏠 主页

项目切换

v3.19 引入的"工作环境快照"功能。把当前的一整套环境——供应商配置、MCP 服务器、Skills、记忆文件——打包保存为一个命名的项目，之后在标题栏或托盘里一键切换到另一套，切换时自动保存当前状态。

比单纯的供应商切换更进一步：切的不只是 API 供应商，而是整个工作上下文。比如"公司项目"用公司网关 + 团队 MCP + 团队规范，"个人项目"用自己的 API + 另一套 Skills，两套环境互不污染。

用不到的话可以在 设置 → 通用 → 主页显示 里关掉，托盘菜单和已有项目数据不受影响。

➕ 添加供应商

主页点「添加」进入的表单，是整个软件里字段最多的一页。顶部先分两个标签：Codex 供应商（生成 Codex 专属的 auth.json + config.toml）和统一供应商（跨应用通用的配置）。

这一页在做什么

本质是登记一家"卖 AI 服务的店"，登记完主页才能把它列出来供你切换。一家店的核心信息只有三样：

1. 去哪找它 —— API 请求地址
2. 凭什么让你用 —— API Key
3. 用它家哪个模型 —— 默认模型

剩下所有字段都是围绕这三样打转的。

预设与自定义配置

预设列表有 60 多家，涵盖官方（OpenAI Official、DeepSeek、Zhipu GLM、MiniMax、xAI）、云厂商（Azure OpenAI、Baidu Qianfan、Bailian、火山 Agentplan、BytePlus、Novita、Nvidia）和各类中转站（PackyCode、ZetaAPI、AiHubMix、OpenRouter、SiliconFlow 等）。卡片上的 ❤️ 和 ⭐ 是收藏与推荐标记，右上角可搜索和排序。

点预设 = 自动填好请求地址和上游格式，你只需要补一个 API Key，省的是查文档的功夫。

列表第一个「自定义配置」是给预设里没有的服务用的，所有必要字段手动填。自建网关一定走这里——你的服务器地址只有你自己知道。

基本字段

字段	说明
供应商名称	显示用，随便起
备注	如"公司专用账号"，多账号时用来区分
官网链接	可选，方便从软件里跳去充值或看文档
API Key	提示写着"只需要填这里，下方 auth.json 会自动填充"——不用手动去改 auth.json
API 请求地址	旁边有「完整 URL」开关：关闭时填到 /v1 由 CC Switch 补全路径，打开时填完整端点
默认模型	Codex 默认请求的模型，随时可改，不用等预设更新。留空且配了模型映射时，默认用映射第一行

上游格式

这是这一页最重要、也最容易忽略的一项。

背景：不同的 AI 服务"说不同的方言"。 业界目前主要有三种协议：

方言	谁在说
Responses	OpenAI 较新的接口，Codex 只会说这一种
Chat Completions	最通用的老方言，绝大多数中转站、国产模型都说这个
Anthropic Messages	Claude 原生的方言

于是问题来了：Codex 只会说 Responses，但你想用的那家店只会说 Chat——语言不通怎么办？

「上游格式」就是告诉 CC Switch 对方说的是哪种方言：

• 选 Responses（原生） = "对方跟 Codex 同一种话" → 直连，不转换；
• 选 Chat 或 Anthropic Messages = "对方说别的话" → 需要有人当翻译。

翻译只能由路由代理来做

界面上明说了：Chat 与 Anthropic Messages 均需开启路由接管才能转换为 Responses。

对照前面讲的两种模式就明白了：

• 普通模式下 Codex 直连对方，中间没有任何人，谁来翻译？没人。选了 Chat 却没开路由，请求发出去就是鸡同鸭讲，直接失败。
• 路由接管下请求先经过本地代理，代理就是那个翻译：接过 Codex 的 Responses 请求，转成 Chat 发给对方，再把回答转回来。

这就是"路由接管能做更聪明的事"的具体落地——协议转换必须有中间人，普通模式没有中间人。

同理，「自定义 User-Agent」和「本地代理请求覆盖」下面都写着"仅在开启本地路由/代理接管后生效"，原因完全一样：这些都是在转发的路上动手脚，没有中间人就无从动手。

其余高级选项

模型映射——生成 Codex 的 model_catalog_json，让 /model 命令能列出这些第三方模型名。可以「获取模型列表」自动拉取，也可以手动添加，表中条目按填写内容原样保存。改完需要重启 Codex 才会刷新。

自定义 User-Agent——仅路由接管后生效，替换转发到供应商 API 请求中的 UA。某些中转站按 UA 做识别或限制时用得上。

本地代理请求覆盖——仅路由接管后生效，应用于协议转换后的上游请求，分 Header 覆盖和 Body 覆盖两个 JSON 输入框。例如统一注入一个标识头，或强制给所有请求加上 "temperature": 0.2。

配置文件直编

表单下半部分把 Codex 的两个真实配置文件直接嵌了进来：

• auth.json（JSON）——凭证文件。上面填了 API Key 后这里的 OPENAI_API_KEY 会自动填充，正常不用手动碰。
• config.toml（TOML）——完整配置，包含 model_provider、wire_api、requires_openai_auth，以及 MCP 服务器、插件开关、项目信任级别、桌面端偏好等一大堆内容。

config.toml 右上角有三个选项：

选项	作用
启用 Goal mode	开启 Codex 的目标模式
启用远程压缩	上下文压缩交给远端处理
应用通用配置	套用「编辑通用配置」里维护的公共段落

「应用通用配置」这个设计值得留意：config.toml 里那一大堆 MCP 服务器、插件开关、项目信任级别对所有供应商都一样，勾上它就自动套用公共那一份，不用每加一家店重抄一遍。和前面 AI 手册想要的"一份原件、多处复用"是同一个思路，只不过 CC Switch 在这里做到了。

计费配置

最底部可为该供应商单独配置计费参数（默认跟随全局），用于「使用统计」页把 token 用量换算成花费。不同中转站价格不一样时才需要单独配。

🔌 实例：接入自建的 New API

New API 是 one-api 的衍生版，一个开源的 AI 接口管理与分发系统。自己部署一套，在里面配好多家上游渠道，对外只暴露一个地址 + 一个令牌。

不用它的时候，每家供应商都要在 CC Switch 里单独登记：

CC Switch ──> 中转站A（一个地址、一个 Key）
          ──> 中转站B（另一个地址、另一个 Key）
          ──> DeepSeek（又一个）

用了之后，中间多一层收口：

CC Switch ──> New API（自建网关）──┬──> 中转站A
                                    ├──> 中转站B
                                    └──> DeepSeek

在 CC Switch 里的填法

1. 选列表第一个「自定义配置」（自建的，预设里不会有）；
2. 供应商名称：如 New API 自建；
3. API 请求地址：https://你的域名/v1；
4. API Key：在 New API 后台「令牌」页生成的 sk-...；
5. 默认模型：填 New API 渠道里实际配好的模型名；
6. 上游格式：看网关对外暴露什么协议。New API 主要提供 OpenAI Chat Completions，所以通常选 Chat，并且必须开启本地路由接管，否则 Codex 的 Responses 请求没人翻译。只有当版本已支持 Responses 直通时，才能选 Responses（原生）。

为什么值得插这一层

• 收口：多家上游统一成一个地址一个 Key，CC Switch 里只配一个供应商；
• 换上游不用动客户端：在网关后台改渠道即可，CC Switch 和 CLI 全程无感；
• 集中管控：令牌额度、分组、模型限流都在网关侧；
• 有完整的调用日志和用量统计，排查和对账都方便。

代价也要认：多一跳延迟；网关本身要部署维护；出故障时排查环节变多（是 CLI、CC Switch 路由、网关，还是上游）。

⚙️ 设置 · 通用

主页显示

三个纯 UI 开关，控制主页顶部摆不摆这些快捷入口，不影响功能本身：

开关	作用
显示项目切换	主页顶部显示项目切换器
显示本地路由开关	主页顶部显示路由和故障转移开关
显示故障转移开关	主页顶部独立显示故障转移开关

关掉后功能依然可以从设置或托盘菜单访问。

Skills · 存储位置

这个开关决定 Skills **源文件（SSOT，单一事实来源）**放在哪里：

选项	路径	特点
CC Switch 内置存储	~/.cc-switch/skills/	由 CC Switch 独占管理，封闭，其他工具不知道它的存在
Agents 共享目录	~/.agents/skills/	社区通用的 Agent 工具共享标准目录，多个工具可共用同一套 skills

❓ 疑问：切换存储位置到底动了什么文件？

直接实测。切换前：

ls ~/.cc-switch/skills/ | wc -l   # 165
ls ~/.agents/skills/   | wc -l   # 0
ls -la ~/.claude/skills/
# accessibility-testing -> /Users/anthony/.cc-switch/skills/accessibility-testing
# xingxing              -> /Users/anthony/.cc-switch/skills/xingxing

在界面上点了切换，切换后：

ls ~/.cc-switch/skills/ | wc -l   # 0
ls ~/.agents/skills/   | wc -l   # 165
ls -la ~/.claude/skills/
# accessibility-testing -> /Users/anthony/.agents/skills/accessibility-testing
# xingxing              -> /Users/anthony/.agents/skills/xingxing

实际表现：这个开关做了三件事——把源目录里所有 skill 原件整体搬家、把旧仓库清空、再把已启用 skill 的软链接重新指向新家。对 Claude Code 完全无感，它还是从 ~/.claude/skills/ 顺着链接找到原件，只是链接指向变了。这就是文档说的"平滑迁移、不丢状态"。

❓ 疑问：搬来搬去意义何在？

意义不在搬家本身，在于新家是谁的地盘。

• ~/.cc-switch/skills/ 是 CC Switch 的私产，别的工具不知道有这个地方；
• ~/.agents/skills/ 是中立的公共目录，社区里多个 AI 编程工具正在约定都来这里找 skills。

放公共目录的三个收益：

1. 多工具共享一份：今天用 Claude Code，明天试 Codex，同一套 skills 不用装两遍；
2. 不被锁死：哪天不用 CC Switch 了，skills 不会埋在它的私有目录里，换别的管理器直接接上；
3. 方便自己管：路径明确中立，可以用 git 管理、多机同步、手动丢新 skill 进去。

结论：只用一个工具 → 内置存储省心；用多个 AI 工具 → 选 agents 目录。

🌟 跨工具共享的实例

xingxing 这个 skill 最初是在 Codex 里创建的，现在原件在 ~/.agents/skills/xingxing/SKILL.md，通过软链接出现在 ~/.claude/skills/xingxing，Claude Code 直接就能加载使用——不用任何搬运。这就是公共目录方案的实际价值。

Skills · 同步方式

源目录只是仓库，Claude Code 实际只读 ~/.claude/skills/。同步方式决定 CC Switch 用哪种方式把启用的 skill 送进各工具目录。

软链接（Symlink）——贴一张"原件在那边"的便签，不复制内容。

• 零冗余，磁盘上永远只有一份原件；
• 改了原件，所有工具立刻读到新版；
• 个别沙箱环境可能不跟随软链接。

复制文件（Copy）——真的拷一份过去。

• 兼容性最好，任何环境都能读；
• 占双份空间，原件更新后要重新同步才生效。

日常本机使用选软链接即可。某工具读不到、或跑在容器里时再换复制。

启用开关只控制分发，不删原件

实测：在界面上取消一个 skill 之后，

ls -la ~/.claude/skills/
# 只剩 xingxing -> /Users/anthony/.agents/skills/xingxing

accessibility-testing 的软链接被撤掉了，但原件仍好好躺在 ~/.agents/skills/ 里。重新打开开关，链接贴回来就恢复可用，不需要重新下载。

所以启用/停用的本质是：控制分发（贴不贴便签），不是删除原件。

❓ 疑问：在 Claude Code 里新装的 skill 会同步回 agents 目录吗？

不会，这是单向的。

~/.agents/skills/（仓库） --CC Switch 分发--> ~/.claude/skills/（工具读取）

CC Switch 只做"仓库 → 各工具"的下发，不会反向扫描。自己装的 skill 会以真实文件夹形式落在 ~/.claude/skills/ 里，和旁边的软链接混住，CC Switch 不知道它存在，其他工具也共享不到，变成"黑户"。

想纳入统一管理，应该先把 skill 放进 ~/.agents/skills/，再在 CC Switch 面板里启用。

提示词

基于 CodeMirror 6 的 Markdown 编辑器，用来管理各应用的全局 AI 手册文件（CLAUDE.md / AGENTS.md / GEMINI.md），支持多套预设和回填保护。

❓ 疑问：Skills 的两个配置会把 AI 手册也一起同步吗？

不会。 存储位置和同步方式只管 skills 文件夹，管辖范围就这么大：

管的：  ~/.agents/skills/ ←→ ~/.claude/skills/
不管的：~/.claude/CLAUDE.md、~/.codex/AGENTS.md、MCP 配置、供应商配置……

实测印证：切换存储位置时搬家的只有 165 个 skill 文件夹，CLAUDE.md（6 月 29 日）和 AGENTS.md（7 月 2 日）一个字节都没被动过。在 CC Switch 的设计里，Skills 和 AI 手册是两个独立的功能模块。

两份手册的实际差异

	Claude Code	Codex
路径	~/.claude/CLAUDE.md	~/.codex/AGENTS.md
大小	1.7 KB	8.5 KB
类型	独立真实文件	独立真实文件

内容零重叠：CLAUDE.md 只有中文回复偏好 + 编码原则；AGENTS.md 有 9 块规则（使用记录、审核处理、项目级 AGENTS.md 维护、Git 提交流程、临时产物目录、数据库 CLI 路径、敏感信息存放、CodeGraph 等）。

后果：在 CLAUDE.md 写的东西 Codex 完全看不到，反之亦然。像"Git 别用 git add .""MySQL 客户端完整路径"这些明明两边都有用的规则，只有 Codex 知道。

❓ 疑问：能用提示词功能让两边内容一致吗？

文档宣称支持"跨应用同步 CLAUDE.md / AGENTS.md / GEMINI.md"，但实际用下来发现它是按应用分仓的：

1. 选中 Claude 再点提示词，显示的是"管理 Claude 提示词"；
2. 切回 Codex 再点提示词，之前没配过的话是空白。

所谓"跨应用"是指这个功能覆盖多种应用（分别写各自的手册文件），而不是一份内容自动同步给所有应用。用它实现统一，等于每个应用各建一份、改的时候挨个改，退化成手动维护两份。

✅ 可行方案：软链接

原理和 skills 的软链接一样，只是手动来贴：

ln -sf ~/.agents/AGENTS.md ~/.claude/CLAUDE.md

ln -sf ~/.agents/AGENTS.md ~/.codex/AGENTS.md

效果：

~/.claude/CLAUDE.md  ──┐
                       ├──> ~/.agents/AGENTS.md（唯一原件）
~/.codex/AGENTS.md   ──┘

两个工具读到的永远是同一个文件，物理上不可能不同步。

注意事项：

• 合并内容时先把现有两份的内容并进去，别直接覆盖；
• Codex 专属规则加个"仅 Codex 适用"的小标题即可，Claude 读到无副作用；
• 建了软链接后别再用 CC Switch 的提示词功能写这两个文件，它一写入可能把软链接替换成普通文件，破坏结构。两套机制选一个，不要混用。

Codex 应用增强

非接管切换时保留官方登录

Codex 有两种用法：官方账号（ChatGPT OAuth 登录，凭证存在 ~/.codex/auth.json）和第三方供应商（填中转站 Key）。

普通模式的切换动作就是改写配置文件，而官方登录凭证住在配置目录里，每次切换都是一次可能误伤它的机会：

开关关闭：切到第三方 → 配置连同凭证一起被清 → 回官方要重新授权
开关打开：切到第三方 → 只改供应商部分，凭证原地不动 → 回官方直接是登录态

它保的不是"当前的连接"，是"将来切回官方时的免登录"。就像出国旅游期间用不到家门钥匙，但钥匙不该扔掉。

路由接管模式下配置文件只在最初改一次，切换发生在代理内部，凭证没有被误伤的机会，所以"路由接管期间始终保留"，这个开关管不着。

最容易混淆的地方

"普通 / 接管"说的是切换的机制，"官方 / 第三方"说的是连接的目的地，两组概念是交叉的，四种组合都存在：

	连官方	连第三方
普通模式	Codex 直连官方服务器	Codex 直连中转站服务器
接管模式	Codex → 本地代理 → 官方	Codex → 本地代理 → 中转站

普通模式的"直连"意思是中间没有代理，直连"配置文件里当前写的那家"——写官方就连官方，写中转站就连中转站。

统一 Codex 会话历史

Codex 存会话历史时按供应商身份分开记，官方的会话和第三方的会话在两个抽屉里。切换供应商后打开历史列表会发现旧会话"不见了"——不是丢了，是在另一个抽屉。

开启后合并成一个列表，还能把官方旧会话迁移过去（迁移前自动备份，关闭开关可恢复）。

⚠️ 代价：跨供应商继续旧会话可能失败。

❓ 疑问：为什么跨供应商续聊会解密失败？

原本的推理是："Codex 把 A 加密成 1 发给中转站，中转站转发到官方服务器，官方还是能把 1 解密成 A。"

这里有两个前提是错的：

前提一：加密的不是 Codex，是服务器。

第 1 轮：Codex 发问题 → 服务器思考、回答
        服务器把思考过程加密成 encrypted_content 发回
        Codex 原样存进历史（它自己解不开，也不需要解）
第 2 轮：Codex 把历史（含密文）原样发回去
        服务器解开自己当初加密的内容 → 接着上次思路继续

钥匙从头到尾只在服务器手里，Codex 只是个保管员。

前提二：中转站不一定"原样转发到官方"。

• 很多中转站背后根本不是官方，而是拿别的模型（DeepSeek、GLM、Kimi）伪装成兼容接口，当然解不开；
• 即使真转发到官方，账号身份也变了——你直连时用你的账号加密，走中转站时中转站用它自己的账号请求官方。官方看到"这段密文是 3 号租户的钥匙加密的，你是 7 号租户"，拒绝解密。这是防止 A 用户的私密推理内容被 B 用户拿去解读。

所以续聊失败不是故障，是加密设计故意的：密文认"生成它的服务器 + 那个账号身份"，换掉任一条件都解不开。

窗口行为

设置项	作用
开机自启	随系统启动运行 CC Switch
静默启动	启动时不弹主窗口，只在托盘运行
应用到 Claude Code 插件	切换供应商时，VS Code 里的 Claude Code 插件配置也一起改，避免终端和编辑器用不同供应商
跳过 Claude Code 初次安装确认	预写"已初始化"标记，跳过首次运行的主题选择、目录信任等问答。给重装、多环境快照切换、CI 场景用
关闭时最小化到托盘	点 ✕ 缩到托盘而非退出程序

"开机自启 + 静默启动 + 关闭最小化到托盘"三个开启，是典型的常驻托盘管家用法。

🚦 设置 · 路由

本地路由

这是 CC Switch 的第二种工作模式，和"改配置文件"平行。

两种模式的区别

普通切换——Codex 直连供应商，想换供应商就改 Codex 自己的配置文件，改完重启才生效。CC Switch 在这里只是个"帮你改配置的秘书"，请求发出去之后跟它无关。

切换前:  Codex ──────> 官方服务器
切换后:  Codex ──────> 中转站A          (CC Switch 改了配置文件)

路由接管——CC Switch 在本机开一个代理服务，把 Codex 的配置改成永远指向这个本地地址，就一次，以后不再动：

Codex ──────> 本地代理 ──┬──> 官方服务器
                          ├──> 中转站A
                          └──> 中转站B

Codex 以为自己一直在跟同一个服务器说话，其实每个请求都先到代理，由代理决定转发给谁。

类比

• 普通切换 = 手机里存了好几个外卖店电话，想换店就去改"常用号码"，改完才能打给新店。
• 路由接管 = 只存一个"外卖总台"号码，每次都打给总台，想吃哪家跟总台说一声——通讯录再也不用改了。

接管模式的三个好处：

1. 切换即时生效，配置文件不动、不用重启；
2. 官方登录绝对安全，配置文件不再被反复改写；
3. 能做更聪明的事——协议转换、失败自动换下一家等，都建立在"请求经过代理的手"这个前提上。

代价：本机多一个常驻代理进程；代理没开的话 AI 工具就断线，依赖变强。

基础设置

项	值	说明
监听地址	127.0.0.1	只接受本机连接。别改成 0.0.0.0，那会让局域网其他设备也能连，等于把 API 额度暴露出去
监听端口	15721	开启后 CLI 配置会被指向 http://127.0.0.1:15721，和别的软件撞车时才需要改

自动故障转移

路由模式独有的能力，路由服务没启动时整页只能看不能配。备胎队列按应用（Claude / Codex / Gemini / Grok Build）分开配置。

核心概念是给供应商排优先级队列：P1 是主力，P2 是第一备胎，以此类推。

平时:        所有请求走 P1
P1 请求失败:  自动改走 P2 → P2 也失败 → 走 P3 → ……

两个参数管两件不同的事：

• 最大重试次数（默认 6）——"同一家多给几次机会"。请求失败后先在当前供应商上重试，都不行才判定这家不行、换下一家。防止一次网络抖动就急着换。
• 失败阈值（默认 8）——熔断器。某家连续失败 8 次后熔断器打开，一段时间内直接跳过它，不再浪费时间尝试，冷却期过后再试探恢复没有。

类比

P1 是常去的餐馆。重试 = 打电话没人接，多打几次；故障转移 = 实在联系不上，换第二家；熔断 = 这家连续一周关门，接下来几天干脆不打它电话了。

只有一个供应商时这套机制无胎可备，可以先不管。

整流器

路由的"翻译官/急救员"，自动修复 API 请求中的兼容性问题。同样属于路由能力，代理没开时规则还没上岗。

请求整流

Thinking 签名整流——Claude 的思考块带加密签名（和前面 encrypted_content 同一个思路，认"生成它的那家"）。切换供应商后继续旧对话，历史里带着 A 家签名的思考块发给 B 家，验签失败报错。整流器自动把不兼容的思考块剥掉并重试一次，代价是模型丢失那部分思考上下文，通常无感。

Thinking Budget 整流——思考功能有预算参数（budget_tokens 最少 1024），配置不合法时供应商直接拒收。整流器自动修成合法值（thinking 置为 enabled、budget 设为 32000、必要时 max_tokens 提到 64000）后重试。

不支持图片降级——贴了截图但当前供应商背后是纯文本模型，一收到图片就报错、对话中断。整流器把图片块替换成 [Unsupported Image] 标记再发，丢失图片内容但对话不死。

纯文本模型预判——上一条是"报错后补救"，这条更进一步：内置一张已确认的纯文本模型注册表，发送前查表直接剥图，连那次注定失败的请求都省了。报错兜底逻辑仍保留，双保险。

Bedrock 请求优化器

只对 AWS Bedrock 类型的供应商生效，不用 Bedrock 可以无视。

• Thinking 优化：按模型代际自动配置思考模式（新模型 Adaptive Thinking，旧模型注入 Extended Thinking）；
• Cache 注入：自动在请求关键位置插入 5 分钟 Cache 断点，让重复的系统提示和历史命中缓存，减少重复 token 计费。

全局出站代理

配置 CC Switch 自己上网时走哪条路——调用供应商 API、下载 Skills、检查更新都会用到。

和"本地路由"虽然都叫代理，但方向相反：

CLI 工具 ──> 本地路由(入站) ──> [全局出站代理(出海通道)] ──> 官方/中转站服务器

• 本地路由管"谁来找我"——接收本机 AI 工具的请求（服务端）；
• 全局出站代理管"我怎么出去"——向外发请求时借的通道（客户端）。

一个是店铺的前台，一个是店铺的出货物流。

界面说明写了"开启本地路由时，应用的请求也会经过此代理"——即开了路由后，CLI 的请求进了代理再往外转发时也走这条出站通道，等于给所有 AI 工具统一配了一次代理，不用每个工具单独设 HTTP_PROXY。

填写格式对应最常见的两种本地代理工具：

http://127.0.0.1:7890      # Clash 系的默认 HTTP 端口
socks5://127.0.0.1:1080    # V2Ray/Shadowsocks 系的默认 SOCKS5 端口

下面的用户名/密码给需要认证的代理用，本地工具一般留空。留空 = 不用代理，直连。

🔐 设置 · 认证

OAuth 认证中心

标着 Beta。前面的供应商配置都是"填 API Key"，但有些服务不卖 Key、只认订阅账号——比如已经在付费的 GitHub Copilot、ChatGPT Plus/Pro、xAI Grok。

这个模块用 OAuth 网页授权登录已有订阅，把订阅额度拿到 CLI 里用。支持三个：

服务	说明
GitHub Copilot	可选部署类型（GitHub.com / Enterprise），支持挂多个账号并标记"默认"
ChatGPT (Codex OAuth)	就是前面反复提到的 Codex 官方登录
xAI (Grok OAuth)	对应主界面的 Grok Build 应用

界面上那句"请注意合规风险"不是客套话

这些订阅的服务条款通常规定只能在官方客户端内使用，把订阅额度转到第三方工具里跑属于绕过官方用途限制——轻则限流，重则封号。这也是它标 Beta 并专门写警示的原因。重要工作流建议还是用正规 API Key 的供应商托底。

🩺 设置 · 关于

本地环境检查

这一页列出 Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes 七款工具的安装状态和版本，可以逐个安装或"全部升级"。

❓ 疑问：本地明明装了 Claude Code 和 Codex，却显示未安装

实测下来 CC Switch 没有误报，CLI 确实没装——装的是桌面 App，两者不是一回事。

机器上有的（桌面 App）：

ls -d /Applications/*laude* /Applications/*hatGPT*
# /Applications/Claude.app        ← Claude 桌面应用
# /Applications/ChatGPT.app       ← ChatGPT 桌面应用（Codex 内置在里面）

机器上没有的（CLI）：

which claude codex gemini
# claude not found
# codex not found
# gemini not found

把常见安装位置全翻了一遍——~/.nvm/versions/node/*/bin/、npm 全局包目录、homebrew、pnpm、~/.local/bin——里面只有 9router、codegraph、copilot 这些，没有任何踪迹。

桌面 App ≠ CLI 工具

	桌面 App	CLI 工具
形态	/Applications/Claude.app，点图标打开	终端里敲 claude 命令
安装方式	下载 dmg 拖进 Applications	npm install -g @anthropic-ai/claude-code

CC Switch 的本地环境检查检测的是 CLI——去 PATH 里找可执行文件，找不到就报未安装。桌面 App 它既不检测也管不着。

连带的两个结论

为什么 skills 软链接却是有效的？ 因为 Claude 桌面 App 的本地代理模式也读 ~/.claude/ 这个配置目录（skills、CLAUDE.md 都在这），所以 CC Switch 管配置目录有效，但管不到不存在的 CLI 二进制。

供应商切换对桌面 App 大概率无效。 CC Switch 切换供应商的本质是改 ~/.claude/settings.json 里的 API 地址和 Key，这套机制是给 CLI 用的；桌面 App 走的是登录的账号订阅，不吃这套配置。

部分卡片一直显示"加载中"（如 Codex、OpenCode、Hermes）是在查最新版本号，需要联网，和装没装是两码事。

想让 CC Switch 真正管起来

点卡片上的「安装」按钮，或手动安装：

npm install -g @anthropic-ai/claude-code

装完 which claude 能找到，卡片就会显示版本号，供应商切换、路由接管这些功能才真正作用到它身上。页面底部折叠的「手动安装命令」展开就是抄这些命令的地方。

📌 小结

几个反复出现、值得单独记住的模型：

1. 两层结构——Skills 的"存储位置"管源文件在哪，"同步方式"管怎么分发到各工具目录，两者组合成完整链路。启用开关控制的是分发，不是删原件。
2. 模块边界——Skills、提示词（AI 手册）、供应商配置、MCP 是各自独立的模块，一个模块的开关不会带动另一个。
3. 两种切换机制——普通模式改配置文件直连；路由接管在本地起代理、由代理转发。故障转移、整流器、上游格式转换、User-Agent 替换、请求覆盖全都是路由模式独有的能力，因为它们都要"在转发的路上动手脚"，而普通模式压根没有中间人。
4. 加密内容认娘家——不管是 Codex 的 encrypted_content 还是 Claude 的 thinking 签名，都绑定"生成它的服务器 + 账号身份"，跨供应商续聊注定失败，只能靠整流器剥离后重试。
5. 入站 vs 出站——本地路由是接收本机请求的服务端，全局出站代理是向外发请求的客户端，方向相反。