CC-Switch 全平台官方安装配置教程

1. 软件简介

CC-Switch是专为Claude Code CLI生态开发的开源API密钥调度管理工具，定位为Claude Code的前置代理层中间件。
核心作用是解决原生Claude Code仅支持单API密钥绑定、不兼容多服务商Claude系列API、无密钥用量监控的痛点，可实现多密钥自动轮询、故障自动切换、请求负载均衡的能力。
项目采用MIT开源协议托管于公开代码仓库，所有代码可审计无后门风险。
当前教程对应最新正式稳定版本号为v1.4.0。

---

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

2. 全平台下载

所有平台安装包均来自官方稳定发布分支，对应三大平台的安装包信息如下：

2.1 Windows平台

1. 安装版文件名：CC-Switch-Setup-v1.4.0.exe
2. 便携版文件名：CC-Switch-Portable-v1.4.0.zip

2.2 macOS平台

1. DMG手动安装包文件名：CC-Switch-v1.4.0.dmg
2. Homebrew源托管安装包，无需手动下载二进制文件

2.3 Linux平台

1. Debian/Ubuntu系安装包文件名：cc-switch_1.4.0_amd64.deb
2. 全发行版通用便携包文件名：CC-Switch-v1.4.0-x86_64.AppImage
3. RHEL/CentOS/Fedora系安装包文件名：cc-switch-1.4.0.x86_64.rpm

3. 分平台安装教程

3.1 Windows系统安装

3.1.1 安装版安装步骤

1. 双击下载得到的CC-Switch-Setup-v1.4.0.exe文件，弹出系统用户账户控制（UAC）提示时点击「是」授权安装权限
2. 进入安装向导后点击下一步，默认安装路径为C:\Program Files\CC-Switch，若C盘空间不足可修改为其他盘的全英文无空格路径，禁止设置为包含中文、特殊字符的路径
3. 勾选「创建桌面快捷方式」「添加到系统PATH环境变量」两个选项，点击下一步后等待安装进度完成
4. 点击完成按钮即可启动软件，首次启动会自动弹出配置引导窗口。

3.1.2 便携版安装步骤

1. 将下载得到的CC-Switch-Portable-v1.4.0.zip压缩包解压到非系统受保护目录，例如D:\Tools\CC-Switch，禁止解压到桌面、系统桌面、C盘根目录等有权限限制的路径
2. 进入解压后的文件夹，右键点击CC-Switch.exe选择「发送到-桌面快捷方式」
3. 双击exe文件即可直接启动，所有配置数据会自动保存在当前文件夹的data子目录下，重装系统不会丢失配置。

3.2 macOS系统安装

3.2.1 Homebrew命令安装步骤

1. 打开终端应用，执行命令添加官方Homebrew Tap源：

brew tap cc-switch/official

2. 执行安装命令自动拉取最新版软件完成安装：

brew install cc-switch

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

3.2.2 DMG手动安装步骤

1. 双击下载得到的CC-Switch-v1.4.0.dmg挂载镜像，在弹出的窗口中将CC-Switch图标拖拽到「应用程序」文件夹图标上完成安装
2. 首次启动时如果系统弹出「无法打开CC-Switch，因为来自身份不明的开发者」提示，右键点击启动台的CC-Switch图标选择「打开」，在新弹出的确认窗口中再次点击「打开」即可正常启动
3. 若右键打开仍报错，可前往「系统设置-隐私与安全性」页面，下滑到底部找到「已阻止使用CC-Switch」的提示，点击「仍要允许」即可解除限制。

3.3 Linux系统安装

3.3.1 deb格式安装（Debian/Ubuntu/Mint系）

1. 打开终端，进入deb安装包所在的下载目录，执行如下命令安装：

sudo apt update
sudo apt install ./cc-switch_1.4.0_amd64.deb -y

2. 安装完成后可在应用程序菜单中找到CC-Switch启动图标，也可直接在终端输入cc-switch命令唤起GUI界面。

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

1. 打开终端，进入AppImage文件所在的目录，先给文件赋予可执行权限：

chmod +x ./CC-Switch-v1.4.0-x86_64.AppImage

2. 直接双击文件即可启动，所有配置自动保存在用户目录的.config/cc-switch路径下，无需额外安装依赖。

3.3.3 rpm格式安装（RHEL/CentOS/Fedora系）

1. 打开终端，进入rpm安装包所在的目录，执行如下命令安装：

sudo dnf install ./cc-switch-1.4.0.x86_64.rpm -y

