CC-Switch 全平台配置使用教程

---

1. 软件简介

CC-Switch 是一款面向Anthropic Claude Code 官方命令行工具的开源第三方适配增强组件，核心作用是解决原生Claude Code仅支持绑定单API密钥、无法自定义多服务商路由、高并发场景下易触发调用中断的痛点。
其定位为Claude Code生态的轻量流量转发中间件，完全兼容原生Claude Code的所有调用逻辑，无需修改 Claude Code 核心代码即可实现多密钥轮询、服务商自定义、故障自动转移等增强能力。
软件完全开源托管于公开开源社区，全程无用户数据上传、无隐私采集行为，所有配置均存储在用户本地设备中。
截至2024年第四季度，CC-Switch正式版最新迭代版本为v1.3.2，全平台安装包均经过官方数字签名校验，无恶意篡改风险。

---

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

2. 全平台下载

所有版本均已在上述指定下载站点同步上传，各操作系统对应的安装包信息如下：

1. Windows 平台：共提供2种安装格式，分别为安装版文件名 CC-Switch_v1.3.2_Windows_Setup.exe，便携版文件名 CC-Switch_v1.3.2_Windows_Portable.zip
2. macOS 平台：共提供2种安装格式，分别为Homebrew托管源在线安装包，DMG离线安装包文件名 CC-Switch_v1.3.2_macOS_Universal.dmg（同时兼容Intel、Apple Silicon双架构）
3. Linux 平台：共提供3种安装格式，deb安装包文件名 cc-switch_1.3.2_amd64.deb，rpm安装包文件名 cc-switch-1.3.2.x86_64.rpm，便携通用格式AppImage文件名 CC-Switch_v1.3.2_Linux_amd64.AppImage

3. 分平台安装教程

3.1 Windows 平台安装

3.1.1 安装版安装步骤

1. 双击下载完成的CC-Switch_v1.3.2_Windows_Setup.exe安装包，触发系统UAC权限确认弹窗后点击「是」
2. 阅读用户许可协议后勾选「我接受许可协议」，点击下一步
3. 自定义安装路径，请勿选择包含中文、特殊字符或空格的路径（如C:\Program Files\CC-Switch为合法路径，D:\软件\CC切换为非法路径），点击下一步
4. 勾选「创建桌面快捷方式」选项，点击「安装」等待进度条完成后即可启动软件。

3.1.2 便携版安装步骤

1. 将下载的CC-Switch_v1.3.2_Windows_Portable.zip压缩包解压至非中文无空格的本地目录
2. 直接双击目录内的CC-Switch.exe即可运行，无需额外写入系统注册表，所有配置均保存在当前解压目录下。

3.2 macOS 平台安装

3.2.1 Homebrew 命令行安装

打开「终端」应用，依次执行以下命令添加官方源并完成安装：

# 添加CC-Switch官方Homebrew镜像源
brew tap cc-switch/tap
# 执行安装命令
brew install cc-switch

安装完成后直接在终端输入cc-switch gui即可唤起图形化界面。

3.2.2 DMG 手动安装

1. 双击打开下载的CC-Switch_v1.3.2_macOS_Universal.dmg镜像文件
2. 在弹出的镜像窗口中，将「CC-Switch」图标拖拽至「Applications」文件夹图标上，等待拷贝完成即完成安装
3. 首次启动时若系统弹出「无法打开来自身份不明的开发者」的提示，右键点击「启动台-CC-Switch」图标，按住Option键选择「打开」，在二次确认弹窗中再次点击「打开」即可正常进入软件。

3.3 Linux 平台安装

3.3.1 deb 格式安装（适配Debian、Ubuntu、Linux Mint等发行版）

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

# 执行deb包安装
sudo dpkg -i cc-switch_1.3.2_amd64.deb
# 修复缺失依赖
sudo apt install -f -y

安装完成后可在应用列表中找到CC-Switch图标直接启动。

3.3.2 rpm 格式安装（适配CentOS、Fedora、OpenSUSE等发行版）

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

# 执行rpm包安装
sudo dnf install ./cc-switch-1.3.2.x86_64.rpm -y

3.3.3 AppImage 便携格式安装

打开终端，在安装包所在目录执行以下命令赋予执行权限：

chmod +x CC-Switch_v1.3.2_Linux_amd64.AppImage
# 直接运行软件
./CC-Switch_v1.3.2_Linux_amd64.AppImage

