CC-Switch 全平台安装配置与使用正式教程

1. 软件简介

CC-Switch是面向Anthropic Claude Code开发者生态推出的开源API代理调度增强工具。
核心作用是突破原生Claude Code仅支持官方单一密钥的限制，实现多服务商兼容、多密钥池动态调度，大幅降低API调用成本和服务中断风险。
项目完全开源无闭源后门，所有代码托管于公开代码仓库，所有调度逻辑完全本地运行不会上传用户密钥等敏感信息。
当前最新稳定版为v1.3.2，全平台原生兼容三大桌面操作系统。

---

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

2. 全平台下载

除上述官方夸克网盘镜像站点外，正式版本也可通过项目公开Release页获取，各平台对应安装包明细如下：

1. Windows平台：安装版安装包文件名为CC-Switch_v1.3.2_x64_Setup.exe，便携版压缩包文件名为CC-Switch_v1.3.2_x64_Portable.zip
2. macOS平台：适配Homebrew源的双架构通用包无单独文件名，DMG格式手动安装包文件名为CC-Switch_v1.3.2_universal.dmg，原生同时支持Intel(x86_64)和Apple Silicon(arm64)芯片
3. Linux平台：Debian/Ubuntu系deb格式包名为cc-switch_1.3.2_amd64.deb，Fedora/RHEL系rpm格式包名为cc-switch-1.3.2.x86_64.rpm，通用免安装AppImage包名为CC-Switch_v1.3.2_amd64.AppImage

3. 分平台安装教程

3.1 Windows 安装教程

3.1.1 安装版安装步骤

1. 双击下载得到的CC-Switch_v1.3.2_x64_Setup.exe，在系统用户账户控制弹窗点击「是」允许程序运行
2. 在安装向导界面选择软件安装路径，默认路径为C:\Program Files\CC-Switch，不建议安装到中文路径下
3. 勾选「创建桌面快捷方式」「添加启动栏常驻图标」可选配置项
4. 点击「安装」等待10秒左右即可完成安装，勾选「立即启动CC-Switch」后点击完成即可进入主界面

3.1.2 便携版安装步骤

1. 将下载得到的CC-Switch_v1.3.2_x64_Portable.zip解压到非系统临时目录，例如D:\Tools\CC-Switch，不要放在桌面、下载等重启会被清理的目录中
2. 直接双击根目录下的CC-Switch.exe即可启动运行，全程不会写入系统注册表，所有配置均保存在当前解压目录下，可直接拷贝到U盘在多设备间流转使用

3.2 macOS 安装教程

3.2.1 Homebrew 命令行安装

打开终端.app依次执行以下命令即可自动完成安装，全程无需手动处理权限问题：

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

安装完成后可直接在终端输入cc-switch启动，也可从启动台找到CC-Switch图标点击运行。

3.2.2 DMG 手动安装步骤

1. 双击下载得到的CC-Switch_v1.3.2_universal.dmg挂载磁盘镜像
2. 在弹出的镜像窗口中，将左侧CC-Switch图标拖拽到右侧「应用程序」文件夹图标上，等待拷贝完成即可完成安装
3. 首次启动若系统弹出「无法打开CC-Switch，因为来自未验证的开发者」报错，右键点击启动台/应用程序中的CC-Switch图标，选择「打开」，在二次确认弹窗点击「打开」即可绕过Gatekeeper限制正常启动。

3.3 Linux 安装教程

3.3.1 deb 格式安装（适配Debian/Ubuntu/Mint系列系统）

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

sudo dpkg -i cc-switch_1.3.2_amd64.deb

输入当前用户管理员密码后等待执行完成，即可在系统应用菜单中找到CC-Switch启动入口。

3.3.2 rpm 格式安装（适配Fedora/RHEL/CentOS系列系统）

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

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

自动安装所有依赖后即可正常启动软件。

3.3.3 AppImage 格式安装（全发行版通用免安装）

在安装包所在目录打开终端，依次执行以下命令添加执行权限并直接启动：

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

无需写入系统目录，直接运行即可正常使用所有功能。

4. 首次基础配置

