Appearance
🔀 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。
放公共目录的三个收益:
- 多工具共享一份:今天用 Claude Code,明天试 Codex,同一套 skills 不用装两遍;
- 不被锁死:哪天不用 CC Switch 了,skills 不会埋在它的私有目录里,换别的管理器直接接上;
- 方便自己管:路径明确中立,可以用 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/xingxingaccessibility-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 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",但实际用下来发现它是按应用分仓的:
- 选中 Claude 再点提示词,显示的是"管理 Claude 提示词";
- 切回 Codex 再点提示词,之前没配过的话是空白。
所谓"跨应用"是指这个功能覆盖多种应用(分别写各自的手册文件),而不是一份内容自动同步给所有应用。用它实现统一,等于每个应用各建一份、改的时候挨个改,退化成手动维护两份。
✅ 可行方案:软链接
原理和 skills 的软链接一样,只是手动来贴:
bash
ln -sf ~/.agents/AGENTS.md ~/.claude/CLAUDE.mdbash
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
└──> 中转站BCodex 以为自己一直在跟同一个服务器说话,其实每个请求都先到代理,由代理决定转发给谁。
类比
- 普通切换 = 手机里存了好几个外卖店电话,想换店就去改"常用号码",改完才能打给新店。
- 路由接管 = 只存一个"外卖总台"号码,每次都打给总台,想吃哪家跟总台说一声——通讯录再也不用改了。
接管模式的三个好处:
- 切换即时生效,配置文件不动、不用重启;
- 官方登录绝对安全,配置文件不再被反复改写;
- 能做更聪明的事——协议转换、失败自动换下一家等,都建立在"请求经过代理的手"这个前提上。
代价:本机多一个常驻代理进程;代理没开的话 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——里面只有 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 真正管起来
点卡片上的「安装」按钮,或手动安装:
bash
npm install -g @anthropic-ai/claude-code装完 which claude 能找到,卡片就会显示版本号,供应商切换、路由接管这些功能才真正作用到它身上。页面底部折叠的「手动安装命令」展开就是抄这些命令的地方。
📌 小结
几个反复出现、值得单独记住的模型:
- 两层结构——Skills 的"存储位置"管源文件在哪,"同步方式"管怎么分发到各工具目录,两者组合成完整链路。启用开关控制的是分发,不是删原件。
- 模块边界——Skills、提示词(AI 手册)、供应商配置、MCP 是各自独立的模块,一个模块的开关不会带动另一个。
- 两种切换机制——普通模式改配置文件直连;路由接管在本地起代理、由代理转发。故障转移和整流器都是路由模式独有的能力,路由不开就用不上。
- 加密内容认娘家——不管是 Codex 的
encrypted_content还是 Claude 的 thinking 签名,都绑定"生成它的服务器 + 账号身份",跨供应商续聊注定失败,只能靠整流器剥离后重试。 - 入站 vs 出站——本地路由是接收本机请求的服务端,全局出站代理是向外发请求的客户端,方向相反。