CC Switch 使用完整指南：一键切换供应商、配置故障转移与备份的 5 步实操

CC Switch 使用完整指南：一键切换供应商、配置故障转移与备份的 5 步实操

【免费下载链接】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 是一款跨平台桌面工具，把 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Grok Build 和 Hermes Agent 的供应商配置、本地路由、用量统计和数据备份收进同一个界面。本文不照搬功能清单，而是按一条真实的使用路线走：先让它在你的系统上装得起来，再把它和供应商接得通，然后学会路由与故障转移让它用得稳，接着优化资源和开销，最后保证配置数据丢不了。每一节都按"遇到什么问题 → 怎么一步步做 → 背后为什么"来讲。

一、装得上：macOS、Windows、Linux 各自的"卡点"与解法

macOS 提示"来自身份不明的开发者"

CC Switch 的 macOS 版已完成 Apple 代码签名与公证，绝大多数情况下直接安装即可。若仍被 Gatekeeper 拦截，通常是安装包来源过旧或下载不完整：关闭弹窗，进入"系统设置 → 隐私与安全性"，在页面下方找到对应提示，点击"仍要打开"，再从官网下载最新版本安装即可。想彻底移除隔离标记，可以在终端执行：

sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/

原理很简单：Gatekeeper 靠 quarantine 扩展属性识别"从网络下载的应用"，去掉这个标记后就不再被拦。

Windows 点击后毫无反应

大概率是缺少 Tauri 依赖的 WebView2 运行时，其次是杀毒软件拦截。处理顺序：

1. 到微软官网下载安装 "Evergreen Standalone Installer"（WebView2 运行时），装完重启一次系统；
2. 仍打不开，就把 CC Switch 加入杀毒白名单再试。

企业环境可以把 WebView2 运行时的离线包放进统一分发，通过组策略批量部署，避免每台机器手动处理。

Linux 启动报错或界面点不动

AppImage 打不开，一般先补执行权限；个别沙箱环境下需要加--no-sandbox：

chmod +x CC-Switch-*.AppImage ./CC-Switch-*.AppImage --no-sandbox

还有一种更隐蔽的坑：Wayland 会话 + NVIDIA 显卡时，主界面内容区点不动、缩放后黑屏。原因是启动钩子默认强制走 XWayland，在新环境下反而让网页内容收不到鼠标事件。解决办法是显式指定后端再启动：

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

若从桌面图标启动，需把该变量写进.desktop的Exec=行。反过来，在 sway/Hyprland 等平铺合成器下如果点击失效，就改成CC_SWITCH_GDK_BACKEND=x11。更多边界情况可查 FAQ（docs/user-manual/zh/5-faq/5.2-questions.md）。

二、接得通：用预设模板 5 分钟接好第一个供应商

添加供应商：选预设，只填 Key

打开主界面，点右上角"+"进入添加流程。这里最省心的地方是预设供应商：DeepSeek、GLM、Kimi、MiniMax、Qwen Coder 等常见服务都内置了请求地址和协议细节，选中后通常只需要填 API Key，端点地址已预置好。

添加完成回到主界面，所有供应商以卡片形式排列，当前在用的那个带绿色"当前使用"标记，右侧还能直接看到已用额度和剩余余额。顶部的应用切换器（Claude / Codex / Gemini……）决定你在给哪个工具配供应商，每个工具下的供应商互相独立。供应商卡片的管理逻辑在src/components/providers/目录下，预设数据则来自src/config/里的各预设文件。

切换后为什么没生效

这是新手最常问的一句话。点"启用"之后，CC Switch 已经把目标工具的配置（环境变量或配置文件）改好了，但正在运行的 CLI 还持有旧配置：

• Claude Code：关掉终端重开，或重启 IDE 插件；
• Codex：同样重开终端；
• Gemini CLI：托盘里切换即时生效，无需重启。

一句话原理：CC Switch 改的是"磁盘上的配置"，进程要重启才会重新读取。

想切回官方登录

用了一段时间中转之后想回到官方渠道，不用手动清理环境变量：选回"官方登录"预设（Claude/Codex 为官方预设，Gemini 为 Google 官方），点"启用"，重启对应 CLI，按正常流程登录即可。Codex 的官方登录保留相关设置可以在 codex-official-auth-preservation 指南 里查到。

三、用得稳：开启本地路由，主力供应商挂了自动切换

端口 15721 被占用怎么办