1. 启动界面入门：软件启动后默认在系统托盘后台常驻，点击托盘图标选择「主界面」即可打开功能面板，主界面分为密钥管理、调度规则、用量统计三个Tab页，首次启动会弹出引导向导，自动扫描本地Claude Code的默认配置路径，用户点击确认即可自动完成环境变量适配。
2. 添加API服务商：进入「密钥管理」Tab页点击「添加服务商」按钮，软件内置预置Anthropic官方、字节豆包兼容接口、阿里通义千问兼容接口、OpenRouter等主流大模型服务商的适配规则，无需手动填写API路径，仅需填入服务商后台生成的API密钥后点击保存即可完成添加。
3. 切换默认密钥：进入「调度规则」Tab页，勾选需要加入调度池的密钥，拖拽调整密钥优先级排序，将常用的高可用密钥拖拽到队列顶部，点击「设为Claude Code全局默认代理」，软件会自动修改Claude Code的本地环境变量配置，无需手动编辑配置文件。
4. 内置预设启用：新手可直接使用软件内置的全量预设规则，预设覆盖Claude 3 Opus/Sonnet/Haiku全系列模型的路由映射、默认负载均衡策略、1秒故障转移阈值等参数，无需额外调整即可直接调用Claude Code服务。

5. 核心功能使用

1. 多密钥管理：支持批量导入数十个API密钥，自动按服务商标签分类管理，支持单独临时禁用指定密钥而不删除记录，方便用户调试不同服务商的接口兼容性，所有密钥信息全部本地加密存储不会外传。
2. 用量统计：自动统计每个密钥的调用次数、输入/输出Token消耗、累计消费金额，支持按日/周/月维度生成统计报表，可一键导出为CSV格式用于财务对账，支持自定义单密钥用量熔断阈值，到达预设上限后自动将密钥移出调度池，避免超额扣费。
3. 故障转移：内置实时健康检测机制，当密钥返回429限流、5xx服务错误、余额不足等报错时，软件会在1秒内自动切换调度池内的下一个可用密钥，完全不打断当前Claude Code的代码生成流程，用户无感知即可实现连续服务。
4. 新版专属功能：v1.3.2版本新增智能路由分流功能，可根据当前调用的模型类型自动分配成本最低的服务商密钥；新增本地缓存功能，自动缓存重复请求的返回结果，最高可降低30%的重复调用成本；新增全局代理穿透配置，完美适配企业内网环境下的API调用需求。

6. 常见问题排查

6.1 Windows平台高频问题

• 报错提示「缺少VCRUNTIME140.dll」：下载安装微软官方最新版Visual C++ Redistributable运行库，重启电脑后即可正常启动。
• Claude Code调用返回连接失败：检查Windows Defender防火墙是否拦截了CC-Switch的本地代理端口，将CC-Switch添加到防火墙信任白名单即可恢复。

6.2 macOS平台高频问题

• 启动后系统托盘无图标：打开「系统设置-隐私与安全性-后台App刷新」，给CC-Switch开启后台运行权限，重启软件后托盘图标即可正常显示。
• 修改配置后Claude Code仍走官方接口：打开终端执行claude config list检查API密钥配置是否被正确替换，重启终端后环境变量即可生效。

6.3 Linux平台高频问题

• AppImage启动无响应：当前系统缺少Fuse2依赖，Debian/Ubuntu系执行sudo apt install fuse，Fedora系执行sudo dnf install fuse安装依赖后即可正常运行。
• deb安装后点击图标无反应：在终端执行sudo chmod 755 /opt/CC-Switch/*赋予程序运行权限即可解决。

6.4 通用问题

密钥添加后调用返回401报错：检查输入的API密钥是否存在多余的空格、换行字符，确认服务商后台已经开启对应Claude系列模型的调用权限。

7. 更新与卸载说明

7.1 更新操作

1. Windows：安装版直接打开软件设置面板点击「检查更新」，自动下载新版覆盖安装即可，原有配置不会丢失；便携版直接将新版本文件解压替换旧目录下的所有文件即可完成更新。
2. macOS：Homebrew安装的版本直接在终端执行brew upgrade cc-switch即可自动完成更新；DMG手动安装的版本直接双击新版DMG，拖拽图标覆盖旧版应用即可。
3. Linux：deb/rpm格式安装的版本直接下载新版安装包执行对应安装命令即可自动覆盖更新；AppImage版本直接替换新的AppImage文件即可完成升级。

7.2 卸载操作

1. Windows：安装版打开「控制面板-程序和功能」，找到CC-Switch点击卸载，按照向导走完流程即可完全清除所有文件；便携版关闭软件后直接删除整个解压目录即可实现零残留卸载。
2. macOS：Homebrew安装的版本依次执行brew uninstall cc-switch、brew untap cc-switch/tap即可完成完全卸载；DMG手动安装的版本，打开启动台长按Option键点击CC-Switch左上角的叉号删除，再将应用程序目录下的CC-Switch拖拽到废纸篓，最后删除~/Library/Application Support/CC-Switch/目录下的残留配置文件即可。
3. Linux：deb安装版本执行sudo dpkg -r cc-switch即可卸载；rpm安装版本执行sudo dnf remove cc-switch即可卸载；AppImage版本直接删除AppImage文件，再删除~/.config/cc-switch配置目录即可完全清除所有数据。