CC-Switch 全平台安装配置技术教程

---

1. 软件简介

CC-Switch 是面向 Claude Code 生态开发的轻量API路由调度辅助工具，核心作用是解决原生Claude Code仅支持单API密钥配置、多服务商切换繁琐、密钥失效后会话直接中断的痛点，可实现多服务商API的统一管理与无缝调度。该软件采用MIT开源协议完全开放源码，无内置数据上传行为，所有密钥配置均仅存储在本地用户目录下，无第三方后门风险。目前最新正式稳定版本为v1.3.2，全平台适配Windows、macOS、Linux三大主流桌面操作系统，完全兼容官方版Claude Code以及所有二次发行版Claude Code客户端。

---

| 下载 | https://pan.quark.cn/s/d6152047213b

---

2. 全平台下载

除上述统一加速下载站外，用户也可通过开源项目官方Release页获取安装包，全平台对应安装包格式与文件名如下：

1. Windows平台适配Win10 21H2及以上64位系统，提供两类安装包：
   • 正式安装版：CC-Switch_v1.3.2_x64.msi
   • 便携免安装版：CC-Switch_v1.3.2_x64_portable.zip
2. macOS平台适配macOS 12 Monterey及以上版本，同时支持Intel、Apple Silicon双架构，提供两类分发介质：
   • DMG手动安装版：CC-Switch_v1.3.2_universal.dmg
   • Homebrew源托管包名：cc-switch
3. Linux平台适配glibc 2.31及以上的主流发行版，提供三类通用安装包：
   • Debian/Ubuntu系deb包：cc-switch_1.3.2_amd64.deb
   • 全发行版通用AppImage包：CC-Switch_v1.3.2_x86_64.AppImage
   • RHEL/CentOS/Fedora系rpm包：cc-switch-1.3.2.x86_64.rpm

---

3. 分平台安装教程

3.1 Windows平台安装教程

3.1.1 MSI安装版安装步骤

1. 双击下载完成的CC-Switch_v1.3.2_x64.msi安装包，弹出用户账户控制(UAC)弹窗时点击「是」允许程序运行
2. 进入安装向导后点击「下一步」，勾选「添加到当前用户桌面快捷方式」选项，默认安装路径为C:\Program Files\CC-Switch，可根据需求自定义修改
3. 点击「安装」等待进度条走完，最后点击「完成」即可自动启动软件

3.1.2 便携版安装步骤

1. 将下载的CC-Switch_v1.3.2_x64_portable.zip压缩包解压到非中文、无特殊符号的目录下，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动，无需写入系统注册表，所有配置数据全部存储在当前解压目录下，移动文件夹即可直接转移到其他设备使用

3.2 macOS平台安装教程

3.2.1 Homebrew命令安装

打开终端应用，依次执行以下命令添加开源项目Tap源并完成安装：

brew tap cc-switch/tap
brew install cc-switch

安装完成后直接在启动台找到CC-Switch图标点击启动即可。

3.2.2 DMG手动安装

1. 双击下载的CC-Switch_v1.3.2_universal.dmg镜像文件，弹出挂载窗口后将左侧的CC-Switch图标拖拽到右侧的「应用程序」文件夹图标上，等待拷贝完成即安装成功
2. 首次启动时如果弹出「无法打开CC-Switch，因为来自身份不明的开发者」提示，不要直接双击软件图标，右键点击应用程序目录下的CC-Switch图标，选择「打开」，二次确认弹窗点击「打开」即可正常运行。

3.3 Linux平台安装教程

3.3.1 deb包安装（Debian/Ubuntu/UOS等系发行版）

打开终端进入安装包所在目录，执行以下命令完成安装：

sudo dpkg -i cc-switch_1.3.2_amd64.deb
# 若提示依赖缺失，执行以下命令自动补全依赖
sudo apt install -f

安装完成后可在系统应用列表找到CC-Switch启动入口。

3.3.2 AppImage包安装（全发行版通用）

打开终端进入文件目录，先给AppImage文件赋予可执行权限，直接运行即可：

chmod +x CC-Switch_v1.3.2_x86_64.AppImage
./CC-Switch_v1.3.2_x86_64.AppImage

可自行创建桌面快捷方式将软件固定到系统启动栏，无需写入系统目录。

3.3.3 rpm包安装（Fedora/RHEL/CentOS等系发行版）

打开终端进入安装包所在目录，执行以下命令完成安装：

sudo dnf install ./cc-switch-1.3.2.x86_64.rpm

---

4. 首次基础配置

