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

1. 软件简介

CC-Switch 是面向 Claude Code 命令行客户端开发的专属API密钥调度中间件工具，核心作用是替代原生Claude Code的单密钥调用逻辑，实现多API密钥的自动负载均衡、故障转移与用量统一统计，彻底解决单密钥额度耗尽、服务商限流导致的使用中断问题。
该项目为完全开源的非商业工具，代码完全公开无后门，可直接对接官方Anthropic API及所有兼容Claude接口的第三方中转服务商，定位为Claude Code生态下的必备增强工具，大幅提升大模型开发调试的稳定性。
目前项目最新正式版本为v2.7.1，全平台原生二进制包均已通过安全签名校验，无额外依赖，启动后默认在本地127.0.0.1端口运行，所有请求均仅在本地流转不会上传用户任何对话数据。
所有版本安装包均经过恶意代码扫描，可直接放心下载使用。

---

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

2. 全平台下载

全平台所有版本安装包均已统一收录在前述提供的资源包内，解压后可直接获取三大系统对应适配版本，各平台安装包对应格式与文件名如下：

1. Windows平台：安装版为EXE可执行文件，文件名为CC-Switch-Setup-v2.7.1.exe；便携版为单EXE绿色文件，文件名为CC-Switch-Portable-v2.7.1.exe
2. macOS平台：Homebrew安装适配包分双架构tar包，文件名为CC-Switch-macOS-arm64-v2.7.1.tar.gz（M系列芯片）、CC-Switch-macOS-x64-v2.7.1.tar.gz（Intel芯片）；通用DMG安装包文件名为CC-Switch-macOS-universal-v2.7.1.dmg
3. Linux平台：deb格式包文件名为cc-switch_2.7.1_amd64.deb；AppImage通用格式包文件名为CC-Switch-v2.7.1-x86_64.AppImage；rpm格式包文件名为cc-switch-2.7.1.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装

步骤1：双击下载的CC-Switch-Setup-v2.7.1.exe，若弹出Windows Defender SmartScreen拦截，点击「更多信息」后选择「仍要运行」即可跳过拦截
步骤2：选择安装路径，默认路径为C:\Program Files\CC-Switch，禁止安装到包含中文、特殊字符的路径下，避免后续运行报错
步骤3：勾选「创建桌面快捷方式」「开机后台自动启动」选项，点击下一步等待安装完成
步骤4：安装结束后会自动唤起程序主界面，状态栏显示「服务运行中」即代表安装成功

3.1.2 便携版安装

步骤1：将CC-Switch-Portable-v2.7.1.exe单独解压到自定义的全英文路径文件夹中
步骤2：直接双击主程序即可启动，所有配置文件、日志数据都会自动生成在当前目录下，不会写入系统注册表，直接移动整个文件夹即可完成程序迁移。

3.2 macOS平台安装

3.2.1 Homebrew命令安装

步骤1：打开终端，切换到解压后对应架构的安装包所在目录，执行如下命令：

# 替换路径为你实际的安装包解压路径
cd ~/Downloads/cc-switch-resources/macos/arm64
# 执行本地安装
brew install ./CC-Switch-macOS-arm64-v2.7.1.tar.gz
# 验证安装结果，输出版本号v2.7.1即代表成功
cc-switch --version

步骤2：执行后台常驻启动命令：brew services start cc-switch，程序会随系统自动后台运行
步骤3：若弹出权限拦截提示，打开「系统设置-隐私与安全性」，下拉到页面底部选择允许CC-Switch运行即可。

3.2.2 DMG手动安装

步骤1：双击打开CC-Switch-macOS-universal-v2.7.1.dmg文件，拖拽CC-Switch图标到应用程序文件夹完成文件复制
步骤2：首次启动时若提示「无法打开，因为来自身份不明的开发者」，右键点击应用图标选择「打开」，在弹出的确认框中再次点击「打开」即可跳过系统隔离限制
步骤3：首次启动后系统会询问是否允许CC-Switch接收网络连接，选择「允许」，程序会常驻顶部菜单栏。

3.3 Linux平台安装

3.3.1 deb格式安装（Debian/Ubuntu系列发行版）

# 切换到deb包所在目录
cd ~/Downloads/cc-switch-resources/linux/deb
# 执行安装命令
sudo dpkg -i cc-switch_2.7.1_amd64.deb
# 自动修复可能存在的依赖缺失
sudo apt install -f
# 验证安装结果
cc-switch --version
# 启用系统服务设置开机自启
sudo systemctl enable --now cc-switch

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

步骤1：进入对应目录后赋予文件执行权限，执行如下命令：

cd ~/Downloads/cc-switch-resources/linux/appimage
chmod +x CC-Switch-v2.7.1-x86_64.AppImage
# 直接启动程序
./CC-Switch-v2.7.1-x86_64.AppImage

