CC-Switch 全平台配置环境变量操作教程

1. 软件简介

CC-Switch 是专为 Claude Code 生态打造的轻量型API密钥调度代理工具，核心定位是解决原生Anthropic官方接口多密钥管理繁琐、故障无法自动切换、API配额利用率低的痛点，可无缝对接Claude Code桌面端、命令行版以及各类基于Claude API的二次开发应用。
该软件为完全开源的免费工具，托管于公开代码仓库，无内置付费广告、无后台非必要数据上传行为，所有本地配置均加密存储在用户本地设备中，不存在密钥泄露风险。
截至2024年Q3最新正式版本号为v1.3.2，该版本适配全平台x86_64与arm64架构，新增了Claude Code环境变量一键注入功能，大幅降低用户配置门槛。
用户可通过下方提供的官方校验资源渠道下载对应系统的安装包：

---

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

2. 全平台下载

所有资源包均附带SHA256校验值，用户下载完成后可通过校验工具确认文件完整性，三大平台对应安装包信息如下：

1. Windows平台：提供2种格式安装包，分别为安装版文件名CC-Switch_v1.3.2_x64_Setup.exe，便携版文件名CC-Switch_v1.3.2_x64_Portable.zip
2. macOS平台：提供2种格式安装渠道，分别为通用架构DMG镜像文件名CC-Switch_v1.3.2_universal.dmg，支持Intel、Apple Silicon芯片同时兼容，以及Homebrew官方源自动安装支持
3. Linux平台：提供3种主流格式安装包，分别为Debian系deb包文件名cc-switch_1.3.2_amd64.deb、通用可执行AppImage文件名CC-Switch_v1.3.2_x86_64.AppImage、RHEL系rpm包文件名cc-switch-1.3.2-1.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 安装版安装流程

1. 双击下载得到的CC-Switch_v1.3.2_x64_Setup.exe文件，弹出系统UAC权限确认弹窗时点击「是」
2. 跟随安装向导选择安装路径，建议不要选择包含中文或特殊字符的路径，避免后续环境变量写入报错，默认路径为C:\Program Files\CC-Switch
3. 勾选「创建桌面快捷方式」「开机自启代理服务」选项，点击确认完成安装，安装完成后软件将自动启动主界面。

3.1.2 便携版安装流程

1. 解压CC-Switch_v1.3.2_x64_Portable.zip压缩包，将整个解压目录移动到非系统临时文件夹路径，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动软件，所有配置文件、密钥数据都会自动保存在同目录下的config子文件夹中，不需要写入系统注册表，重装系统也不会丢失配置。

3.2 macOS平台安装

3.2.1 Homebrew 命令安装

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

# 添加CC-Switch官方Homebrew源
brew tap cc-switch/tap
# 执行安装命令
brew install cc-switch

安装完成后即可在启动台找到CC-Switch图标，点击即可启动。

3.2.2 DMG手动安装

1. 双击下载得到的CC-Switch_v1.3.2_universal.dmg镜像文件，挂载磁盘镜像
2. 在弹出的镜像窗口中，将左侧CC-Switch图标拖拽到右侧「应用程序」文件夹图标上，等待拷贝完成即安装成功
3. 首次启动时如果系统弹出「无法打开CC-Switch，因为来自身份不明的开发者」提示，点击弹窗中的「取消」，随后打开「系统设置-隐私与安全性」，拉到页面最下方点击「仍要打开」，输入系统账户密码验证后即可正常启动软件。

3.3 Linux平台安装

3.3.1 deb格式安装（适配Ubuntu、Debian、Linux Mint等发行版）

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

# 执行deb包安装
sudo dpkg -i cc-switch_1.3.2_amd64.deb
# 若提示依赖缺失，执行以下命令自动补全依赖
sudo apt install -f

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

3.3.2 AppImage格式安装（适配所有主流Linux发行版）

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

# 为AppImage文件添加可执行权限
chmod +x CC-Switch_v1.3.2_x86_64.AppImage
# 直接启动软件
./CC-Switch_v1.3.2_x86_64.AppImage

如果需要把软件固定到启动器，可手动创建.desktop桌面快捷方式写入应用路径即可。

3.3.3 rpm格式安装（适配CentOS、RHEL、Fedora等发行版）

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

# 执行rpm包安装，自动补全所有依赖
sudo dnf install ./cc-switch-1.3.2-1.x86_64.rpm

安装完成后直接在应用列表启动即可。

4. 首次基础配置