1. 启动界面引导：首次打开软件后会自动弹出配置向导，软件会自动扫描本地Claude Code的默认配置文件路径，若扫描失败可手动指定路径，通用路径规则为用户目录下的.claude/config.json，确认路径后点击「下一步」
2. 添加API服务商：在左侧菜单栏选择「服务商管理」，点击「添加服务商」，可直接选择内置的Anthropic官方、字节豆包方舟、阿里云通义千问、DeepSeek等预设服务商，填入对应平台申请的API密钥后可自定义密钥别名，点击保存即可完成添加
3. 切换默认密钥：在密钥列表对应条目右侧点击星标按钮，星标高亮的密钥即为Claude Code默认优先调用的密钥，切换星标即可一键更换当前使用的API路由
4. 内置预设功能：在「策略设置」页面提供三类一键预设：低延迟优先、成本优先、高稳定性优先，选中对应预设后软件会自动完成路由权重、故障转移阈值、限速规则的配置，无需用户手动调整复杂参数。

---

5. 核心功能使用

1. 多密钥分组管理：支持批量导入上百条API密钥，可按服务商、项目用途自定义添加标签分组，支持设置单密钥单日调用量上限、单小时Token消耗上限，超出阈值后自动将该密钥临时移出调度池，避免产生超额扣费。
2. 用量可视化统计：实时展示每个密钥的调用次数、输入/输出Token消耗量、剩余预估额度，自动生成日/周/月维度的统计报表，支持导出为CSV格式文件留存，方便对账核算。
3. 无感知故障转移：开启该功能后，若当前正在使用的密钥触发速率限制、余额耗尽、网络请求失败场景，软件会在100ms内自动切换到同服务商下的其他可用密钥，全程不中断Claude Code的当前会话，用户无感知。
4. v1.3.2新版专属功能：新增国内节点网络加速优化，可将国内服务商的API响应速度提升40%以上；支持自定义路由分流规则，指定特定模型走指定服务商密钥；新增静默后台运行模式，开启后软件启动后自动最小化到系统托盘，几乎不占用CPU与内存资源。

---

6. 常见问题排查

1. Windows平台高频报错：
   • MSI安装提示「此安装包不支持当前系统」：确认系统为64位Windows且版本高于21H2，临时关闭360、腾讯管家等杀毒软件的拦截规则后重新运行安装包即可。
   • 启动后无法识别Claude Code配置：手动找到用户目录下的.claude文件夹，将路径直接粘贴到配置向导的路径输入框即可。
2. macOS平台高频报错：
   • 启动提示「CC-Switch已损坏，无法打开」：打开终端执行命令xattr -d com.apple.quarantine /Applications/CC-Switch.app，清除系统隔离属性后即可正常打开。
   • Homebrew安装后提示找不到命令：在终端执行brew link cc-switch --force强制关联软链接即可修复。
3. Linux平台高频报错：
   • AppImage双击后无响应：执行sudo apt install libfuse2（Debian系）或sudo dnf install fuse-libs（Fedora系）补全FUSE依赖即可运行。
   • 安装完成后桌面图标不显示：执行update-desktop-database刷新系统应用索引即可。
4. 通用报错：Claude Code调用提示「密钥无效」：确认CC-Switch的系统代理开关处于开启状态，检查填入的API密钥前后无多余空格，重启软件后即可恢复正常。

---

7. 更新与卸载说明

7.1 更新操作

1. Windows安装版：直接下载最新版MSI安装包运行，程序会自动覆盖旧版本数据，原有密钥配置完全保留无需重新配置；便携版直接用新版本的exe文件替换旧目录下的同名文件即可。
2. macOS平台：Homebrew安装的版本直接在终端执行brew upgrade cc-switch即可完成更新；DMG安装的版本直接运行新的DMG包，将新的CC-Switch拖拽到应用程序文件夹替换旧版本即可。
3. Linux平台：deb/rpm包直接用新版安装包覆盖安装即可，AppImage版本直接替换新的AppImage文件即可完成更新，所有历史配置数据自动继承。

7.2 卸载操作

1. Windows安装版：打开控制面板-程序和功能，找到CC-Switch点击卸载，跟随向导完成操作即可；便携版直接删除整个解压目录即可完全卸载。
2. macOS平台：Homebrew安装的版本执行brew uninstall cc-switch即可卸载；DMG安装的版本直接将应用程序目录下的CC-Switch拖拽到废纸篓即可。
3. Linux平台：deb包执行sudo apt remove cc-switch卸载，rpm包执行sudo dnf remove cc-switch卸载，AppImage版本直接删除对应的文件即可。

卸载前可在软件设置页面导出配置备份文件，避免密钥统计数据丢失，重新安装后可直接导入备份文件恢复所有配置。