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

1. 软件简介

CC-Switch 是一款专为Anthropic Claude Code终端客户端定制开发的开源配套管理工具。
它的核心作用是打通原生Claude Code不支持的多API密钥调度、第三方兼容API服务商接入、请求故障自动转移等能力，大幅提升大模型开发工作流的稳定性。
该工具完全遵循MIT开源协议发布，全功能对个人用户免费开放，无任何内置广告与付费解锁限制，不存在后台非必要数据上传行为。
截至2024年第四季度，官方最新正式稳定版本号为v2.4.0，所有更新均经过全平台兼容性测试。

---

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

2. 全平台下载

本次教程提供的镜像下载链接同步官方Release正式版全量安装包，各平台对应安装包格式与文件名如下：

1. Windows平台：提供安装版与便携版两种分发格式，安装包文件名为CC-Switch_v2.4.0_Windows_Setup.exe，便携版压缩包文件名为CC-Switch_v2.4.0_Windows_Portable.zip
2. macOS平台：提供Homebrew源码安装包与DMG镜像两种分发格式，其中ARM架构（M系列芯片）DMG包文件名为CC-Switch_v2.4.0_macOS_ARM64.dmg，Intel架构DMG包文件名为CC-Switch_v2.4.0_macOS_x64.dmg
3. Linux平台：提供deb、rpm、通用AppImage三种分发格式，deb包文件名为cc-switch_2.4.0_amd64.deb，rpm包文件名为cc-switch-2.4.0.x86_64.rpm，AppImage包文件名为CC-Switch_v2.4.0_Linux_Universal.AppImage

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装步骤

1. 双击下载的CC-Switch_v2.4.0_Windows_Setup.exe安装包，弹出系统UAC权限提示时点击「是」同意授权
2. 自定义选择安装路径，默认路径为C:\Program Files\CC-Switch，禁止选择包含中文、特殊字符的路径避免运行异常
3. 勾选「添加桌面快捷方式」「自动添加系统PATH环境变量」两个可选配置项，不要跳过环境变量配置
4. 点击「立即安装」等待进度条走完，勾选「启动CC-Switch」后点击「完成」结束安装流程

3.1.2 便携版安装步骤

1. 将下载的CC-Switch_v2.4.0_Windows_Portable.zip压缩包完全解压到非系统临时目录，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动软件，所有配置文件自动存储在当前目录的config子文件夹内，无需写入系统注册表，重装系统不会丢失配置

3.2 macOS平台安装

3.2.1 Homebrew命令安装

打开终端应用，依次执行以下两条命令即可自动完成全流程安装，适配M系列与Intel所有架构设备：

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

安装完成后可直接从启动台找到CC-Switch图标点击启动，也可在终端输入cc-switch命令唤起软件界面。

3.2.2 DMG手动安装

1. 双击打开对应芯片架构的DMG镜像文件，等待系统挂载完成弹出安装窗口
2. 拖拽左侧CC-Switch图标到右侧「应用程序」文件夹图标上，等待拷贝进度条走完即完成安装
3. 首次启动如果弹出「无法打开来自未验证开发者的应用」的系统提示，右键点击应用图标选择「打开」，在二次确认弹窗再次点击「打开」即可绕过公证限制正常启动。

3.3 Linux平台安装

3.3.1 deb格式（Debian/Ubuntu/UOS等Deb系发行版）

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

sudo dpkg -i cc-switch_2.4.0_amd64.deb
# 如果出现依赖缺失提示，执行以下命令自动补全依赖
sudo apt install -f

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

3.3.2 rpm格式（CentOS/RHEL/Fedora等RPM系发行版）

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

# 常规rpm安装命令
sudo rpm -ivh cc-switch-2.4.0.x86_64.rpm
# Fedora/CentOS8+用户推荐使用以下命令自动补全依赖
sudo dnf install ./cc-switch-2.4.0.x86_64.rpm

3.3.3 AppImage通用格式

AppImage属于免安装便携格式，仅需授予执行权限即可直接运行：

# 赋予文件可执行权限
chmod +x CC-Switch_v2.4.0_Linux_Universal.AppImage
# 直接启动软件
./CC-Switch_v2.4.0_Linux_Universal.AppImage

可右键将文件锁定到系统dock栏，也可手动创建桌面快捷方式方便后续调用。

4. 首次基础配置

