CC-Switch 全平台部署与使用正式教程【2026-05-31】

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

1. 软件简介

CC-Switch是专为Anthropic Claude Code命令行工具打造的轻量级API调度代理工具，核心定位是补全原生Claude Code缺失的多API密钥管理、多服务商兼容能力，大幅提升代码编写场景下的服务可用性。本项目完全开源且无任何内置付费逻辑，所有功能面向全用户免费开放，本次教程覆盖的最新稳定版本号为v1.3.2。

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

CC-Switch运行时会作为本地透明代理接管Claude Code的所有API请求，无需修改Claude Code原生配置文件即可实现动态切换密钥、自动故障转移等能力，全程不会上传任何用户密钥或对话数据到第三方服务器。

2. 全平台下载

本次发布包严格适配三大主流操作系统，所有包均通过官方哈希校验，无额外捆绑内容，各系统对应安装包明细如下：

1. Windows平台：提供两类安装包，分别为安装版CC-Switch-Setup-v1.3.2.exe、便携版CC-Switch-Portable-v1.3.2.zip
2. macOS平台：提供两类分发格式，分别为支持芯片自动适配的Homebrew源安装包、全芯片通用的磁盘镜像包CC-Switch-v1.3.2.dmg（单独提供x86_64/arm64架构独立包供老设备下载）
3. Linux平台：提供三类主流分发格式，分别为Deb系安装包cc-switch_1.3.2_amd64.deb、通用便携包CC-Switch-v1.3.2-x86_64.AppImage、RPM系安装包cc-switch-1.3.2.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装步骤

1. 双击下载得到的CC-Switch-Setup-v1.3.2.exe文件，在弹出的用户账户控制（UAC）弹窗中点击「是」授予权限
2. 选择软件安装路径，默认路径为C:\Program Files\CC-Switch，不建议安装到系统盘桌面或临时文件夹
3. 勾选「创建桌面快捷方式」「开机自动后台启动」可选选项，点击下一步等待安装完成
4. 安装完成后桌面自动生成CC-Switch图标，双击即可启动程序

3.1.2 便携版安装步骤

1. 将下载的CC-Switch-Portable-v1.3.2.zip压缩包解压到非系统临时目录，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动程序，所有配置文件会自动保存在当前解压目录中
3. 注意：请勿删除或移动解压后的文件夹，否则会导致所有配置、导入的密钥全部丢失

3.2 macOS平台安装

3.2.1 Homebrew命令安装

打开「启动台-其他-终端」应用，依次执行以下命令完成安装：

# 添加CC-Switch官方开源Tap源brew tap cc-switch-dev/tap# 执行安装命令brewinstallcc-switch# 启动程序open/usr/local/bin/cc-switch

3.2.2 DMG手动安装

1. 双击下载的CC-Switch-v1.3.2.dmg磁盘镜像文件，挂载镜像后在弹出的窗口中，将CC-Switch图标拖拽到「应用程序」文件夹图标上完成安装
2. 首次启动右键点击应用程序列表中的CC-Switch图标，选择「打开」，在系统弹出的「无法验证开发者」弹窗中再次点击「打开」即可绕过系统安全限制
3. 如果上述操作失败，可在终端执行以下命令绕过公证校验：

xattr-dcom.apple.quarantine /Applications/CC-Switch.app

3.3 Linux平台安装

3.3.1 Deb系发行版（Ubuntu/Debian/Mint等）安装

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

# 执行dpkg安装命令sudodpkg-icc-switch_1.3.2_amd64.deb# 修复可能缺失的依赖sudoaptinstall-f-y# 刷新系统桌面启动项缓存update-desktop-database

3.3.2 AppImage通用格式安装

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

# 给AppImage文件添加可执行权限chmod+x CC-Switch-v1.3.2-x86_64.AppImage# 直接运行程序./CC-Switch-v1.3.2-x86_64.AppImage

可将文件移动到/opt目录下长期保存，创建桌面快捷方式后即可直接点击启动。

3.3.3 RPM系发行版（CentOS/Fedora/RHEL等）安装

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

# 执行rpm安装命令sudorpm-ivhcc-switch-1.3.2.x86_64.rpm# 如遇到依赖缺失可使用dnf自动补全sudodnfinstall./cc-switch-1.3.2.x86_64.rpm

4. 首次基础配置

首次启动软件后将自动进入引导配置流程，按步骤操作即可完成基础适配：

