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

CC-Switch 是一款专门面向 Anthropic Claude Code 生态的开源调度增强工具，核心作用是解决原生 Claude Code 仅支持单一官方API密钥、区域限制严格、无故障容错机制的痛点。
工具定位为 Claude Code 的轻量化全局代理调度中间件，无需修改 Claude Code 核心源码即可实现多服务商API密钥的统一管理、自动负载均衡与智能故障转移，大幅提升大模型编程场景下的调用稳定性。
CC-Switch 采用 MIT 开源协议，所有核心代码完全公开无闭源后门，支持全架构跨平台运行，当前最新正式版本为 v1.2.3。
全量安装包可通过以下公共资源链接获取：

---

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

1. 全平台下载说明

当前v1.2.3版本全平台安装包均已同步至上述资源站，各系统对应安装包参数如下：

1. Windows平台
   • 安装版：后缀为.exe，文件名：CC-Switch_v1.2.3_Windows_Setup.exe
   • 便携版：后缀为.zip，文件名：CC-Switch_v1.2.3_Windows_Portable.zip
2. macOS平台
   • 一键安装Homebrew源已同步至官方Tap仓库，手动安装包为Universal通用架构DMG镜像，文件名：CC-Switch_v1.2.3_macOS_Universal.dmg，同时支持Intel、Apple Silicon芯片
3. Linux平台
   • Debian/Ubuntu系安装包（deb格式）：文件名cc-switch_1.2.3_amd64.deb
   • 通用便携格式（AppImage）：文件名CC-Switch_v1.2.3_Linux_amd64.AppImage
   • RHEL/CentOS/Fedora系安装包（rpm格式）：文件名cc-switch-1.2.3.x86_64.rpm

2. 分平台安装教程

2.1 Windows平台安装

2.1.1 安装版安装流程

1. 双击下载得到的CC-Switch_v1.2.3_Windows_Setup.exe，弹出用户账户控制弹窗时选择「是」确认权限
2. 进入安装向导后，勾选「同意开源许可协议」，点击下一步
3. 自定义安装路径，不建议选择系统盘C盘的受保护目录（如C:\Program Files）避免后续权限限制，可设置为D:\Program Files\CC-Switch
4. 勾选「添加桌面快捷方式」「添加至系统PATH环境变量」两个选项，点击下一步开始安装
5. 等待10秒左右安装完成，勾选「立即启动CC-Switch」后点击完成即可进入工具界面。

2.1.2 便携版安装流程

1. 将下载的CC-Switch_v1.2.3_Windows_Portable.zip压缩包解压至非系统盘的纯英文路径下，路径中不得包含中文、特殊字符或空格
2. 直接双击根目录下的CC-Switch.exe即可启动工具，无需额外安装，所有配置数据都会自动保存在解压目录的data子文件夹中
3. 若需要创建桌面快捷方式，右键点击exe文件选择「发送到」-「桌面快捷方式」即可。

2.2 macOS平台安装

2.2.1 Homebrew命令安装

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

# 添加CC-Switch官方Homebrew源
brew tap cc-switch/tap
# 执行安装命令
brew install cc-switch
# 启动工具验证安装结果
cc-switch start

安装完成后可在启动台找到CC-Switch图标，点击即可打开图形化界面。

2.2.2 DMG手动安装

1. 双击下载得到的CC-Switch_v1.2.3_macOS_Universal.dmg挂载镜像，弹出安装向导窗口
2. 直接将左侧的CC-Switch图标拖拽至右侧的「应用程序」文件夹图标上，等待拷贝完成即完成安装
3. 首次启动时若弹出「无法打开CC-Switch，因为来自身份无法验证的开发者」报错，右键点击启动台内的CC-Switch图标，选择「打开」，在二次确认弹窗中再次点击「打开」即可正常启动，该操作仅需执行一次。

2.3 Linux平台安装

2.3.1 deb格式（Debian/Ubuntu/Mint等发行版）

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

# 执行安装命令自动解决依赖
sudo apt install ./cc-switch_1.2.3_amd64.deb
# 验证安装成功
cc-switch --version

2.3.2 AppImage通用便携格式

终端进入安装包所在目录，依次执行以下命令：

# 为AppImage文件添加可执行权限
chmod +x CC-Switch_v1.2.3_Linux_amd64.AppImage
# 直接启动运行
./CC-Switch_v1.2.3_Linux_amd64.AppImage