2. 安装完成后可在应用程序列表中找到CC-Switch入口点击启动。

4. 首次基础配置

1. 启动界面初始化：首次启动软件会自动检测本地已安装的Claude Code CLI程序路径，若检测失败可手动指定Claude Code的安装目录，确认后软件会自动修改Claude Code的默认请求代理地址指向本地127.0.0.1:7890端口，不会修改原有系统全局代理配置。
2. 添加API服务商：进入左侧菜单栏「服务商管理」页面，支持添加Anthropic官方API、Azure Claude API、第三方Claude中转服务三类服务商，填写服务商名称、API密钥、API请求端点三个必填项后点击保存即可完成添加。
3. 切换默认密钥：进入「密钥列表」页面，选中任意一条已添加的API密钥，点击右上角「设为默认」按钮，该密钥将成为Claude Code发起请求的首选密钥。
4. 内置预设功能：软件内置了Claude 3 Opus、Claude 3.5 Sonnet、Claude 3 Haiku三类模型的请求参数预设，无需手动配置最大上下文窗口、超时时间、请求速率限制等参数，选中对应模型预设即可自动加载所有适配参数。

5. 核心功能使用

1. 多密钥管理：支持批量导入上百条API密钥，可对密钥分组打标签，实现按不同项目分配专属密钥池，避免多项目共用单密钥导致的用量混淆。
2. 用量统计：内置全维度用量看板，可按日/周/月维度统计单密钥、单服务商的Token消耗总量、请求成功率、平均响应时长，支持一键导出CSV格式用量报表。
3. 故障转移：开启自动轮询功能后，若当前密钥触发限流、额度耗尽、服务不可用等异常，软件会在100ms内自动切换到下一条可用密钥，全程无感知不中断Claude Code的当前会话请求，最高支持万级密钥池自动负载均衡。
4. 新版v1.4.0专属功能：新增Claude Code会话自动密钥续传功能，无需重启Claude Code即可实时切换生效密钥；新增自定义请求拦截规则，可对Claude Code输出的内容实现自定义合规校验；新增远程同步配置功能，支持多设备间加密同步所有密钥和配置信息。

6. 常见问题排查

1. Windows平台报错：启动后直接闪退，解决方案是安装微软官方VC++ 2019运行库，重启电脑后即可正常启动；若提示端口7890被占用，可在软件设置中修改本地监听端口为其他未使用端口，同时同步修改Claude Code的环境变量对应端口即可。
2. macOS平台报错：启动后无法关联Claude Code，解决方案是打开终端执行which claude获取Claude Code的实际安装路径，手动填写到CC-Switch的关联配置项中，重启软件即可识别。
3. Linux平台报错：AppImage启动后GUI界面黑屏，解决方案是安装最新版FUSE2依赖包，Debian系执行sudo apt install libfuse2，Fedora系执行sudo dnf install fuse-libs即可修复。
4. 跨平台通用报错：Claude Code请求返回403权限错误，解决方案是检查密钥对应的服务商端点是否可正常连通，在CC-Switch的密钥检测页面点击单密钥连通性测试，根据返回的错误提示配置对应代理规则即可。

7. 更新与卸载说明

7.1 更新说明

所有版本更新均可直接覆盖安装，原有配置数据会自动保留，不会被新版本覆盖。Windows安装版可通过软件内置的「检查更新」功能一键自动升级，便携版直接将新版压缩包解压到旧版本目录选择覆盖所有文件即可完成升级；macOS Homebrew安装执行brew upgrade cc-switch即可更新，DMG版本直接拖拽新版镜像内的软件覆盖原有应用程序内的旧文件即可；Linux deb版本执行sudo apt upgrade cc-switch，rpm版本执行sudo dnf update cc-switch即可完成升级，AppImage版本直接替换新的AppImage文件即可使用。

7.2 卸载说明

1. Windows安装版：打开系统控制面板-程序和功能，找到CC-Switch点击卸载即可，卸载完成后会自动清除所有环境变量配置。
2. Windows便携版：直接删除CC-Switch所在的整个文件夹即可完成卸载，不会残留任何系统配置项。
3. macOS Homebrew安装：打开终端执行brew uninstall cc-switch && brew untap cc-switch/official即可完成卸载。
4. macOS DMG安装：将应用程序文件夹内的CC-Switch图标拖拽到废纸篓即可完成卸载。
5. Linux deb版本：打开终端执行sudo apt remove --purge cc-switch -y即可完全卸载。
6. Linux rpm版本：打开终端执行sudo dnf remove cc-switch -y即可完全卸载。