1. 启动引导设置：首次启动软件会自动扫描本地Claude Code客户端的安装路径，如果扫描失败可手动指定claude可执行文件的存储路径，确认后点击「下一步」进入主界面
2. 添加API服务商：点击侧边栏「服务商管理」选项，支持直接选择原生Anthropic官方、字节方舟兼容、DeepSeek兼容、OpenAI代理兼容4种内置预设服务商，也支持自定义填写第三方服务商的接口端点、自定义请求头字段，填入对应API密钥后点击「连通性验证」，提示成功后即可保存
3. 切换默认密钥：进入主界面的密钥列表，选中需要作为默认调用的密钥，右键点击选择「设为当前默认密钥」，软件会自动覆盖Claude Code的本地环境变量配置，后续所有调用claude命令的操作都会自动使用该密钥
4. 内置预设启用：新手用户可直接开启主界面的「自动适配系统代理」「请求超时自动重试」两个内置预设开关，无需手动修改任何配置文件即可正常使用所有功能。

5. 核心功能使用

1. 多密钥管理：支持批量导入最多1000个API密钥，可给每个密钥添加标签备注使用场景、剩余额度，支持创建多分组实现密钥批量切换，例如划分「测试组」「生产组」，切换分组后全局生效无需单独调整配置
2. 用量统计：自动同步所有绑定密钥的每日请求次数、输入输出token消耗、累计消费金额，生成可视化日/周/月统计报表，支持导出CSV格式账单，可自定义设置额度预警阈值，消耗达到阈值后自动推送桌面通知避免超额扣费
3. 故障转移：开启故障转移功能后，当当前使用的密钥触发限流、额度耗尽、服务商接口宕机的异常情况时，软件会自动按照用户预设的优先级切换同服务商下的其他可用密钥，全程不中断Claude Code的现有会话，不需要手动重启开发任务
4. v2.4.0新版专属功能：新增Claude Code 3.5 Sonnet思考模式专属适配、本地请求日志自动脱敏存储、小型团队密钥共享同步、全局请求延迟实时监控4项专属能力，长时开发任务稳定性提升60%以上。

6. 常见问题排查

1. Windows平台高频报错：
   • 启动软件提示「找不到vcruntime140.dll」：下载安装微软官方最新版VC++运行库，重启设备即可解决
   • 便携版启动后配置无法保存：检查解压目录是否被设置为系统只读属性，取消只读勾选后重启软件即可
2. macOS平台高频报错：
   • 启动软件提示无法修改环境变量：打开终端执行sudo spctl --master-disable临时关闭公证限制，重启软件后重新授权即可
   • Homebrew安装后终端找不到cc-switch命令：执行brew link cc-switch --overwrite重建软链接即可
3. Linux平台高频报错：
   • AppImage双击无响应：Deb系发行版执行sudo apt install libfuse2，RPM系发行版执行sudo dnf install fuse-libs补全FUSE依赖即可正常启动
   • 调用claude命令提示密钥不生效：完全退出当前终端后重新打开，让系统重新加载CC-Switch注入的环境变量即可
4. 全平台通用报错：API连通性验证失败，优先检查系统代理是否正常连通目标接口，确认填入的接口地址与密钥没有多余空格，临时关闭系统防火墙重试即可。

7. 更新与卸载说明

7.1 更新操作

• Windows：安装版直接点击软件内「检查更新」按钮即可自动下载覆盖安装，所有原有配置不会丢失；便携版直接将新版exe文件替换旧版文件，保留原目录下的config文件夹即可完成升级
• macOS：Homebrew安装的用户执行brew upgrade cc-switch即可完成升级；DMG版直接拖拽新版镜像内的APP文件覆盖旧版应用即可
• Linux：deb版执行sudo apt update && sudo apt upgrade cc-switch升级；rpm版执行sudo dnf update cc-switch升级；AppImage版直接替换新的可执行文件即可完成升级

7.2 卸载操作

• Windows：安装版直接从控制面板的程序列表找到CC-Switch点击卸载即可；便携版直接删除整个解压目录即可，卸载前可导出config文件夹备份所有配置
• macOS：Homebrew版执行brew uninstall cc-switch即可卸载；DMG版直接删除应用程序目录下的CC-Switch.app，同时删除~/.config/cc-switch配置目录即可完全清除
• Linux：deb版执行sudo apt remove cc-switch卸载；rpm版执行sudo dnf remove cc-switch卸载，删除用户目录下的~/.config/cc-switch文件夹即可彻底清除所有残留配置。