CC-Switch v2.7.0 全平台正式版操作教程

1. 软件简介

CC-Switch是专为Anthropic Claude Code系列客户端打造的开源API调度增强工具，核心定位为轻量透明代理层，无需修改Claude Code客户端底层代码即可实现多API服务商、多密钥的统一管理，解决原生Claude Code仅支持绑定单一Anthropic官方密钥、多线路切换操作繁琐、无法自动故障重试、用量统计缺失的核心痛点。
本工具完全开源免费，无内置付费功能、无额外数据上传行为，所有调度逻辑均在本地运行，不会泄露用户API密钥与对话数据。
本次发布的最新稳定版本为v2.7.0，新增macOS原生菜单栏常驻功能、Claude Code CLI一键联动调度能力，同步完成Windows、macOS、Linux全平台适配优化。
用户可通过以下指定渠道获取全平台安装包：

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

2. 全平台下载

所有安装包均已完成数字签名校验，可直接解压/安装使用，各系统对应安装包信息如下：

1. Windows平台：
   • 安装版文件名：CC-Switch-v2.7.0-Windows-x64-Setup.exe，格式为exe可执行安装包，适配Windows 10/11 x64系统
   • 便携版文件名：CC-Switch-v2.7.0-Windows-x64-Portable.zip，格式为绿色压缩包，无需写入系统注册表
2. macOS平台：
   • 官方Homebrew源已同步上架v2.7.0版本，支持Apple Silicon M系列芯片与Intel芯片全架构适配
   • DMG手动安装包文件名：CC-Switch-v2.7.0-macOS-universal.dmg，格式为磁盘镜像包，大小仅28MB
3. Linux平台：
   • Deb格式包文件名：CC-Switch-v2.7.0-Linux-amd64.deb，适配Debian/Ubuntu/UOS等Debian系发行版
   • AppImage格式包文件名：CC-Switch-v2.7.0-Linux-x86_64.AppImage，通用绿色包，适配所有主流Linux发行版
   • Rpm格式包文件名：CC-Switch-v2.7.0-Linux-x86_64.rpm，适配CentOS/RHEL/Fedora等RPM系发行版

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装步骤

1. 双击运行下载的CC-Switch-v2.7.0-Windows-x64-Setup.exe，如果系统弹出用户账户控制提示，点击「是」允许程序修改设备
2. 在安装向导中选择程序安装路径，默认路径为C:\Program Files\CC-Switch，不建议选择中文路径避免运行异常
3. 勾选「创建桌面快捷方式」「添加到系统启动项」选项，点击「安装」等待进度条完成后即可启动软件

3.1.2 便携版安装步骤

1. 将下载的CC-Switch-v2.7.0-Windows-x64-Portable.zip压缩包解压到非系统盘的任意纯英文路径文件夹内
2. 右键点击解压目录内的CC-Switch.exe文件，选择「发送到-桌面快捷方式」，双击即可直接启动，所有配置数据均保存在当前解压目录内，迁移设备时直接拷贝文件夹即可同步所有配置

3.2 macOS平台安装

3.2.1 Homebrew命令安装

打开「终端」应用，依次执行以下命令即可自动完成安装：

# 添加上游官方源
brew tap cc-switch/tap
# 执行安装命令
brew install cc-switch
# 启动软件
open /Applications/CC-Switch.app

3.2.2 DMG手动安装

1. 双击打开下载的CC-Switch-v2.7.0-macOS-universal.dmg文件，在弹出的挂载窗口中，将左侧CC-Switch图标拖拽到右侧「应用程序」文件夹图标上，等待拷贝完成即完成安装
2. 首次启动时如果系统弹出「无法打开‘CC-Switch’，因为Apple无法检查其是否包含恶意软件」的安全提示，右键点击启动台/应用程序文件夹内的CC-Switch图标，选择「打开」，在二次确认弹窗中再次点击「打开」即可正常启动，无需修改系统全局安全设置

3.3 Linux平台安装

3.3.1 Deb格式安装（Debian/Ubuntu系）

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

# 执行安装操作
sudo dpkg -i CC-Switch-v2.7.0-Linux-amd64.deb
# 若提示依赖缺失，执行以下命令自动补全依赖
sudo apt install -f

安装完成后可在应用程序列表中找到CC-Switch启动图标。

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

打开终端进入安装包所在目录，执行以下命令添加执行权限后即可直接运行：

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

3.3.3 Rpm格式安装（CentOS/RHEL/Fedora系）

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

# 执行安装操作
sudo dnf install ./CC-Switch-v2.7.0-Linux-x86_64.rpm

安装完成后可在应用程序列表中找到CC-Switch启动图标。

4. 首次基础配置

