CC-Switch 多供应商配置全平台技术教程

1. 软件简介

CC-Switch 是面向 Claude Code 生态专门开发的多供应商API调度代理工具，核心作用是突破原生Claude Code仅支持单官方API密钥的限制，实现跨服务商的大模型请求路由、负载均衡与故障自愈。
该软件为完全开源项目，采用MIT开源协议发布，无内置收费模块、无数据上传云端逻辑，所有密钥与调用记录全本地存储。
当前最新稳定版本为 v1.8.2，全平台二进制包均经过安全校验可直接部署使用。

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

2. 全平台下载

所有版本安装包均已在上述统一下载入口归档，三大平台对应的安装包格式与文件名如下：

1. Windows平台：分为安装版 CC-Switch_v1.8.2_Windows_Setup.exe、便携版 CC-Switch_v1.8.2_Windows_Portable.zip
2. macOS平台：分为Homebrew自动安装包、ARM架构专用DMG安装包 CC-Switch_v1.8.2_macOS_arm64.dmg、Intel架构专用DMG安装包 CC-Switch_v1.8.2_macOS_x64.dmg
3. Linux平台：分为Deb系deb安装包 cc-switch_1.8.2_amd64.deb、通用AppImage运行包 CC-Switch_v1.8.2_Linux_amd64.AppImage、RHEL系rpm安装包 cc-switch-1.8.2.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装步骤

1. 从下载目录双击运行CC-Switch_v1.8.2_Windows_Setup.exe，若系统弹出用户账户控制提示，点击「是」允许程序运行
2. 勾选同意用户许可协议，自定义安装路径（禁止选择含中文或特殊字符的路径，例如D:\Program Files\CC-Switch），不推荐安装到系统盘临时目录
3. 勾选「创建桌面快捷方式」「添加系统PATH环境变量」选项，点击安装等待进度条走完，点击完成即可启动程序
4. 首次启动时Windows Defender防火墙会弹出网络访问提示，勾选「专用网络」「公用网络」两个选项后点击允许访问，确保本地代理端口正常监听

3.1.2 便携版安装步骤

1. 解压CC-Switch_v1.8.2_Windows_Portable.zip压缩包到非系统临时文件夹，例如D:\Tools\CC-Switch
2. 直接双击运行主程序CC-Switch.exe即可启动，所有配置数据会自动保存在当前解压目录的data文件夹内，无系统注册表写入，拷贝到其他电脑可直接运行无需重新配置

3.2 macOS平台安装

3.2.1 Homebrew命令安装

打开终端应用，依次执行以下命令即可完成自动安装，安装完成后可直接在Launchpad找到程序图标：

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

3.2.2 DMG手动安装步骤

1. 双击下载好的对应架构DMG文件，弹出挂载窗口后，将CC-Switch图标拖拽到「应用程序」文件夹图标上完成拷贝
2. 首次启动时不要直接双击打开，右键点击应用程序目录内的CC-Switch.app文件，选择「打开」，在弹出的「无法验证开发者」提示窗口点击「打开」即可正常启动
3. 如果上述操作仍无法启动，可打开「系统设置-隐私与安全性」，下拉到安全区域，点击「仍要打开」按钮完成授权

3.3 Linux平台安装

3.3.1 deb格式（适配Debian/Ubuntu/Mint等发行版）

打开终端进入下载目录，依次执行以下命令：

# 执行安装
sudo dpkg -i cc-switch_1.8.2_amd64.deb
# 若提示依赖缺失，自动补全依赖
sudo apt install -f

安装完成后可在应用程序菜单找到CC-Switch启动图标，或直接终端输入cc-switch启动。

3.3.2 AppImage通用格式（适配所有主流Linux发行版）

打开终端进入下载目录，依次执行以下命令：

# 赋予程序执行权限
chmod +x CC-Switch_v1.8.2_Linux_amd64.AppImage
# 直接运行程序
./CC-Switch_v1.8.2_Linux_amd64.AppImage

该格式无需安装，所有配置默认保存在用户主目录的隐藏文件夹.cc-switch内。

3.3.3 rpm格式（适配RHEL/CentOS/Fedora/openSUSE等发行版）

打开终端进入下载目录，执行以下命令：

sudo dnf install ./cc-switch-1.8.2.x86_64.rpm

如果使用yum作为包管理器，可将上述命令中的dnf替换为yum执行。

4. 首次基础配置

