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

---

1. 软件简介

CC-Switch 是专为 Anthropic 旗下 Claude Code 本地开发工具、Claude API 全链路服务设计的轻量级多密钥调度代理工具。
其核心定位是解决 Claude 系列产品在使用过程中出现的密钥切换混乱、区域访问限制、多密钥负载不均、调用中断无容灾等高频痛点，完全适配 Claude Code 官方客户端的所有接口逻辑。
本项目完全开源托管于开源社区，无闭源付费捆绑逻辑，所有基础功能永久免费开放，无任何隐性数据上传逻辑。
当前正式版最新版本号为 v2.1.0。

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

2. 全平台下载

所有平台的官方安装包均从上述官方镜像站分发，对应不同操作系统的安装包清单如下：

操作系统	安装包类型	完整文件名	适配架构
Windows	安装版	CC-Switch-v2.1.0-Windows-x64-Setup.exe	x86_64
Windows	便携版	CC-Switch-v2.1.0-Windows-x64-Portable.zip	x86_64
macOS	DMG手动安装包	CC-Switch-v2.1.0-macOS-Universal.dmg	Intel x86_64 + Apple Silicon M系列全架构
Linux	deb安装包	CC-Switch-v2.1.0-Linux-amd64.deb	x86_64
Linux	AppImage便携包	CC-Switch-v2.1.0-Linux-x86_64.AppImage	x86_64
Linux	rpm安装包	CC-Switch-v2.1.0-Linux-x86_64.rpm	x86_64

3. 分平台安装教程

3.1 Windows 平台安装

3.1.1 安装版安装步骤

1. 双击下载完成的 CC-Switch-v2.1.0-Windows-x64-Setup.exe 文件，在弹出的用户账户控制（UAC）弹窗中点击「是」授予权限
2. 自定义选择安装路径，默认路径为 C:\Program Files\CC-Switch，请勿选择包含中文、特殊字符的路径
3. 勾选「创建桌面快捷方式」「自动添加到系统PATH环境变量」两个可选配置项
4. 等待安装进度完成后，点击「立即启动」即可打开软件主界面

3.1.2 便携版安装步骤

1. 将下载的 CC-Switch-v2.1.0-Windows-x64-Portable.zip 解压到非系统盘的空白目录，例如 D:\Tools\CC-Switch
2. 无需写入系统注册表，直接双击目录内的 CC-Switch.exe 即可运行
3. 右键点击可执行文件，选择「发送到-桌面快捷方式」，后续可直接从桌面双击启动

3.2 macOS 平台安装

3.2.1 Homebrew 命令安装

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

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

安装完成后可直接在 Launchpad 找到 CC-Switch 图标点击启动，也可在终端直接输入 cc-switch 命令唤起运行。

3.2.2 DMG 手动安装

1. 双击下载完成的 CC-Switch-v2.1.0-macOS-Universal.dmg 挂载磁盘镜像
2. 在弹出的镜像窗口中，将左侧 CC-Switch 图标拖拽到右侧「应用程序」文件夹图标上完成拷贝
3. 首次启动时如果系统弹出「无法打开CC-Switch，因为来自身份未验证的开发者」提示，只需右键点击应用程序目录中的 CC-Switch 图标，选择「打开」，在二次确认弹窗中再次点击「打开」即可跳过系统公证限制正常启动。

3.3 Linux 平台安装

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

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

sudo dpkg -i ./CC-Switch-v2.1.0-Linux-amd64.deb
# 如果出现依赖缺失提示，执行以下命令自动补全依赖
sudo apt install -f

安装完成后可在应用程序菜单中找到 CC-Switch 入口，或终端执行 cc-switch 启动。

3.3.2 AppImage 便携包安装

在安装包所在目录打开终端，依次执行命令授予可执行权限并启动：

chmod +x ./CC-Switch-v2.1.0-Linux-x86_64.AppImage
./CC-Switch-v2.1.0-Linux-x86_64.AppImage

该格式无需写入系统目录，可存放在任意目录直接运行。

3.3.3 rpm 格式安装（适配 CentOS / Fedora / RHEL 等RedHat系发行版）

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

sudo rpm -ivh ./CC-Switch-v2.1.0-Linux-x86_64.rpm
# Fedora系统也可直接使用dnf命令自动补全依赖安装
sudo dnf install ./CC-Switch-v2.1.0-Linux-x86_64.rpm

4. 首次基础配置