1. 启动界面认知：软件首次启动后默认最小化运行在系统托盘/菜单栏中，主界面分为密钥管理、用量统计、设置三大标签页，默认本地监听端口为18789，会自动向系统写入Claude Code专用代理环境变量，无需用户手动修改Claude Code配置文件
2. 添加API服务商：进入「密钥管理」标签页，点击「添加服务商」按钮，可选择预设的Anthropic官方、国内第三方中转服务商模板，也可自定义私有中转的API地址，输入服务商提供的API密钥后点击「保存」即可完成添加
3. 切换默认密钥：点击系统托盘/菜单栏内的CC-Switch图标，在弹出的密钥列表中点击对应密钥即可一键切换全局生效，所有Claude Code的请求会自动走选中的密钥线路
4. 内置预设功能：v2.7.0版本内置3类开箱即用调度预设，新手用户无需手动配置规则，直接在设置页选择对应预设一键启用即可：高并发轮询预设适合多密钥批量请求场景、低延迟优先预设优先匹配响应速度最快的线路、成本优先预设自动排序价格最低的线路优先调用

5. 核心功能使用

1. 多密钥管理：支持单批次批量导入最多1000条API密钥，可按项目、服务商对密钥进行分组标记，支持给不同项目绑定专属密钥组，不同项目的Claude Code调用会自动使用对应分组的密钥，避免混用密钥导致额度统计混乱
2. 用量统计：自动按日/周/月维度统计每个密钥的输入Token、输出Token消耗，同步自动计算剩余可用额度，支持导出用量报表，无需手动登录服务商后台查询消费数据
3. 故障转移：内置自动健康检查机制，若某条密钥出现调用失败、额度耗尽、网络超时的情况，系统会自动跳过当前密钥切换到下一条可用密钥，连续失败3次的密钥会被临时标记为不可用，10分钟后自动重试检测可用性，避免无效重试浪费用户额度
4. 新版专属功能：本次v2.7.0版本新增macOS原生菜单栏悬浮快捷面板，无需打开主界面即可完成密钥切换、用量查看操作；新增Claude Code CLI自动联动能力，打开系统终端调用claude命令时会自动注入调度规则，无需手动配置代理环境变量；新增全平台深色模式自适应，自动跟随系统主题切换界面样式

6. 常见问题排查

1. Windows平台高频问题：
   • 报错「无法绑定18789端口」：打开CC-Switch设置页，将默认监听端口修改为其他未被占用的端口（如18790），重启软件即可解决，该报错通常是其他本地代理工具占用了默认端口
   • Claude Code提示网络连接失败：检查Windows Defender防火墙是否拦截了CC-Switch的出站请求，在防火墙白名单中添加CC-Switch程序即可
2. macOS平台高频问题：
   • 启动后菜单栏无图标：打开「系统设置-通用-登录项」，确认CC-Switch在「允许在后台运行」列表中，若缺失手动添加后重启软件即可恢复
   • 调度规则不生效：打开「系统设置-隐私与安全性-完全磁盘访问权限」，勾选CC-Switch的权限选项，重启软件即可正常读取Claude Code的本地配置文件
3. Linux平台高频问题：
   • AppImage双击无法启动：确认文件所在路径无中文/特殊字符，终端执行启动命令时观察报错信息，若提示缺少依赖可安装libfuse2组件解决
   • 密钥切换无反应：关闭系统其他代理工具的TUN模式，避免路由优先级高于CC-Switch的透明代理规则导致调度失效

7. 更新与卸载说明

7.1 更新操作

• Windows：安装版直接运行新版exe安装包，向导会自动覆盖旧版本所有配置无需重新设置；便携版直接将新版压缩包内容解压替换到旧版本目录即可完成更新
• macOS：Homebrew安装的版本执行brew upgrade cc-switch即可一键更新；DMG版本直接运行新版DMG包，将新的CC-Switch图标拖拽覆盖应用程序文件夹内的旧版本文件即可
• Linux：Deb格式包直接执行sudo dpkg -i 新版deb包路径即可自动覆盖更新；Rpm格式包执行sudo dnf update ./新版rpm包路径即可完成更新；AppImage直接替换旧文件即可

7.2 卸载操作

• Windows：安装版从「控制面板-程序和功能」中找到CC-Switch执行卸载即可；便携版直接删除解压文件夹即可完全移除所有数据
• macOS：Homebrew安装的版本执行brew uninstall cc-switch即可完全卸载；DMG版本直接将应用程序文件夹内的CC-Switch拖拽到废纸篓即可删除
• Linux：Deb版本执行sudo dpkg -r cc-switch卸载；Rpm版本执行sudo dnf remove cc-switch卸载；AppImage版本直接删除文件即可，无冗余配置残留。