1. 启动界面校验：首次启动后软件默认最小化到系统托盘（Windows）/顶部菜单栏（macOS/Linux），点击图标呼出主界面，系统将自动检测本地已安装的Claude Code命令行工具路径，如未检测到可手动填写~/.claude.json配置文件的路径完成绑定
2. 添加API服务商：进入「密钥管理」页面，点击「新增服务商」，可选择官方Anthropic、第三方Claude中转服务商两类模板，输入对应服务商提供的API密钥、自定义备注名后点击保存即可完成添加
3. 切换默认密钥：点击系统托盘内的CC-Switch图标，在弹出的下拉密钥列表中点击想要设为默认的密钥，选中后将自动接管当前所有Claude Code的API请求
4. 内置预设功能：软件内置三类开箱即用预设，分别为「Claude 3全系列模型路由预设」「全局代理一键配置预设」「低网速下超时自动重试预设」，新手用户直接点击「一键启用全部预设」即可无需手动调参直接使用。

5. 核心功能使用

1. 多密钥管理：支持批量导入最多100组API密钥，可按个人测试场景、团队协作场景分组，自动识别密钥到期时间提前7天弹出提醒，支持一键导出加密备份所有密钥
2. 用量统计：后台自动定时拉取每一组密钥的Token消耗、剩余额度统计数据，生成日/周/月维度的使用报表，可直接导出CSV表格用于对账，所有统计数据完全存储在本地不会上传
3. 故障转移：开启该功能后，软件会实时监测Claude Code返回的API请求状态，遇到401密钥无效、429请求限流、5xx服务端报错时，会自动跳过故障密钥切换到下一个可用密钥，全程无需人工干预，完全不会中断正在运行的Claude Code代码生成任务
4. v1.3.2新版专属功能：新增会话级密钥绑定能力，支持同时开多个Claude Code终端窗口时给不同窗口分配独立密钥，避免单密钥限流；新增自定义路由规则，可指定不同类型代码请求走指定服务商的模型通道。

6. 常见问题排查

1. Windows平台高频报错：
   • 报错提示「缺少VCRUNTIME140.dll」：解决方法为下载安装微软官方VC++ 2015-2022运行库即可修复
   • 系统托盘不显示CC-Switch图标：右键点击任务栏空白处，选择「任务栏设置-选择哪些图标显示在任务栏上」，开启CC-Switch的图标显示权限即可
2. macOS平台高频报错：
   • 启动后提示「CC-Switch已损坏，无法打开」：进入「系统设置-隐私与安全性」，下拉到安全性区域，点击「仍要打开」按钮验证系统权限即可
   • 无法读取Claude Code配置文件：进入「系统设置-隐私与安全性-全磁盘访问权限」，勾选CC-Switch的访问权限后重启程序即可
3. Linux平台高频报错：
   • AppImage文件双击无响应：确认已通过终端命令添加文件可执行权限，部分发行版默认禁用非应用商店来源可执行文件，可关闭安全沙箱限制后重试
   • 端口占用报错提示「8787端口已被占用」：进入CC-Switch设置页面，将默认代理端口修改为其他未占用端口，重启程序后自动同步Claude Code的代理配置即可。

7. 更新与卸载说明

1. Windows平台：安装版用户可点击软件设置页面的「检查更新」按钮，一键自动下载替换新版完成升级，卸载时可直接在控制面板的「程序和功能」列表中找到CC-Switch点击卸载即可；便携版用户直接下载新版压缩包覆盖旧文件即可完成升级，卸载时直接删除解压的整个文件夹即可，残留配置可手动删除%APPDATA%\cc-switch目录。
2. macOS平台：Homebrew安装用户执行brew upgrade cc-switch命令即可完成升级，卸载执行brew uninstall cc-switch即可；DMG安装用户直接下载新版DMG包替换应用程序内的旧文件即可，卸载时将CC-Switch拖拽到废纸篓，手动删除~/Library/Application Support/cc-switch目录即可清除所有配置。
3. Linux平台：Deb系用户下载新版deb包后执行sudo dpkg -i cc-switch_1.3.x_amd64.deb即可完成升级，卸载执行sudo apt remove cc-switch；AppImage用户直接替换旧的二进制文件即可完成升级，删除文件即完成卸载；RPM系用户下载新版rpm包后执行sudo rpm -Uvh cc-switch-1.3.x.x86_64.rpm完成升级，卸载执行sudo rpm -e cc-switch即可。