CC-Switch 全平台部署使用官方教程【2026-05-31】

CC-Switch 全平台部署使用官方教程

1. 软件简介

CC-Switch 是专为 Claude Code 生态打造的开源轻量代理网关工具，核心作用是解决原生 Claude Code 不支持多API服务商接入、多密钥自动轮换、调用负载均衡的痛点，无需修改 Claude Code 核心代码即可实现全链路API请求的智能调度。该项目完全开源免费，无任何内置付费功能，托管于GitHub开源社区，当前最新稳定版本为v1.7.2。作为轻量化中间件工具，CC-Switch 对所有系统提供绿色免安装选项，无需写入系统注册表或全局环境变量即可正常运行。

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

2. 全平台下载

官方发布渠道仅提供上述夸克网盘合集与GitHub Release页两类下载入口，所有安装包均经过GPG签名校验，无恶意代码植入。三大平台对应安装包命名与格式如下：

1. Windows平台：安装版格式为EXE，文件名为CC-Switch-v1.7.2-Windows-Setup.exe；绿色便携版格式为7z压缩包，文件名为CC-Switch-v1.7.2-Windows-Portable.7z
2. macOS平台：统一通用安装包格式为DMG，支持Intel x86_64与Apple Silicon ARM64双架构，文件名为CC-Switch-v1.7.2-macOS-Universal.dmg
3. Linux平台：Debian系对应deb包文件名为cc-switch_1.7.2_amd64.deb；通用免安装格式AppImage文件名为CC-Switch-v1.7.2-Linux-x86_64.AppImage；RHEL系对应rpm包文件名为cc-switch-1.7.2.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台

3.1.1 安装版部署步骤

1. 双击下载的CC-Switch-v1.7.2-Windows-Setup.exe，若系统弹出用户账户控制提示，点击「是」允许运行
2. 选择软件安装路径，建议避免选择包含中文、空格的路径（例如默认路径C:\Program Files\CC-Switch可直接使用）
3. 勾选「创建桌面快捷方式」选项，点击下一步等待安装完成即可启动

3.1.2 绿色便携版部署步骤

1. 将下载的CC-Switch-v1.7.2-Windows-Portable.7z解压到纯英文无特殊字符的目录，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动，全程无需写入系统注册表，所有配置文件自动生成在当前解压目录内，拷贝到U盘可直接在其他设备运行

3.2 macOS平台

3.2.1 Homebrew命令安装

打开终端执行如下命令添加源并完成安装：

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

安装完成后直接在启动台找到CC-Switch图标点击运行即可

3.2.2 DMG手动安装

1. 双击下载的DMG文件，系统自动弹出挂载窗口
2. 将窗口内的CC-Switch图标拖拽到「应用程序」文件夹图标上完成拷贝
3. 首次启动时若系统提示「无法打开，因为来自身份不明的开发者」，右键点击启动台内的CC-Switch图标，选择「打开」即可跳过安全限制完成启动

3.3 Linux平台

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

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

sudodpkg-icc-switch_1.7.2_amd64.deb# 若出现依赖缺失报错，执行如下命令自动补全依赖sudoaptinstall-f

3.3.2 AppImage格式免安装部署

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

chmod+x CC-Switch-v1.7.2-Linux-x86_64.AppImage ./CC-Switch-v1.7.2-Linux-x86_64.AppImage

3.3.3 rpm格式安装（适用于Fedora、CentOS、RHEL等发行版）

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

sudorpm-ivhcc-switch-1.7.2.x86_64.rpm# 若依赖缺失可替换为dnf命令自动补全安装sudodnfinstall./cc-switch-1.7.2.x86_64.rpm

4. 首次基础配置

1. 启动界面初始化：首次启动时系统防火墙会弹出网络访问提示，点击「允许访问专用网络」即可，软件默认监听本地127.0.0.1的8787端口，主界面分为侧边功能栏、主配置区、运行日志区三个模块
2. 添加API服务商：点击侧边栏「服务商管理」选项，支持原生Anthropic官方、硅基流动、字节豆包Claude中转、火山引擎Claude等所有兼容Anthropic接口规范的服务商，输入服务商自定义名称、API端点地址、对应密钥后点击保存即可完成添加
3. 切换默认密钥：在侧边栏「密钥池」列表中，选中需要设为默认路由的密钥，点击列表右侧的「设为默认」按钮即可，所有Claude Code的默认请求将优先使用该密钥
4. 内置预设启用：点击主界面顶部的「预设模板」下拉菜单，可直接选择Claude 3 Opus、Claude 3.5 Sonnet、Claude 3 Haiku三类官方模型的配置预设，自动完成请求限速、超时阈值、最大并发数的参数配置，无需手动调整。

5. 核心功能使用

1. 多密钥管理：支持按服务商、模型类型对密钥进行分组，可单独设置每组密钥的轮询规则、权重占比，实现调用流量的智能分配，避免单一密钥触发平台限流
2. 用量统计：内置可视化统计看板，可按日/周/月维度查看单个密钥的调用次数、输入Token消耗、输出Token消耗、累计消费金额，所有数据自动本地存储不上传云端
3. 故障转移：开启故障转移开关后，若某条密钥返回401鉴权失败、429限流、503服务不可用三类错误，系统将自动跳过该密钥将请求转发给密钥池内下一条可用密钥，全程无需人工干预，Claude Code侧不会出现报错中断
4. v1.7.2新版专属功能：新增Claude Code一键适配模式，点击主界面「绑定Claude Code」按钮可自动读取本地已安装的Claude Code全局环境变量，无需手动配置端点即可完成代理挂载，同时新增上下文缓存共享功能，同一条对话的多个并行请求可复用历史上下文缓存，降低Token消耗最高可达40%。

6. 常见问题排查

1. Windows平台便携版双击无响应：排查解压路径是否包含中文、特殊字符，将整个文件夹移动到C:\Tools这类纯英文路径下重新运行即可；若提示端口被占用，可在配置文件中将默认监听端口从8787修改为其他未被占用的端口
2. macOS平台启动提示「应用已损坏」：打开终端执行命令xattr -d com.apple.quarantine /Applications/CC-Switch.app即可解除系统隔离限制
3. Linux平台AppImage双击无法启动：确认文件是否已赋予执行权限，部分发行版的文件管理器默认禁用可执行文件运行，需通过终端命令启动；若启动后找不到系统托盘图标，可安装libappindicator-gtk3依赖库解决
4. Claude Code侧提示连接被拒绝：确认CC-Switch处于运行状态，检查Claude Code的API端点配置是否填写为http://127.0.0.1:8787，若开启了系统代理需将本地地址加入代理免走名单。

7. 更新与卸载说明

1. 更新操作：所有平台版本均可直接点击主界面「关于」栏的「检查更新」按钮自动完成增量升级，无需手动重新下载安装包；若使用Homebrew、apt/dnf包管理器安装的版本，也可直接通过对应包管理器执行升级命令
2. Windows卸载：安装版可直接在控制面板的程序列表中选中CC-Switch点击卸载即可；便携绿色版无需卸载，直接删除解压目录即可清理所有文件
3. macOS卸载：Homebrew安装的版本执行brew uninstall cc-switch即可完成卸载；DMG手动安装的版本直接将应用程序文件夹内的CC-Switch拖拽到废纸篓即可清理
4. Linux卸载：deb包安装的版本执行sudo apt remove cc-switch即可清理，rpm包安装的版本执行sudo dnf remove cc-switch即可清理；AppImage版本直接删除对应文件即可完成卸载，无任何残留配置。