1. 启动界面介绍：程序首次启动后默认进入调度总览面板，顶部显示本地代理默认监听地址为http://127.0.0.1:8787，侧边栏包含服务商管理、密钥池管理、用量统计、系统设置4个核心功能模块。
2. 添加API服务商：点击侧边栏「服务商管理」，点击右上角「添加服务商」，软件内置了Anthropic官方、主流第三方合规代理、OpenAI兼容网关等17种常用服务商的预设模板，选择对应模板后自动填充API端点、请求头规则、模型映射规则，无需手动调整复杂参数。
3. 切换默认密钥：进入「密钥池管理」页面，点击「导入密钥」，输入对应服务商的API密钥后，可给密钥打标签、设置单密钥速率上限，勾选目标密钥的「默认路由」选项，即可将该密钥设为Claude Code的默认调用密钥。随后打开Claude Code的全局配置文件，将API代理端点修改为CC-Switch的本地监听地址http://127.0.0.1:8787即可完成关联。
4. 内置预设功能：在服务商管理页面点击「一键导入预设」，可直接导入社区分享的合规代理服务商全量配置，仅需填入自己的密钥即可直接使用，无需手动填写端点、模型映射等参数。

5. 核心功能使用

1. 多密钥管理：支持批量导入最多1000条不同服务商的密钥，可按模型类型、服务商品牌分组管理，针对不同的Claude大模型（Claude 3 Opus/Sonnet/Haiku）绑定独立的密钥池，实现模型维度的密钥路由隔离。
2. 用量统计：自动实时统计每一条密钥的累计调用次数、输入输出Token消耗量、剩余可用额度，支持生成日/周/月维度的调用报表，可导出为CSV格式本地存储，避免出现密钥超额扣费的问题。
3. 故障转移：开启故障转移开关后，当单条密钥触发429限流、503服务不可用、401密钥失效等错误时，系统会自动将请求切换到密钥池内的下一条可用密钥，最多支持3次自动重试，全程不中断Claude Code的当前会话请求，大幅提升服务可用性。
4. v1.8.2新版专属功能：新增权重配置式负载均衡策略，支持给不同服务商的密钥设置调用权重，实现流量的动态分配；新增本地请求缓存功能，相同的Prompt请求无需重复调用大模型，最高可降低40%的Token消耗；新增Claude Code会话自动同步功能，所有本地历史会话记录可自动备份到CC-Switch的本地数据库内，跨设备可直接导入恢复。

6. 常见问题排查

1. Windows平台高频问题
   • 问题：启动后提示端口8787被占用：进入系统设置-网络设置，将CC-Switch的默认监听端口修改为其他未被占用的端口（例如8788），同时同步修改Claude Code配置内的代理端点端口即可。
   • 问题：Claude Code提示无法连接API：检查Windows防火墙是否放行CC-Switch的入站规则，部分安全软件会默认拦截本地端口的访问，将CC-Switch加入白名单即可解决。
2. macOS平台高频问题
   • 问题：Homebrew安装后终端输入cc-switch提示命令不存在：在终端执行brew link cc-switch --overwrite命令重新创建软链接即可。
   • 问题：启动后程序菜单栏不显示：打开「系统设置-通用-登录项」，将CC-Switch加入开机自启列表后重启电脑即可修复。
3. Linux平台高频问题
   • 问题：AppImage双击运行无响应：大概率是未赋予执行权限，重新执行chmod +x ./CC-Switch_v1.8.2_Linux_amd64.AppImage命令即可解决。
   • 问题：deb包安装后启动闪退：执行sudo apt install libssl3 libglib2.0-0补全系统依赖即可正常启动。
4. 通用问题
   • 问题：提示密钥校验失败：检查服务商配置的API端点末尾是否添加了/v1前缀，模型映射规则是否与服务商提供的模型ID完全匹配，修正配置后重新导入密钥即可。

7. 更新与卸载说明

1. Windows平台
   • 更新：安装版直接运行新版安装包，选择覆盖旧版本安装即可，所有历史配置会自动保留；便携版直接将新版压缩包解压到旧版本目录下覆盖文件即可完成更新。
   • 卸载：安装版可从控制面板-程序和功能列表找到CC-Switch点击卸载即可完全清除；便携版直接删除整个解压文件夹即可完成卸载，无任何系统残留。
2. macOS平台
   • 更新：Homebrew安装的版本直接在终端执行brew upgrade cc-switch即可完成自动更新；DMG安装的版本用新版DMG内的程序覆盖应用程序文件夹内的旧版本文件即可。
   • 卸载：Homebrew安装的版本执行brew uninstall cc-switch即可完全卸载；DMG安装的版本直接将应用程序文件夹内的CC-Switch拖拽到废纸篓即可。
3. Linux平台
   • 更新：deb包安装的版本直接执行sudo dpkg -i 新版deb包路径覆盖安装即可；rpm包安装的版本执行sudo dnf update 新版rpm包路径完成更新；AppImage格式直接替换新版文件即可完成更新。
   • 卸载：deb包执行sudo apt remove cc-switch，rpm包执行sudo dnf remove cc-switch即可完全清除所有系统文件；AppImage格式直接删除对应的文件，同时删除用户主目录下的.cc-switch隐藏文件夹即可完全清除所有配置数据。