CC-Switch 全平台适配使用教程（含Apple Silicon原生优化版）

1. 软件简介

CC-Switch是专为Anthropic官方代码助手Claude Code打造的第三方API流量调度中间件，核心解决原生Claude Code客户端仅支持官方API通道、无法接入兼容OpenAI协议的第三方服务商、多密钥切换繁琐的痛点。
其定位为Claude Code生态的轻量无侵入代理层，完全开源托管于公开代码仓库，无任何后台数据上报、无付费锁限制，所有功能对个人开发者完全免费开放。
目前最新正式版本为v1.4.0，已完成Apple Silicon架构全栈原生适配，所有M系列、M2 Ultra、M3系列芯片的Mac设备无需Rosetta 2转译即可运行，运行功耗降低40%以上，资源占用率仅为同版本Intel架构应用的60%。
CC-Switch无需修改Claude Code客户端的底层配置文件，仅需在本地挂载端口转发规则即可完成全链路接管，支持所有符合OpenAI兼容协议的大模型服务商接入。

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

2. 全平台下载

本版本所有安装包均经过架构适配验证，可根据自身操作系统选择对应文件：

2.1 Windows平台

• 安装版包格式：.exe 可执行程序，文件名：CC-Switch-v1.4.0-win64-setup.exe
• 便携版包格式：.zip 压缩包，文件名：CC-Switch-v1.4.0-win64-portable.zip

2.2 macOS平台

• Homebrew命令安装包：自动匹配当前设备芯片架构，Apple Silicon设备自动拉取arm64原生二进制文件
• DMG手动安装包分双架构版本：Apple Silicon专属版文件名CC-Switch-v1.4.0-macOS-arm64.dmg，Intel架构版文件名CC-Switch-v1.4.0-macOS-x64.dmg

2.3 Linux平台

• deb格式包：提供amd64和arm64两个架构版本，文件名分别为cc-switch_1.4.0_amd64.deb、cc-switch_1.4.0_arm64.deb
• rpm格式包：提供x86_64和aarch64两个架构版本，文件名分别为cc-switch-1.4.0-1.x86_64.rpm、cc-switch-1.4.0-1.aarch64.rpm
• AppImage格式包：全架构通用便携版，文件名分别为CC-Switch-v1.4.0-linux-x64.AppImage、CC-Switch-v1.4.0-linux-arm64.AppImage

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装步骤

1. 双击下载得到的CC-Switch-v1.4.0-win64-setup.exe，若系统弹出SmartScreen安全提示，点击「更多信息」后选择「仍要运行」
2. 自定义安装路径，建议避开C盘系统保护目录，勾选「添加桌面快捷方式」「添加系统PATH环境变量」选项
3. 点击「立即安装」，等待进度条完成后勾选「立即启动CC-Switch」，确认Windows Defender防火墙弹窗中所有网络权限均已放行

3.1.2 便携版安装步骤

1. 将CC-Switch-v1.4.0-win64-portable.zip解压到非系统盘的纯英文路径下，路径中禁止出现中文、特殊符号
2. 直接双击解压目录内的CC-Switch.exe即可启动，所有配置数据均保存在当前目录的config文件夹中，不会写入系统注册表，可直接拷贝到U盘在其他设备运行

3.2 macOS平台安装

3.2.1 Homebrew命令安装

打开终端执行以下命令，Apple Silicon设备会自动拉取原生arm64版本，无需转译：

# 添加官方软件源
brew tap cc-switch/official
# 执行安装
brew install cc-switch
# 启动GUI客户端
open /opt/homebrew/Cellar/cc-switch/1.4.0/CC-Switch.app

3.2.2 DMG手动安装

1. 双击下载的CC-Switch-v1.4.0-macOS-arm64.dmg，将CC-Switch图标拖拽到「应用程序」文件夹完成写入
2. 首次启动时右键点击启动台内的CC-Switch图标，选择「打开」，在弹出的「开发者未被验证」提示框中再次点击「打开」即可正常运行
3. 若仍提示无法启动，进入「系统设置-隐私与安全性」页面，下滑到底部找到「已阻止使用CC-Switch」的提示，点击「仍要打开」完成授权

3.3 Linux平台安装

3.3.1 deb格式安装（Debian/Ubuntu系发行版）

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

# 执行安装
sudo dpkg -i cc-switch_1.4.0_arm64.deb
# 修复可能出现的依赖缺失问题
sudo apt --fix-broken install -y
# 启动客户端
cc-switch

3.3.2 rpm格式安装（CentOS/RHEL/Fedora系发行版）

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

