Skip to content

🔀 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,两套环境互不污染。

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

⚙️ 设置 · 通用

主页显示

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

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

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

Skills · 存储位置

这个开关决定 Skills **源文件(SSOT,单一事实来源)**放在哪里:

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

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

直接实测。切换

bash
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

在界面上点了切换,切换

bash
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 之后,

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

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

所以启用/停用的本质是:控制分发(贴不贴便签),不是删除原件。

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

不会,这是单向的。

text
~/.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 文件夹,管辖范围就这么大:

text
管的:  ~/.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 CodeCodex
路径~/.claude/CLAUDE.md~/.codex/AGENTS.md
大小1.7 KB8.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 的软链接一样,只是手动来贴:

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

效果:

text
~/.claude/CLAUDE.md  ──┐
                       ├──> ~/.agents/AGENTS.md(唯一原件)
~/.codex/AGENTS.md   ──┘

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

注意事项:

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

Codex 应用增强

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

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

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

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

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

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

最容易混淆的地方

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

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

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

统一 Codex 会话历史

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

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

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

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

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

这里有两个前提是错的:

前提一:加密的不是 Codex,是服务器。

text
第 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 在这里只是个"帮你改配置的秘书",请求发出去之后跟它无关。

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

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

text
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 是第一备胎,以此类推。

text
平时:        所有请求走 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、检查更新都会用到。

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

text
CLI 工具 ──> 本地路由(入站) ──> [全局出站代理(出海通道)] ──> 官方/中转站服务器
  • 本地路由管"谁来找我"——接收本机 AI 工具的请求(服务端);
  • 全局出站代理管"我怎么出去"——向外发请求时借的通道(客户端)。

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

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

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

text
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):

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

机器上没有的(CLI):

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

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

桌面 App ≠ CLI 工具

桌面 AppCLI 工具
形态/Applications/Claude.app,点图标打开终端里敲 claude 命令
安装方式下载 dmg 拖进 Applicationsnpm 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 真正管起来

点卡片上的「安装」按钮,或手动安装:

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

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

📌 小结

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

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

技术笔记