1. 启动界面初始化：首次启动软件将弹出引导配置页，默认本地代理端口为29090，用户可根据自身需求修改未被占用的端口号，确认后软件将自动启动本地后台代理服务，右下角托盘会显示CC-Switch运行图标。
2. 添加API服务商：点击左侧菜单栏「服务商管理」选项，支持添加Anthropic官方服务商、第三方合规中转服务商，依次填入服务商名称、接口转发地址，在批量密钥输入框中每行粘贴1条Claude系列API密钥，确认后即可完成服务商绑定。
3. 切换默认密钥：返回软件主界面，在顶部下拉选择框中选中需要设为当前Claude Code默认调用的密钥，点击「一键生效」按钮，软件会自动覆盖系统全局ANTHROPIC_API_KEY环境变量，同步更新Claude Code本地配置文件，无需用户手动修改配置。
4. 内置预设功能选择：新手用户可直接使用软件内置的「新手默认预设」，自动开启基础负载均衡、故障转移功能，有进阶需求的用户也可手动选择高配额优先、最低延迟优先、单密钥独占模式三类预设。

5. 核心功能使用

1. 多密钥管理：单服务商下最高支持绑定100个API密钥，支持批量导入、一键加密导出备份、自定义标签分类功能，自动识别过期失效密钥并标记为不可用，不会占用有效配额名额。
2. 用量统计：主界面可视化展示每个绑定密钥的累计调用次数、输入输出Token消耗量、剩余可用配额，支持按日/周/月三个维度导出CSV格式用量报表，方便用户核算成本。
3. 故障转移：当API请求返回429限流、401密钥无效、5xx服务端错误三类异常时，软件会自动跳过当前故障密钥，自动切换到下一个可用密钥发起重试，最高支持3层自动重试机制，完全不需要人工干预，保证Claude Code使用过程不中断。
4. v1.3.2新版专属功能：支持Claude Code环境变量一键注入，无需用户手动修改.zshrc/.bash_profile等终端配置文件，自动生成全平台兼容的终端代理规则；同时新增全链路API请求日志面板，用户可实时查看所有请求的返回状态、耗时、Token消耗明细，方便调试接口问题。

6. 常见问题排查

6.1 Windows平台高频问题

1. 启动提示端口29090被占用：打开软件设置页修改默认代理端口为其他未占用端口，也可打开终端执行netstat -ano | findstr "29090"查询占用端口的进程PID，结束对应进程后重启软件即可。
2. 杀毒软件提示病毒误报：将CC-Switch的安装目录加入杀毒软件白名单，软件代码完全开源无恶意行为，误报为Electron类打包程序通用特征导致，可通过官方SHA256校验值确认文件安全。

6.2 macOS平台高频问题

1. 启动提示「CC-Switch已损坏，无法打开」：打开终端执行以下命令，输入系统密码解除系统隔离限制即可：

sudo xattr -r -d com.apple.quarantine /Applications/CC-Switch.app

2. 环境变量配置后Claude Code无法识别：打开终端执行source ~/.zshrc命令，重启终端后重新验证环境变量即可生效。

6.3 Linux平台高频问题

1. AppImage格式双击启动无响应：执行命令安装FUSE依赖即可解决，Ubuntu/Debian系命令为sudo apt install libfuse2，Fedora系命令为sudo dnf install fuse-libs。
2. deb/rpm包安装后应用图标不显示：终端执行update-desktop-database命令刷新系统桌面图标缓存即可。

7. 更新与卸载说明

1. Windows平台：安装版用户可直接打开软件设置页的「检查更新」功能，一键完成在线升级；卸载时可在控制面板-程序和功能列表找到CC-Switch执行卸载操作。便携版用户直接删除解压得到的整个软件目录即可完成全部卸载，所有配置文件同步删除。
2. macOS平台：Homebrew安装用户执行brew upgrade cc-switch命令即可完成升级，执行brew uninstall cc-switch即可卸载。DMG手动安装用户直接将应用程序目录中的CC-Switch图标拖拽到废纸篓，同时删除~/.config/cc-switch路径下的配置文件夹即可完成全部卸载。
3. Linux平台：deb包用户下载新版deb安装包后执行sudo dpkg -i 新版包名即可完成升级，执行sudo apt remove cc-switch卸载。rpm包用户下载新版rpm包后执行sudo rpm -Uvh 新版包名升级，执行sudo dnf remove cc-switch卸载。AppImage格式用户直接下载新版文件替换旧文件即可完成更新，删除旧文件即完成卸载，无需额外操作。