CC-Switch 全平台环境变量配置与使用教程

1. 软件简介

CC-Switch 是一款专为 Claude Code 终端开发场景设计的开源 API 代理调度工具，核心定位是解决原生 Claude Code 仅支持单密钥调用、多服务商API切换繁琐、故障无自动容错的痛点。
它完全兼容 Claude Code 官方客户端的环境变量读取规则，无需修改 Claude Code 原生代码即可实现多密钥轮询、第三方兼容API接入、请求负载均衡、用量统计的全链路调度能力，是当前生态内使用率最高的 Claude Code 增强配套工具。
项目完全基于MIT开源协议开放全部源码，无任何后台埋点、无强制付费功能，所有核心能力均可免费使用。
截至2024年第四季度，CC-Switch 最新稳定版本号为 v1.3.2，已适配全平台 x86_64 与 ARM64 架构。

---

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

2. 全平台下载

所有安装包均已内置自动环境变量注入逻辑，无需用户手动编写复杂配置，不同平台对应安装包明细如下：

1. Windows 平台：包含2类安装包，分别为安装版文件 CC-Switch-v1.3.2-windows-x64-Setup.exe、便携版文件 CC-Switch-v1.3.2-windows-x64-Portable.zip
2. macOS 平台：包含2类分发介质，分别为 Homebrew 官方源托管的配方包、通用二进制DMG镜像文件 CC-Switch-v1.3.2-darwin-universal.dmg，同时支持Intel x64与Apple Silicon架构
3. Linux 平台：包含3类安装包，分别为Deb系发行版适用的 cc-switch_1.3.2_amd64.deb / cc-switch_1.3.2_arm64.deb、通用便携执行文件 CC-Switch-v1.3.2-linux-x86_64.AppImage、RPM系发行版适用的 cc-switch-1.3.2.x86_64.rpm / cc-switch-1.3.2.aarch64.rpm

3. 分平台安装教程

3.1 Windows 平台安装

3.1.1 安装版安装流程

1. 双击下载得到的 CC-Switch-v1.3.2-windows-x64-Setup.exe 执行文件
2. 系统弹出用户账户控制提示时选择「是」，进入安装向导
3. 阅读用户协议后勾选「我接受许可协议中的条款」，点击下一步
4. 自定义安装路径，注意路径不得包含中文、特殊字符与空格，推荐默认安装路径 C:\Program Files\CC-Switch
5. 勾选「自动添加系统环境变量」选项，点击下一步后等待安装完成
6. 安装完成后勾选「立即启动CC-Switch」，点击完成即可进入主界面

3.1.2 便携版安装流程

1. 右键解压 CC-Switch-v1.3.2-windows-x64-Portable.zip 压缩包到非系统盘的纯英文路径下，例如 D:\Tools\CC-Switch
2. 直接双击目录内的 CC-Switch.exe 即可启动主程序
3. 首次启动后右键点击系统托盘中的CC-Switch图标，选择「自动注入系统环境变量」，确认弹窗后系统将自动完成环境变量配置，无需重启即可生效

3.2 macOS 平台安装

3.2.1 Homebrew 命令行安装

打开「终端」应用，依次执行以下代码块内的命令，即可完成全自动化安装：

# 添加CC-Switch官方Tap源
brew tap cc-switch/tap
# 执行安装命令
brew install cc-switch
# 启动应用并自动配置环境变量
open /usr/local/bin/cc-switch

3.2.2 DMG 手动安装

1. 双击打开 CC-Switch-v1.3.2-darwin-universal.dmg 镜像文件
2. 在弹出的镜像窗口中，将CC-Switch图标拖拽到「应用程序」文件夹图标上，等待拷贝完成
3. 首次启动时请右键点击启动台内的CC-Switch图标，选择「打开」，在系统弹出的「无法验证开发者」提示框中再次点击「打开」，绕过系统公证限制
4. 应用启动后将自动读取当前用户环境变量，完成适配配置

3.3 Linux 平台安装

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

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

# 安装deb包
sudo dpkg -i cc-switch_1.3.2_amd64.deb
# 修复依赖异常（若提示依赖缺失时执行）
sudo apt install -f
# 启动应用
cc-switch

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

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

# 为AppImage文件添加执行权限
chmod +x CC-Switch-v1.3.2-linux-x86_64.AppImage
# 直接运行启动
./CC-Switch-v1.3.2-linux-x86_64.AppImage
# （可选）添加桌面快捷方式，将程序移动到/opt目录下
sudo mv CC-Switch-v1.3.2-linux-x86_64.AppImage /opt/cc-switch.appimage