路由服务的默认监听地址是127.0.0.1、端口15721（范围 1024–65535）。启动失败报"端口占用"时，先确认是谁占着，再改端口绕开：

lsof -i :15721 # macOS / Linux netstat -ano | findstr :15721 # Windows

改端口在"设置 → 路由"里完成：修改"监听端口"后点保存，重启路由服务即可。

哪些供应商需要路由，哪些不用

不是所有供应商都需要本地路由。直连型供应商（自带 Anthropic/OpenAI 兼容端点的中转服务）配好 Key 就能用；而协议不匹配的供应商必须走路由，比如把 DeepSeek 接进 Claude Code、把 Codex 账号接进 Claude Desktop——这类卡片上会标"需要路由"。路由开启后，CC Switch 在本机起一个转发服务，负责协议翻译、模型映射和鉴权注入，工具本身只需要把请求地址指向这个本地端口。

故障转移与熔断：主力挂了谁来顶

路由面板提供自动故障转移：给当前供应商配好优先级排序，主请求失败达到熔断阈值后，熔断器会暂时摘除该供应商，流量自动落到下一位；等熔断窗口过去再试探性恢复。阈值、恢复时间这些参数在面板里可视化调整，底层实现可以看src-tauri/src/proxy/circuit_breaker.rs和src-tauri/src/proxy/failover_switch.rs。

经验值：日常开发把失败阈值保持在 3~5 次即可，恢复窗口别设太短，否则遇到供应商整体故障时会反复"试探—失败"，白白消耗 token。

四、跑得快：轻量模式省内存，用量看板管开销

常驻后台，内存却降不下来

CC Switch 建议开着托盘常驻，方便随时切换。v3.13 起新增的轻量模式就是为常驻场景设计的：右键托盘图标选"轻量模式"后，主窗口被彻底销毁（不是隐藏），UI 资源随之释放，空闲占用接近零，但托盘切换、深链接唤起全部照常可用；下次打开主界面时窗口会按需重建。

配套建议：勾选"关闭时最小化到托盘"，再按需开启"开机自启"，路由服务随应用启动，不用每天手动点一次。

用量与余额怎么查

"使用统计"页提供完整的用量看板：按供应商、模型、日期筛选，能看到请求日志、token 消耗趋势和缓存命中率；官方订阅类（Claude / Codex / Gemini / Copilot）自动展示剩余额度，第三方中转的余额通过内置模板一键启用。供应商卡片上也会同步显示"已使用 / 剩余"，方便在切换前看一眼钱包。相关统计服务在src-tauri/src/services/usage_stats.rs，前端看板在src/components/usage/。

两个省资源的小习惯：日志级别调到"警告"以上；用不到的应用（比如你根本不用 OpenClaw）在"应用可见性"里直接隐藏，界面更清爽，列表也更轻。

五、丢不了：自动备份、恢复与 WebDAV 云同步

自动备份怎么开

所有配置、供应商、路由参数都存在本地 SQLite 数据库里。设置页的备份管理支持手动导出和自动备份：可设定备份间隔（默认 24 小时）与保留份数（默认 10 份），每次恢复前还会自动打一个"安全备份"快照，恢复操作本身也因此可逆。团队或个人最稳的姿势是：自动备份开着 + 定期把备份文件拷到另一个磁盘或网盘。

换电脑、团队共享：导入导出与 WebDAV

• 导入导出：一键打包全部配置为备份文件，新机器导入即可还原；也支持通过深链接把单个供应商配置直接导入（src/deeplink/目录处理深链接解析与导入确认）。
• WebDAV 同步：在 WebDAV 同步设置里填入私有 WebDAV 服务地址，配置即可自动同步到企业网盘或自建存储，多台电脑之间保持同一份供应商配置。实现位于src-tauri/src/services/webdav_sync/。

安全上多提醒一句：备份文件里含 API Key 明文，同步目标选可信任的私有存储，不要把备份提交进代码仓库。

下一步

按"装得上 → 接得通 → 用得稳 → 跑得快 → 丢不了"走完一遍，你手上已经是一套能自动故障转移、可同步、可恢复的 AI 工具管理环境。接下来可以顺着两条线深入：查docs/user-manual/zh/下的用户手册看 Claude Desktop 路由、Codex×DeepSeek 互转等进阶玩法；或盯docs/release-notes/的更新日志，轻量模式、用量看板这些能力仍在快速迭代。需要源码级定制的话，克隆仓库git clone https://gitcode.com/GitHub_Trending/cc/cc-switch即可上手。

【免费下载链接】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