步骤2：建议将AppImage文件移动到/opt目录下，手动创建桌面快捷方式方便后续快速启动，无需其他额外依赖。

3.3.3 rpm格式安装（CentOS/Fedora/RHEL系列发行版）

# 进入rpm包所在目录
cd ~/Downloads/cc-switch-resources/linux/rpm
# 执行安装命令
sudo rpm -ivh cc-switch-2.7.1.x86_64.rpm
# 启动后台服务并设置开机自启
sudo systemctl start cc-switch
sudo systemctl enable cc-switch
# 验证服务运行状态
systemctl status cc-switch

4. 首次基础配置

4.1 启动界面说明

首次启动后会自动弹出可视化配置界面，默认运行端口为8787，状态栏显示绿色的「服务运行中」即代表本地代理服务已正常启动，系统弹出的网络权限请求选择允许即可。

4.2 添加API服务商

点击左侧菜单栏的「服务商管理」按钮，选择对应服务商类型，目前支持Anthropic官方及所有兼容Claude协议的第三方中转平台，按提示填入服务商接口地址、API密钥、模型配额上限，点击保存即可完成添加。

4.3 切换默认密钥

打开终端进入Claude Code的原生配置页，执行命令claude config set api-base http://127.0.0.1:8787，将Claude Code的默认请求地址指向CC-Switch本地服务，原有Claude Code配置的API密钥可直接清空，也可以填写任意随机字符串即可正常运行。

4.4 内置预设功能

软件内置了近30家热门第三方中转服务商的预设模板，选择对应服务商名称后会自动填充正确的接口地址，无需手动输入参数，大幅降低配置出错概率。

5. 核心功能使用

5.1 多密钥管理

支持添加无上限数量的API密钥，可自定义不同密钥的权重值，高权重密钥会被分配更多请求流量，支持单独启停某一个密钥，不需要删除即可临时停用特定密钥，适配多团队共享密钥的场景。

5.2 用量统计

自动统计每个密钥的Token消耗量、请求次数、剩余额度，可视化展示日/周/月的调用趋势，无需手动登录服务商后台即可快速查询全量用量数据。

5.3 故障转移

开启故障转移开关后，当某一个密钥触发限流、额度耗尽、接口报错时，系统会自动跳过该失效密钥，将当前请求无缝转发到下一个正常可用的密钥，全程用户无感知，不会中断Claude Code的当前对话流程。

5.4 新版专属功能

v2.7.1版本新增了请求速率自定义限流、超长上下文Token自动截断、密钥优先级队列、本地请求日志回溯功能，完整适配Claude 3.5 Sonnet、Opus、Haiku全系列模型的调度规则，兼容最新版Claude Code所有功能特性。

6. 常见问题排查

1. Windows平台高频报错：启动后提示8787端口被占用，可在软件设置页修改CC-Switch的运行端口为其他未占用端口，同步修改Claude Code的api-base配置为对应新端口即可；若程序无法启动，检查程序是否安装在中文路径下，移动到全英文路径即可解决。
2. macOS平台高频报错：打开应用提示「文件已损坏」，打开终端执行命令xattr -d com.apple.quarantine /Applications/CC-Switch.app即可解除系统隔离限制；后台进程自动退出，进入「系统设置-通用-登录项」，勾选CC-Switch允许在后台启动即可。
3. Linux平台高频报错：执行cc-switch提示命令不存在，执行source /etc/profile刷新全局环境变量即可；AppImage启动后闪退，执行对应发行版的依赖安装命令，Debian/Ubuntu系列执行sudo apt install libfuse2安装FUSE依赖即可解决。
4. 全平台通用报错：Claude Code发起请求提示连接失败，首先检查CC-Switch主界面状态栏是否显示服务运行中，若未运行手动重启服务即可，确认本地防火墙没有拦截127.0.0.1地址的8787端口访问权限。

7. 更新与卸载说明

7.1 更新方式

全平台均支持内置一键更新，点击主界面右上角「关于-检查更新」，即可自动下载最新版本安装包完成升级，原有所有密钥配置、统计数据会自动保留，无需重新配置。也可直接从官方下载链接获取最新安装包直接覆盖安装，不会丢失本地用户数据。

7.2 卸载方式

1. Windows安装版：打开系统设置-应用列表，找到CC-Switch点击卸载，可自主选择是否勾选「删除所有配置数据」清空本地存储的密钥信息；便携版直接删除存放程序的文件夹即可完成全部卸载。
2. macOS Homebrew安装：打开终端执行brew uninstall cc-switch && brew services stop cc-switch即可完全卸载；DMG安装版本直接将应用程序里的CC-Switch拖拽到废纸篓，手动删除~/Library/Application Support/CC-Switch目录的残留配置即可。
3. Linux平台：deb包执行sudo apt remove cc-switch完成卸载，rpm包执行sudo rpm -e cc-switch完成卸载，AppImage格式直接删除对应文件即可完成全部卸载。