部分发行版首次运行提示缺失FUSE依赖时，执行sudo apt install libfuse2（Debian/Ubuntu系）或sudo dnf install fuse-libs（Fedora系）即可解决。

4. 首次基础配置

1. 启动界面引导：首次打开软件会自动扫描本地已安装的Claude Code路径，若未检测到原生Claude Code，会弹出一键引导安装窗口，跟随提示完成依赖部署即可进入主界面。主界面分为侧边功能栏、核心配置区、运行日志区三个板块。
2. 添加API服务商：点击侧边栏「服务商管理」-「添加服务商」，可直接选择内置的Anthropic官方、国内合规中转服务商预设，也可选择「自定义兼容协议服务商」，手动填写自定义端点地址、API版本标识、请求头规则，完成后点击保存。
3. 切换默认密钥：选择侧边栏「密钥池」板块，点击「添加密钥」填入对应服务商颁发的API Key，上传后在密钥列表中右键点击目标密钥，选择「设为默认调用密钥」，软件会自动将密钥配置同步到原生Claude Code的环境变量文件中，无需手动修改配置。
4. 内置预设功能开启：点击侧边栏「全局配置」-「预设模板」，可一键开启「长文本自动分片」「代码生成速率限制」「上下文自动压缩」等预设能力，无需手动编写复杂规则。

5. 核心功能使用

1. 多密钥管理：支持批量导入最多1000条API密钥，可按服务商、额度类型对密钥分组，支持自定义权重分配不同密钥的调用占比，软件会自动识别密钥剩余可用额度，过滤失效密钥。
2. 用量统计：主界面仪表盘自动生成维度统计报表，展示近30天每日调用次数、Token消耗总量、剩余可用额度，支持将用量数据导出为CSV格式本地存档，方便团队内部对账核算。
3. 故障转移：开启该功能后，单条密钥调用出现超时、限流、权限报错等异常时，软件会自动将请求转发至下一条可用密钥，连续3次调用失败的密钥会被自动临时隔离，避免无效重试浪费额度。
4. v1.3.2新版专属功能：新增Claude 3.5 Sonnet 20241022最新模型流式输出优化，调用延迟降低30%以上；支持多工作区并行路由规则，可指定不同开发项目使用特定服务商的模型，同时兼容Claude Code官方最新v0.20+全版本的特性。

6. 常见问题排查

1. Windows平台报错：
   • 启动提示缺失VCRUNTIME140.dll：前往微软官方下载安装VC++ 2015-2022运行库即可解决
   • 便携版双击无响应：检查解压路径是否包含中文、特殊字符，将目录移动至根目录下重新运行即可
2. macOS平台报错：
   • Claude Code识别不到配置的密钥：打开终端执行cc-switch env export，将输出的环境变量配置写入~/.zshrc文件后重启终端即可生效
   • Homebrew安装后提示命令不存在：执行brew link --overwrite cc-switch强制关联二进制文件即可
3. Linux平台报错：
   • 图形界面启动无响应：检查系统是否开启SELinux，临时执行sudo setenforce 0测试，若可正常启动则为SELinux拦截规则问题，添加对应放行规则即可
4. 通用类报错：切换密钥后Claude Code仍然调用旧密钥：关闭所有Claude Code进程，手动删除用户目录下.claude文件夹内的cache子目录，重启CC-Switch后即可同步最新配置。

7. 更新与卸载说明

1. Windows平台：
   • 更新：安装版直接运行新版安装包，会自动覆盖旧版本完成升级；便携版直接将新版文件替换解压目录内的旧文件即可
   • 卸载：安装版从系统控制面板的「程序和功能」列表中找到CC-Switch执行卸载；便携版直接删除解压目录即可完全清除所有文件
2. macOS平台：
   • 更新：Homebrew安装的版本执行brew upgrade cc-switch即可完成升级；DMG安装的版本直接运行新版DMG镜像，将新应用覆盖Applications目录下的旧应用即可
   • 卸载：Homebrew安装的版本执行brew uninstall cc-switch即可；DMG安装的版本将应用从Applications拖入废纸篓，删除~/.config/cc-switch配置目录即可完全卸载
3. Linux平台：
   • 更新：deb/rpm格式安装的版本直接使用对应包管理工具执行升级命令即可；AppImage版本直接用新版文件替换旧文件即可
   • 卸载：deb包执行sudo apt remove cc-switch，rpm包执行sudo dnf remove cc-switch，AppImage版本直接删除AppImage文件和本地配置目录~/.config/cc-switch即可完成完全卸载。