1. 启动界面引导：首次启动软件会自动弹出初始化向导，默认监听本地代理地址 127.0.0.1:7899，无需复杂网络配置即可直接进入主界面。
2. 添加API服务商：点击左侧菜单栏「服务商管理」模块，点击「添加服务商」按钮，软件内置Anthropic官方、国内合规Claude代理服务商的预设模板，仅需填写对应服务商的API端点、自定义服务商备注名、API密钥内容，点击保存即可完成录入。
3. 切换默认密钥：在主界面顶部的密钥下拉选择栏，直接选中需要默认调用的密钥，系统会自动同步修改Claude Code全局环境变量中的ANTHROPIC_API_KEY参数，所有Claude系列客户端会自动路由到该密钥。
4. 内置预设功能开启：在左侧「预设规则」模块，可一键开启Claude 3全系列模型的速率配额阈值预设、Claude Code本地开发模式优化路由规则，无需用户手动编写代理规则，开启后自动生效。

5. 核心功能使用

1. 多密钥管理：支持最多同时导入100组Claude API密钥，可自定义分组标记密钥的服务商来源、配额类型、使用场景，支持批量导入/导出加密密钥清单，不会明文上传任何密钥数据到外部服务器。
2. 用量统计：自动实时统计每一组密钥的调用次数、输入/输出Token消耗、剩余额度，自动生成日/周/月维度的调用报表，支持导出为CSV格式用于对账和成本核算。
3. 故障转移：当某一组密钥触发限流、额度耗尽、网络连通失败时，系统会实现无感知自动切换到同分组下的下一个可用密钥，不会中断Claude Code正在运行的开发任务，完全避免调用报错。
4. v2.1.0新版专属功能：新增Claude Code全局上下文缓存调度功能，支持自定义多密钥轮询权重，新增区域网络智能择优路由，新增全链路调用请求日志溯源功能，可直接导出调试日志快速定位API调用报错原因。

6. 常见问题排查

1. Windows平台高频报错
   • 启动提示7899端口被占用：进入软件设置页面，修改监听端口为其他未占用端口如7900，重启软件即可解决。
   • 启动后闪退：检查软件存放路径是否包含中文、特殊字符，便携版请勿存放在桌面的中文命名目录下，右键点击程序选择「以管理员身份运行」即可修复。
2. macOS平台高频报错
   • 启动提示「CC-Switch已损坏，无法打开」：打开终端执行命令 xattr -d com.apple.quarantine /Applications/CC-Switch.app，输入本机开机密码确认后即可正常启动。
   • Claude Code未识别到配置的密钥：终端执行source ~/.zshrc（使用Bash的用户执行source ~/.bash_profile），重启Claude Code即可同步环境变量。
3. Linux平台高频报错
   • AppImage双击启动无响应：Deb系发行版执行sudo apt install fuse3，RHEL系发行版执行sudo dnf install fuse3补全FUSE运行依赖即可解决。
   • 终端输入cc-switch提示命令不存在：执行sudo ln -s /opt/CC-Switch/cc-switch /usr/local/bin/建立软链接即可正常调用。
4. 全平台通用报错：Claude Code返回401密钥错误，进入CC-Switch的「服务商管理」页面，点击对应密钥旁的「连通性测试」按钮，即可快速定位密钥填写错误、端点不通等问题。

7. 更新与卸载说明

7.1 更新操作

软件内置自动更新校验功能，点击顶部菜单栏「帮助-检查更新」即可自动识别最新正式版，下载对应平台的安装包后直接覆盖安装即可，所有已配置的密钥、自定义规则数据都会自动保留，无需手动重新导入。

7.2 卸载操作

• Windows安装版：打开「控制面板-程序和功能」，找到CC-Switch点击卸载，跟随向导确认操作即可，系统会自动清除之前添加的PATH环境变量配置。
• Windows便携版：直接删除解压后的软件目录即可，无任何注册表冗余残留。
• macOS Homebrew安装版：终端依次执行brew uninstall cc-switch && brew untap cc-switch/tap即可完全卸载。
• macOS DMG安装版：将「应用程序」目录内的CC-Switch拖拽到废纸篓，同时删除用户目录下的.cc-switch隐藏配置文件夹即可完全清除所有数据。
• Linux deb/rpm安装版：Deb系执行sudo apt remove cc-switch，RHEL系执行sudo dnf remove cc-switch即可完成卸载。
• Linux AppImage便携版：直接删除对应的AppImage文件即可，无任何系统文件残留。