CC-Switch 全平台安装配置官方教程

1. 软件简介

CC-Switch是专为Anthropic Claude Code命令行工具研发的第三方增强调度工具，核心作用是解决原生Claude Code仅支持单API密钥绑定、多服务商接入点无法灵活切换的功能痛点。
其产品定位为Claude Code的配套运维增强工具，不对Claude Code的核心运行逻辑做任何篡改，仅在API密钥调度、接入点管理、用量统计三个维度提供扩展能力。
软件完全采用MIT开源协议发行，全量源码托管至公开代码仓库，所有版本安装包均支持GPG签名校验，无任何埋点、暗门与未授权数据上传行为，安全性可完全审计。
当前正式发布的最新稳定版本号为v1.4.1，原生适配Windows、macOS、Linux三大主流桌面操作系统，全平台统一功能无差异化。

---

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

2. 全平台下载

除上述共享资源入口外，用户也可通过官方开源发布页获取对应平台的安装包，所有安装包均经过SHA256哈希校验，未被二次篡改，各平台对应安装包明细如下：

1. Windows平台：包含两个发行版本，分别为安装版文件名为CC-Switch_v1.4.1_Windows_Setup.exe，便携免安装版文件名为CC-Switch_v1.4.1_Windows_Portable.zip
2. macOS平台：通用架构DMG安装包文件名为CC-Switch_v1.4.1_macOS_Universal.dmg，同时兼容Intel x86_64与Apple Silicon M系列芯片，官方已上架Homebrew Cask源支持命令行直接安装
3. Linux平台：提供三种主流发行版适配格式，deb安装包文件名为cc-switch_1.4.1_amd64.deb，rpm安装包文件名为cc-switch-1.4.1.x86_64.rpm，全发行版通用AppImage包文件名为CC-Switch_v1.4.1_Linux_amd64.AppImage

3. 分平台安装教程

3.1 Windows 平台安装

3.1.1 安装版安装步骤

1. 双击下载的CC-Switch_v1.4.1_Windows_Setup.exe，弹出系统UAC权限提示时点击「是」
2. 自定义选择安装路径，默认路径为C:\Program Files\CC-Switch，禁止选择包含中文、特殊字符的路径避免运行异常
3. 勾选「添加桌面快捷方式」「添加到系统PATH环境变量」两个可选配置项，方便后续全局调用
4. 点击「立即安装」等待进度条走完，勾选「立即启动CC-Switch」后点击完成即可结束安装

3.1.2 便携版安装步骤

1. 将下载的CC-Switch_v1.4.1_Windows_Portable.zip完全解压到非系统临时目录，如D:\Tools\CC-Switch
2. 右键点击主程序CC-Switch.exe，选择「发送到-桌面快捷方式」生成桌面启动入口
3. 可选操作：手动将当前解压目录添加到系统PATH环境变量，实现终端全局调用CC-Switch命令

3.2 macOS 平台安装

3.2.1 Homebrew 命令安装

打开终端执行以下命令，先添加官方软件源再完成安装：

brew tap cc-switch-offical/tap
brew install --cask cc-switch

安装完成后可直接在Launchpad启动台中找到CC-Switch图标点击启动。

3.2.2 DMG 手动安装步骤

1. 双击CC-Switch_v1.4.1_macOS_Universal.dmg挂载磁盘镜像
2. 在弹出的镜像窗口中，将左侧CC-Switch图标拖拽到右侧Applications文件夹图标上，完成软件拷贝
3. 首次启动如果弹出「无法打开来自未验证开发者的应用」提示，打开「系统设置-隐私与安全性」，拉到页面最底部点击「仍要打开」，输入开机密码确认即可正常启动。

3.3 Linux 平台安装

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

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

sudo dpkg -i cc-switch_1.4.1_amd64.deb
# 如果提示依赖缺失，执行以下命令自动补全依赖
sudo apt install -f

安装完成后可在应用列表中找到CC-Switch启动入口。

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

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

# CentOS/RHEL 执行
sudo rpm -ivh cc-switch-1.4.1.x86_64.rpm
# Fedora 用户推荐使用dnf自动处理依赖
sudo dnf install ./cc-switch-1.4.1.x86_64.rpm

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

AppImage为便携免安装格式，仅需要赋予可执行权限即可运行，终端执行以下命令：

chmod +x CC-Switch_v1.4.1_Linux_amd64.AppImage
# 直接双击运行 或 终端执行以下命令启动
./CC-Switch_v1.4.1_Linux_amd64.AppImage

4. 首次基础配置