部分发行版若出现启动失败，可先执行sudo apt install fuse2安装FUSE依赖后重试。

2.3.3 rpm格式（RHEL/CentOS 8+/Fedora/OpenSUSE等发行版）

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

# Fedora/RHEL系安装命令
sudo dnf install ./cc-switch-1.2.3.x86_64.rpm
# 验证安装成功
cc-switch --version

3. 首次基础配置

完成安装后首次启动工具，按以下流程完成基础配置即可正常对接Claude Code：

1. 启动界面初始化：工具首次启动会自动扫描当前系统的Claude Code安装路径，若扫描失败可手动指定Claude Code的全局安装目录，点击确认即可完成环境校验。
2. 添加API服务商：在左侧菜单栏选择「服务商管理」，支持添加Anthropic官方服务、国内第三方Claude代理、兼容OpenAI协议的转译服务商三类站点，按提示填写服务商名称、接口地址、API密钥即可完成添加，支持批量导入密钥。
3. 切换默认密钥：在「调度规则」页面，点击密钥列表的「设为默认」按钮，即可将选中的密钥配置为Claude Code全局默认调用密钥，无需修改原生Claude Code的环境变量配置。
4. 内置预设功能：工具内置了3种官方模型的调用限速预设，分别对应Claude 3 Opus、Claude 3.5 Sonnet、Claude 3 Haiku的官方调用频率限制规则，点击对应预设即可一键完成适配配置，无需手动填写限流参数。

4. 核心功能使用

1. 多密钥分组管理：支持将不同服务商、不同额度的API密钥按使用场景分组，设置优先级权重，工具会按照权重自动分发调用请求，避免单密钥过快耗尽额度。
2. 可视化用量统计：内置统计看板，可按日/周/月维度查看所有密钥的调用次数、输入输出Token消耗、剩余额度估算，自动生成用量报表支持导出。
3. 智能故障转移：可自定义故障转移阈值，当密钥触发限流、返回401鉴权失败、接口超时等异常情况时，工具会自动将请求切换至下一个可用密钥，全程无感知不打断Claude Code的代码补全、长文本生成流程。
4. v1.2.3新版专属功能：新增跨设备密钥端到端加密同步、国内节点低延迟自动探测、Claude Code会话流量本地镜像留存三个专属功能，大幅提升国内无魔法环境下的Claude Code调用稳定性。

5. 常见问题排查

1. Windows平台：启动时提示“缺少VCRUNTIME140.dll运行库”，直接前往微软官网下载安装最新版Visual Studio 2022运行库即可解决；若出现切换密钥不生效，重启本地终端的Claude Code进程后即可加载新配置。
2. macOS平台：启动后提示“无法获取Claude Code环境变量”，前往「系统设置」-「隐私与安全性」-「全磁盘访问」，勾选CC-Switch的权限后重启工具即可解决；若密钥同步失败，检查系统代理是否拦截了工具的出站请求，添加白名单即可恢复。
3. Linux平台：AppImage双击无响应，在终端执行命令启动查看报错信息，90%以上的场景是缺少fuse2依赖，安装对应发行版的fuse2软件包即可解决；若无法监听本地调度端口，检查5876端口是否被其他进程占用，在设置页面修改自定义监听端口即可。
4. 通用报错：所有平台均出现“Claude Code调用返回403区域限制”，在CC-Switch的网络设置页面开启自动代理隧道功能即可绕过区域校验。

6. 更新与卸载说明

6.1 版本更新

CC-Switch内置自动更新通道，可在「设置」-「关于」页面点击「检查更新」，一键下载增量更新包完成升级，无需手动重新下载完整安装包；若关闭自动更新，直接覆盖安装最新版的安装包即可，原有配置数据不会丢失。

6.2 卸载说明

1. Windows安装版：打开「控制面板」-「程序和功能」，找到CC-Switch点击卸载，按照向导提示即可完全移除所有文件；便携版直接删除解压的整个文件夹即可完成卸载。
2. macOS平台：Homebrew安装的版本执行brew uninstall cc-switch即可完全卸载；DMG手动安装的版本直接删除「应用程序」目录下的CC-Switch.app文件即可。
3. Linux平台：deb格式执行sudo apt remove cc-switch卸载，rpm格式执行sudo dnf remove cc-switch卸载，AppImage便携版直接删除AppImage文件即可，所有配置数据默认保存在~/.config/cc-switch目录下，按需删除即可彻底清空所有本地数据。