CC Switch 完整教程：多供应商一键切换，AI 编程 CLI 配置不再手改
【免费下载链接】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 这些 AI 编程命令行工具，提供供应商配置的集中管理与一键切换。它替你省掉的，是每次换端点、贴密钥、改 TOML/JSON 配置文件时那份翻找文件再排查半天的心力。
🎯 适合谁用
想象一下你的日常：主力用 Claude Code 的官方订阅，偶尔切到 Kimi 或 DeepSeek 的第三方端点省点钱，再顺手用 Codex 跑批处理。
- 配置散落在
~/.claude、~/.codex、~/.gemini各处，格式还不统一，改一处忘一处。 - 供应商限流或挂掉，你正写着代码，只能中断手头的事手动改配置再试。
- 花了多少 token、钱花在哪，月底完全说不清。
只要你有两个以上供应商在轮换，或者希望请求有自动兜底，CC Switch 就能帮上忙：所有供应商配置统一入库，点一下切换，请求还能走内置本地代理实现故障转移和用量记录。
🚀 装上并跑通
第 1 步：下载安装。从官方渠道（官网 ccswitch.io）下载对应系统的安装包，安装完成后直接启动。
第 2 步：过掉首次启动的系统坑。三个系统各有各的拦路虎：
- macOS：如果提示"来自身份不明的开发者"，进入「系统设置 → 隐私与安全性」，点击"仍要打开"即可。
- Windows：安装后点不开，多半是缺少 WebView2 运行时（Tauri 框架渲染界面依赖的微软组件）。去微软官网下载 Evergreen Standalone Installer 装上再启动。
- Linux：AppImage 版本先执行
chmod +x CC-Switch-*.AppImage再运行。如果用的是 Wayland + NVIDIA 显卡，界面点了没反应或缩放后黑屏，改用CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage启动（从桌面图标启动时，把这个变量写进.desktop文件的Exec=行）。
第 3 步：添加第一个供应商。主界面点+，选择一个预设（智谱 GLM、DeepSeek、Kimi 等会自动填好端点地址），或者选"自定义"，填入 API Key 后添加。
第 4 步：验证切换生效。在供应商卡片上点"启用"，或直接右键托盘图标切换。生效时机因工具而异：Claude Code、Gemini 即时生效；Codex、OpenCode、OpenClaw 需要重开终端。然后运行claude随便问一句话，能正常回答就算全链路通了。
⚙️ 功能：从基础到进阶
供应商切换：官方订阅当主力，第三方端点做备份
所有供应商配置都存在~/.cc-switch/（Windows 为C:\Users\<用户名>\.cc-switch\）的 SQLite 数据库里，界面卡片或托盘菜单点两下即可完成切换，预设模板覆盖主流供应商，省去手改端点和密钥的重复劳动。
要切回官方登录时，选"官方登录"预设（Gemini 对应"Google 官方"）再走 CLI 自身的登录流程即可。典型搭配是：官方订阅日常使用，第三方端点留作备用，供应商抽风时在托盘里切过去，终端窗口完全不用动。
内置本地代理：所有请求走一道门
不想每换一次供应商就重设一遍环境变量，可以让请求统一收口到内置 HTTP 代理，它默认监听 49152 端口转发工具请求并统一改写端点。
在「设置 → 代理服务」里开启代理，把 CLI 的端点指向本地代理地址；如果端口被占用导致启动失败，点"恢复默认"或先释放端口。开启后，以 Codex 为例端点固定指向本地代理，之后换供应商再也不用碰终端里的配置。
怎么开启自动故障转移：主供应商挂了自动换
熔断器（连续失败达到阈值就自动断开当前供应商的机制）会持续监控主供应商，失败次数到阈值后自动切到队列里的备用，熔断时长默认 60 秒，到期后再自动试探恢复。
在代理面板打开自动故障转移开关，队列里放 2~3 个备用供应商即可。如果发现误触发太频繁（比如网络抖动），把失败阈值从 3 调到 5。效果是：主力供应商限流时请求自动落到备用端点，你甚至感知不到中断。熔断与切换逻辑的实现在 src-tauri/src/proxy/ 目录下，感兴趣可以直接读源码。
用量统计：token 花在哪一眼看清
代理层会解析请求与响应中的用量信息，按供应商、模型两个维度汇总花费和趋势，月底对账不用再靠猜。
前提是三个开关都打开：代理运行中、应用接管开启（让请求真正经代理转发）、日志记录开启。另外部分第三方供应商还需要在供应商卡片上手动打开"用量查询"并选择内置模板。开启后在用量面板里就能看到单日花费与供应商分布了。
🔍 出问题先查这张表
| 症状 | 原因 | 修复 |
|---|---|---|
| 切换后工具还在用旧配置 | 已运行的 CLI 进程不会自动重读配置 | 重开终端再试；Claude Code 与 Gemini 本身即时生效，无需重启 |
| API Key 被拒、测速不通 | key 复制时带了空格，或端点地址写错 | 重新复制无空格的 key，再点供应商卡片上的"速度测试"验证 |
| 代理启动失败，报端口占用 | 默认端口 49152 已被其他程序占掉 | 用lsof -i :49152（Windows 用netstat -ano \| findstr :49152）找出占用进程，释放后重试或在设置里"恢复默认" |
| Windows 装完打不开 | 缺少 WebView2 运行时 | 安装微软 Evergreen Standalone Installer 后重新启动 |
| 故障转移始终不触发 | 代理没运行，或接管、自动转移、备用队列三项没配齐 | 按顺序检查三个开关，队列里确保有 2~3 个备用供应商 |
| 用量面板一片空白 | 请求没走代理，或日志记录没开 | 确认代理在跑、应用接管已开，再检查日志记录开关 |
| 重启后供应商列表消失 | 配置目录被删或数据库损坏 | 从~/.cc-switch/backups/恢复最新备份，或用之前导出的文件重新导入 |
🧭 进阶入口
- 日志：运行日志在
~/.cc-switch/logs/cc-switch.log，按 20MB 自动轮转；应用崩溃看同目录下的crash.log（Windows 在C:\Users\<用户名>\.cc-switch\下）。 - 完整文档：多语言用户手册见 docs/user-manual/，安装、供应商管理、代理与故障转移都有专章。
- 深度链接：
ccswitch://v1/import?resource=...链接可以把供应商、MCP 服务、提示词一键带进应用，分享给同事比自己手动重填省事得多。 - 本地开发：
git clone https://gitcode.com/GitHub_Trending/cc/cc-switch，然后执行pnpm install和pnpm tauri dev即可跑起开发环境，遇到问题到项目 Issues 反馈。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