1. 启动引导校验：首次打开软件会自动启动配置向导，自动扫描本地环境中已安装的Claude Code命令行工具路径，如果未检测到已安装程序，会提示用户执行npm install -g @anthropic-ai/claude-code完成官方Claude Code部署。
2. 添加API服务商：进入侧边栏「服务商管理」页面，点击「新增服务商」，支持三种接入类型：官方Anthropic原生接入、国内中转服务商接入、自定义兼容协议接入，依次填写服务商名称、API端点、API密钥、支持的模型列表后点击保存即可。
3. 切换默认密钥：进入侧边栏「密钥管理」页面，选中需要设置为Claude Code全局默认的密钥，右键点击选择「设为全局默认」，软件会自动修改Claude Code的用户配置文件~/.claude.json中的apiKey字段，不需要用户手动编辑配置。
4. 内置预设启用：软件内置20+主流Claude中转服务商的预设配置，不需要手动填写端点和模型参数，仅需输入服务商提供的API密钥即可一键启用，大幅降低新手配置门槛。

5. 核心功能使用

1. 多密钥批量管理：支持批量导入上百个API密钥，可按服务商、剩余额度、权限等级对密钥进行分组标记，支持单独禁用/启用指定密钥，设置单密钥每日请求上限，避免单密钥超限被封禁。
2. 可视化用量统计：软件自动同步所有Claude Code的请求日志，按日/周/月三个维度统计每个密钥的输入输出token消耗、实际费用支出，生成可视化统计报表，支持导出CSV格式文件用于对账。
3. 无感故障转移：开启故障转移模式后，当当前使用的密钥触发限流、过期、额度耗尽时，软件会自动无缝切换到下一个可用密钥，完全不会中断当前Claude Code的对话进程，用户全程无感知。
4. v1.4.1新版专属功能：新增Claude 3 Opus、Sonnet 3.5 200k上下文专属调度规则，支持按任务类型自动分配高优先级密钥，新增全局代理接管模式，不需要额外配置系统代理即可让Claude Code走指定代理节点，避免网络连通问题。

6. 常见问题排查

1. Windows平台高频报错：启动提示「缺少VCRUNTIME140.dll」，解决方案：下载微软官方VC++运行库合集安装包完成安装后重启电脑即可解决。便携版提示无权限修改Claude配置，右键点击程序选择「以管理员身份运行」即可获得配置修改权限。
2. macOS平台高频报错：启动后直接闪退，解决方案：打开终端执行xattr -d com.apple.quarantine /Applications/CC-Switch.app清除系统隔离属性即可正常启动。Homebrew安装提示签名校验失败，执行brew uninstall --cask cc-switch卸载旧缓存包，重新执行安装命令拉取最新包即可修复。
3. Linux平台高频报错：AppImage启动提示权限不足，确认已经执行chmod +x命令赋予可执行权限，不要直接从压缩包内双击运行，解压到本地非临时目录再启动。deb安装后启动无响应，终端执行sudo apt install libfuse2安装缺失的系统依赖即可修复。
4. 全平台通用报错：修改默认密钥后Claude Code仍使用旧密钥，点击CC-Switch首页的「同步配置到Claude」按钮强制覆盖配置，之后重启Claude Code进程即可生效。

7. 更新与卸载说明

7.1 更新方式

软件自带自动更新检测功能，每次启动时会自动校验官方最新版本，有新版本发布时会弹窗提示，点击「一键更新」即可自动下载安装包完成升级，所有用户配置的密钥、服务商数据都会自动保留，不会出现丢失情况。用户也可以直接下载最新版安装包覆盖安装，跳过自动更新流程。

7.2 卸载方式

1. Windows安装版：打开「控制面板-程序和功能」，找到CC-Switch点击卸载，按照向导提示操作即可，可选勾选「删除所有用户配置数据」清空所有本地缓存。
2. Windows便携版：直接删除解压的CC-Switch文件夹即可，无任何写入系统注册表的冗余文件。
3. macOS Homebrew安装：终端执行brew uninstall --cask cc-switch即可完成卸载。
4. macOS DMG安装：直接从Applications文件夹将CC-Switch拖拽到废纸篓即可完成卸载。
5. Linux deb包卸载执行sudo apt remove cc-switch，rpm包卸载执行sudo dnf remove cc-switch，AppImage版本直接删除对应AppImage文件即可。
   所有平台的配置数据统一存放在用户目录下的.config/cc-switch文件夹，手动删除该目录即可完全清空所有使用痕迹，实现彻底卸载。