# 执行安装
sudo dnf install ./cc-switch-1.4.0-1.aarch64.rpm -y
# 启动客户端
cc-switch

3.3.3 AppImage格式安装

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

# 添加可执行权限
chmod +x CC-Switch-v1.4.0-linux-arm64.AppImage
# 直接启动运行
./CC-Switch-v1.4.0-linux-arm64.AppImage

4. 首次基础配置

1. 启动界面初始化：首次启动会弹出初始化引导页，默认本地监听端口为18989，若该端口已被其他软件占用可手动修改端口号，点击「确认生成本地转发规则」完成第一步配置
2. 添加API服务商：点击左侧菜单栏「服务商管理」，可选择内置预设的通义千问、豆包、DeepSeek、SiliconFlow等20+主流大模型服务商，自动填充API地址，仅需输入个人API密钥后点击「保存」即可生效；也可选择「自定义服务商」填写私有部署的大模型API对接参数
3. 切换默认密钥：点击顶部「全局调度面板」，在已添加的密钥列表中勾选需要设为默认优先级的密钥，点击「设为当前优先」即可完成切换
4. 内置预设功能启用：点击首页「Claude Code一键适配」按钮，复制生成的环境变量配置脚本，粘贴到终端执行后即可让本地Claude Code客户端自动将API请求转发到CC-Switch的本地端口，无需修改Claude Code任何底层配置文件

5. 核心功能使用

1. 多密钥管理：支持批量导入上百条API密钥，可单独为每个密钥设置流量权重、并发上限、过期时间，系统会自动过滤已经过期的无效密钥，无需手动维护
2. 用量统计：内置可视化看板，实时展示每个API服务商的Token消耗、请求成功率、平均响应延迟，支持按日/周/月维度导出用量报表，精准控制调用成本
3. 故障转移：可自定义故障转移阈值，默认连续3次请求失败时自动将当前故障密钥移出调度队列，自动切换到下一个可用密钥，避免Claude Code代码补全过程中出现请求中断报错，完全无感知切换
4. Apple Silicon专属新版功能：v1.4.0版本新增Apple Neural Engine硬件加速模块，密钥签名校验速度比x64版本提升210%，同时支持Claude Code会话上下文本地智能缓存，相同上下文重复请求可减少70%以上的Token消耗，大幅降低Apple Silicon设备运行时的风扇转速，后台空闲时CPU占用率低于1%

6. 常见问题排查

1. Windows平台高频报错：启动提示「端口18989被占用」，打开终端执行netstat -ano | findstr 18989查询占用进程PID，在任务管理器中结束对应进程即可，或直接在CC-Switch初始化界面修改监听端口为其他未使用端口
2. Apple Silicon macOS平台高频报错：启动提示「CC-Switch已损坏，无法打开」，打开终端执行xattr -d com.apple.quarantine /Applications/CC-Switch.app，去除系统隔离属性后即可正常启动
3. Linux平台高频报错：启动后Claude Code提示「连接被拒绝」，检查系统防火墙是否开放18989端口，执行sudo ufw allow 18989/tcp放行端口后即可恢复
4. 全平台通用报错：Claude Code提示「API密钥无效」，进入CC-Switch服务商管理页面检查密钥是否填写正确，点击「连通性测试」按钮自动检测服务商链路可用性，排除链路故障后即可恢复

7. 更新与卸载说明

7.1 更新操作

• Windows安装版：点击设置页面的「检查更新」按钮，系统自动下载新版安装包完成覆盖升级，原有配置数据不会丢失；便携版直接将新版exe文件替换旧版文件即可完成升级
• macOS Homebrew安装版：终端执行brew upgrade cc-switch即可自动完成升级；DMG安装版直接双击新DMG文件，将新版CC-Switch拖拽到应用程序文件夹覆盖旧版即可
• Linux deb/rpm格式安装版：直接下载新版安装包执行相同的安装命令，系统自动覆盖旧版本；AppImage便携版直接替换为新的AppImage文件即可完成升级

7.2 卸载操作

• Windows安装版：进入控制面板-程序和功能，找到CC-Switch点击卸载即可，勾选「删除所有配置文件」选项可完全清理所有数据；便携版直接删除解压目录即可完全卸载
• macOS Homebrew安装版：终端执行brew uninstall cc-switch，再删除应用程序目录下的残留文件即可；DMG安装版直接将CC-Switch图标从应用程序拖拽到废纸篓即可完成卸载
• Linux deb/rpm格式安装版：执行sudo apt remove --purge cc-switch或sudo dnf remove cc-switch即可完全卸载；AppImage便携版直接删除AppImage文件即可无残留卸载