3.3.3 rpm格式安装（CentOS/Fedora/RHEL等发行版）

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

# 安装rpm包
sudo dnf install ./cc-switch-1.3.2.x86_64.rpm
# 启动应用
cc-switch

4. 首次基础配置

1. 启动界面引导：首次启动后应用将弹出配置引导页，自动检测当前系统已安装的Claude Code、Cursor、Windsurf等AI开发客户端，自动校验端口占用情况，默认调度端口为8787
2. 添加API服务商：点击左侧菜单栏「服务商管理」按钮，可选择添加原生Anthropic官方API、国内云厂商Claude兼容API、开源推理框架兼容API三类服务商，填写服务商提供的API密钥与端点地址即可完成绑定
3. 切换默认密钥：在「密钥管理」列表中，点击对应密钥右侧的星型图标，即可将该密钥设置为系统全局默认调用密钥，所有已配置的AI客户端将自动切换到该密钥发起请求
4. 内置预设功能：应用内置Claude 3 Opus/Sonnet/Haiku全系列模型的路由规则预设，无需手动填写模型端点参数，开启后将自动匹配Claude Code原生的模型调用请求，无需修改Claude Code任何配置即可直接运行

5. 核心功能使用

1. 多密钥管理：单实例最多支持绑定100个API密钥，支持按服务商标签、模型权限、剩余配额分组，自动校验密钥有效性，一键批量导入导出密钥列表，支持自动去重避免重复绑定
2. 用量统计：实时统计每个密钥的Token消耗、请求次数、失败率数据，支持按日/周/月维度生成用量报表，可直接导出为CSV格式文件，自动触发低配额预警，剩余额度低于设定阈值时将发送系统通知提醒
3. 故障转移：开启自动轮询模式后，任意密钥调用失败将自动切换到下一个可用密钥，连续3次请求失败的密钥将被自动标记为不可用，1小时后自动恢复重试，完全避免单密钥故障导致的开发进程中断
4. v1.3.2新版专属功能：新增环境变量全局一键注入能力，支持Windows/macOS/Linux全平台的终端、IDE、GUI AI客户端自动识别调度规则，无需用户手动修改任何配置文件；新增自定义限流规则，可针对单密钥设置每秒请求数上限，避免触发服务商频率限制。

6. 常见问题排查

1. Windows平台：环境变量配置后Claude Code仍提示未设置密钥：关闭所有已打开的终端、VSCode等程序后重新启动，新打开的终端将自动读取新注入的环境变量；若仍不生效可手动在系统变量中新增ANTHROPIC_BASE_URL变量，值设置为http://127.0.0.1:8787即可
2. macOS平台：启动提示文件已损坏无法打开：打开终端执行以下命令移除系统隔离属性即可：sudo xattr -d com.apple.quarantine /Applications/CC-Switch.app
3. Linux平台：AppImage启动闪退：先执行sudo apt install fuse2（Deb系）或sudo dnf install fuse2（RPM系）安装依赖，启动时增加参数运行：./CC-Switch-xxx.AppImage --no-sandbox即可正常进入主界面
4. 通用问题：调度端口8787被占用：进入应用「系统设置」页面，修改调度端口为其他未被占用的端口，点击保存后应用将自动更新环境变量配置，无需修改其他参数。

7. 更新与卸载说明

1. Windows平台：安装版直接运行新版安装包即可自动覆盖旧版本，更新过程中自动保留原有密钥配置；卸载时进入控制面板的「程序和功能」列表找到CC-Switch点击卸载，程序将自动清除所有注入的环境变量与本地配置文件。便携版直接替换解压目录内的主程序文件即可完成更新，卸载时先右键点击托盘图标选择「移除系统环境变量」，再直接删除整个解压目录即可。
2. macOS平台：Homebrew安装的版本执行brew upgrade cc-switch即可完成更新，卸载时执行brew uninstall cc-switch命令自动清除所有配置；DMG安装的版本直接将新版DMG内的CC-Switch拖拽替换「应用程序」目录下的旧版本即可完成更新，卸载时将应用拖入废纸篓，终端执行defaults delete com.cc.switch清除残留配置。
3. Linux平台：deb版本更新执行sudo apt upgrade cc-switch，卸载执行sudo apt remove cc-switch && sudo apt autoremove；AppImage版本直接替换新的执行文件即可完成更新，删除文件即可完成卸载；rpm版本更新执行sudo dnf update cc-switch，卸载执行sudo dnf remove cc-switch自动清理所有配置与环境变量。