CC-Switch 全平台正式使用教程

1. 软件简介

CC-Switch 是Claude Code生态下专为Anthropic系列大模型设计的开源代理网关工具，核心作用是解决官方API密钥单账号限流、配额不足、失效后中断服务的痛点，实现多密钥的自动轮换与负载均衡，大幅提升Claude Code开发场景的稳定性。
该工具是目前Claude Code配套生态中用户量最高的密钥管理类工具，完全遵循MIT开源协议，所有代码公开可审计无后门，当前最新正式版本为v1.2.7。
所有版本全平台绿色无捆绑，用户可通过以下高速通道直接获取全版本安装包：

---

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

2. 全平台下载

官方校验入口为CC-Switch GitHub Releases公开页面，所有安装包均附带GPG签名可验证完整性，各平台对应安装包文件名如下：

1. Windows平台：CC-Switch_Setup_x64_v1.2.7.exe（标准安装版）、CC-Switch_Portable_x64_v1.2.7.zip（便携免安装版）
2. macOS平台：CC-Switch_arm64_v1.2.7.dmg（M系列芯片专用）、CC-Switch_x64_v1.2.7.dmg（Intel芯片专用），同时支持Homebrew仓库一键安装
3. Linux平台：cc-switch_amd64_v1.2.7.deb（Debian/Ubuntu系专用）、CC-Switch-x86_64-v1.2.7.AppImage（全发行版通用便携版）、cc-switch.x86_64_v1.2.7.rpm（CentOS/RHEL/Fedora系专用）

3. 分平台安装教程

3.1 Windows 系统安装

3.1.1 便携版安装（推荐）

1. 将下载的CC-Switch_Portable_x64_v1.2.7.zip压缩包解压到非系统盘的纯英文路径下，禁止解压到C:\Program Files等需要管理员权限的系统目录
2. 进入解压后的根目录，直接双击CC-Switch.exe即可启动，无需修改注册表、无需写入系统目录
3. 所有配置文件、密钥数据库、日志均自动保存在解压目录下的data子文件夹中，移动整个文件夹即可直接迁移使用，重装系统不会丢失数据

3.1.2 标准安装版安装

1. 双击运行CC-Switch_Setup_x64_v1.2.7.exe，确认UAC弹窗的管理员权限申请
2. 选择目标安装路径，按引导点击下一步即可完成安装，桌面会自动生成快捷启动图标

3.2 macOS 系统安装

3.2.1 Homebrew 命令行安装（推荐开发者使用）

打开终端依次执行以下命令，即可自动完成安装和环境变量适配：

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

安装完成后可直接在Launchpad找到启动图标，也可通过终端输入cc-switch命令直接拉起服务。

3.2.2 DMG 手动安装

1. 双击下载的对应芯片架构的DMG文件，在弹出的窗口中将CC-Switch图标拖拽到「应用程序」文件夹完成拷贝
2. 首次启动如果弹出「无法验证开发者」的系统提示，右键点击Launchpad中的CC-Switch图标，选择「打开」即可跳过系统安全限制正常启动。

3.3 Linux 系统安装

3.3.1 deb格式安装（Debian/Ubuntu 20.04+）

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

sudo apt install ./cc-switch_amd64_v1.2.7.deb

安装完成后自动生成系统启动菜单，可在应用列表直接打开。

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

打开终端进入安装包所在目录，先为文件赋予执行权限后直接运行：

chmod +x CC-Switch-x86_64-v1.2.7.AppImage
./CC-Switch-x86_64-v1.2.7.AppImage

无需安装依赖，双击即可直接启动使用。

3.3.3 rpm格式安装（CentOS8+/Fedora/RHEL8+）

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

sudo dnf install ./cc-switch.x86_64_v1.2.7.rpm

4. 首次基础配置

1. 启动界面确认：首次启动后工具会自动在本地监听127.0.0.1:7897端口，浏览器访问http://127.0.0.1:7897即可打开可视化管理后台，默认未设置访问密码，可按需自行配置。
2. 添加API服务商：进入管理后台的「服务商管理」页面，支持接入Anthropic官方API、合规中转服务商等多类源，填写服务商的API接入端点后点击保存即可。
3. 切换默认密钥：进入「密钥管理」页面，可直接粘贴自己的Anthropic密钥添加，勾选对应密钥前的单选框即可将其设为Claude Code默认调用的主密钥。
4. 内置预设启用：工具内置Claude Code专属适配预设，点击「一键生成Claude Code环境变量」按钮即可直接得到对应终端配置命令，直接复制粘贴到终端运行即可完成Claude Code的代理对接，无需手动修改配置文件。

5. 核心功能使用

1. 多密钥批量管理：支持单条添加、CSV批量导入密钥，可对密钥进行分组打标签、设置单日请求上限、到期时间提醒，所有密钥使用AES256加密存储在本地，不会上传到任何第三方服务器。
2. 全维度用量统计：自动统计每一条密钥的请求次数、输入/输出Token消耗、剩余配额，支持按日/周/月维度导出用量报表，可直接对接个人记账、团队分摊场景。
3. 智能故障转移：开启故障转移开关后，工具会自动检测密钥返回的401失效、429限流、5xx服务错误等异常状态，自动将请求转发到下一条可用密钥，全程无需人工干预，Claude Code不会出现服务中断。
4. v1.2.7版专属新功能：新增Claude 3.5 Sonnet 20241022版本的上下文缓存配额统计，新增微信/邮箱密钥告警通知，新增加密配置跨设备同步功能，支持在多台开发机之间同步密钥库无需重复导入。

6. 常见问题排查

1. Windows便携版启动闪退：确认解压路径不包含中文、特殊符号，同时不要放在受系统权限保护的系统目录下，移动到D盘等非系统盘普通文件夹即可解决。
2. macOS启动后Claude Code无法连接网关：进入「系统设置-隐私与安全性-防火墙」，找到CC-Switch勾选允许传入连接，即可解除 macOS 系统的网络拦截。
3. Linux AppImage双击无响应：该问题由系统缺失FUSE2依赖导致，执行命令sudo apt install fuse2（Debian/Ubuntu系）或sudo dnf install fuse（Fedora系）安装依赖后即可正常启动。
4. 密钥导入后显示无效：检查密钥是否以官方要求的sk-ant-开头，确认粘贴过程中没有多余的换行、空格字符，剔除无效字符后重新导入即可识别。
5. 端口7897被占用：进入工具的「系统设置」页面，将监听端口修改为其他未被占用的端口，同步更新Claude Code的环境变量中对应的端点地址即可。

7. 更新与卸载说明

1. Windows平台：便携版直接解压新版压缩包，覆盖旧版目录的所有文件即可完成更新，所有原有配置会自动保留；卸载时直接删除整个解压目录即可，无任何残留文件。安装版可通过内置的「检查更新」功能一键升级，卸载时进入「控制面板-程序和功能」找到CC-Switch点击卸载即可。
2. macOS平台：Homebrew安装的版本执行brew upgrade cc-switch即可一键更新，执行brew uninstall cc-switch即可完成卸载；DMG手动安装的版本直接将应用程序中的CC-Switch拖入废纸篓，同时删除~/.config/cc-switch路径下的配置文件夹即可完全卸载。
3. Linux平台：deb/rpm格式安装的版本直接重新下载新版安装包执行安装命令即可覆盖更新，卸载分别执行sudo apt remove cc-switch、sudo dnf remove cc-switch即可；AppImage便携版直接替换新版AppImage文件即可完成更新，删除对应文件就完全卸载，无任何系统残留。