CC-Switch API Key 配置全平台官方教程

1. 软件简介

CC-Switch 是专为 Claude Code 系列IDE/终端编码工具打造的轻量化API密钥调度管理配套组件。
其核心作用是替代手动修改系统环境变量、Claude Code 配置文件的繁琐操作，实现多API服务商密钥的一键切换，同时内置流量负载均衡、故障自动重试能力，大幅降低多账号、多中转节点场景下的运维成本。
该工具采用MIT开源协议发布，所有核心代码完全公开，无后台明文密钥上传逻辑，用户存储的密钥仅存放在本地磁盘，安全性经过上万名Claude生态用户长期验证。
当前最新正式稳定版本为 v2.3.1，全平台原生开发，无额外依赖，可兼容Claude Code v1.8及以上全系列版本。

---

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

2. 全平台下载

所有版本安装包均托管在上述官方统一分发镜像内，各操作系统对应的安装包信息如下：

1. Windows平台：提供两种格式，分别是标准安装版CC-Switch-v2.3.1-Windows-x64-Setup.exe、便携免安装版CC-Switch-v2.3.1-Windows-x64-Portable.zip
2. macOS平台：提供两种分发渠道，分别对应Homebrew源自动拉取安装、通用双架构DMG镜像CC-Switch-v2.3.1-macOS-universal.dmg，同时兼容Intel x86芯片与Apple Silicon M系列芯片
3. Linux平台：提供三种主流格式，分别是Deb系deb包cc-switch_2.3.1_amd64.deb、通用免安装AppImage包CC-Switch-v2.3.1-Linux-x86_64.AppImage、RPM系rpm包cc-switch-2.3.1.x86_64.rpm

3. 分平台安装教程

3.1 Windows平台安装

3.1.1 标准安装版步骤

1. 下载得到exe格式安装包后，双击启动安装向导
2. 系统弹出「用户账户控制」权限请求弹窗时，点击「允许」继续
3. 选择软件安装路径，默认路径为C:\Program Files\CC-Switch，新手用户建议保留默认配置无需修改
4. 向导功能勾选区必须同时选中「添加桌面快捷方式」「自动注册到系统PATH环境变量」两个选项，点击下一步
5. 等待文件解压写入完成，勾选「立即运行CC-Switch」选项后点击完成，安装流程结束。

3.1.2 便携免安装版步骤

1. 下载得到zip压缩包后，将其解压至任意非系统临时目录，例如D:\Tools\CC-Switch
2. 直接双击目录内的CC-Switch.exe即可启动软件，全程不会写入系统注册表和系统Program Files目录
3. 右键点击CC-Switch.exe，依次选择「发送到-桌面快捷方式」，即可创建常用启动入口。

3.2 macOS平台安装

3.2.1 Homebrew命令安装

启动macOS原生终端应用，依次执行以下命令完成安装：

brew tap cc-switch/tap
brew install cc-switch

安装完成后可直接在启动台找到CC-Switch图标点击启动，也可在终端直接输入cc-switch命令唤起图形界面。

3.2.2 DMG手动安装步骤

1. 下载得到dmg镜像文件后双击挂载
2. 在弹出的安装窗口中，直接将左侧CC-Switch图标拖拽到右侧Applications文件夹图标内，等待文件写入完成
3. 首次启动时不要直接双击图标，右键点击启动台内的CC-Switch图标，选择「打开」，在弹出的「未验证开发者」确认弹窗中再次点击「打开」，即可绕过系统安全限制正常启动。

3.3 Linux平台安装

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

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

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

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

3.3.2 AppImage通用格式（全发行版兼容）

打开终端进入安装包所在目录，依次执行以下命令赋予执行权限后启动：

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

该格式无需写入系统目录，也可直接右键点击文件在属性面板勾选「允许作为可执行文件」，之后双击即可直接运行。

3.3.3 rpm格式（Fedora/CentOS/RHEL系列发行版）

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

sudo rpm -ivh cc-switch-2.3.1.x86_64.rpm

执行完成后即可从系统应用菜单中找到CC-Switch启动入口。

4. 首次基础配置

4.1 启动界面引导

第一次启动软件后会自动弹出新手引导向导，软件会自动扫描本地已安装的Claude Code可执行文件路径，若扫描失败可手动指定Claude可执行文件的存放路径。主界面左侧为导航栏，包含「密钥管理」「服务商设置」「用量统计」「系统设置」四个核心模块，右侧为对应功能的操作主区。

4.2 添加API服务商

点击左侧导航栏「服务商设置」，点击右上角「新增服务商」按钮，可直接选择软件内置的预设服务商（含Anthropic官方、主流Claude中转节点），也可选择自定义服务商，手动填写服务商名称、API端点地址、请求头适配规则，确认后保存即可。

4.3 切换默认密钥

进入「密钥管理」页面，点击「添加新密钥」，选择密钥所属的对应服务商，粘贴用户持有的API Key，填写自定义备注（例如「个人付费账号」「公司开发节点」），保存后点击该密钥右侧的「设为默认」按钮，软件会自动将该密钥同步写入系统全局环境变量CLAUDE_API_KEY，后续Claude Code启动时会自动读取该环境变量值完成鉴权。

4.4 内置预设功能启用

新手用户可直接在系统设置页开启内置的「Claude 3系列模型自动适配」「中转服务商超时阈值预设」两个开关，无需手动调整复杂请求参数即可开箱使用。

5. 核心功能使用

5.1 多密钥管理

支持无上限添加不同服务商的API Key，支持按项目、付费等级给密钥打标签分组，可通过全局快捷键Ctrl+Shift+S（macOS平台为Command+Shift+S）唤起快速切换面板，无需打开软件主界面即可一键切换当前生效的API密钥。

5.2 用量统计

软件会自动监听Claude Code的所有请求，精准统计每个密钥的输入Token消耗、输出Token消耗、总调用次数、剩余可用额度，支持导出月度用量报表，可自定义额度告警阈值，当密钥剩余额度低于阈值时自动弹窗提醒用户替换密钥。

5.3 故障转移

开启故障转移功能后，当当前正在使用的密钥触发限流、服务商节点宕机、返回401/429等错误码时，软件会自动切换到同一分组下的其他可用密钥，静默重试当前请求，全程不会中断Claude Code的编码流程，对用户完全无感知。

5.4 v2.3.1版本专属功能

新版新增三大特性：一是支持密钥池负载均衡，同一服务商下的多个密钥可自定义权重分配请求流量，最大化利用多账号配额；二是支持Claude Code会话隔离，不同密钥对应的会话上下文完全独立，不会出现不同账号串号的问题；三是新增代理全局适配，自动读取系统代理配置，也支持用户手动指定自定义全局代理地址。

6. 常见问题排查

1. 通用高频问题：切换密钥后Claude Code未生效，属于终端环境变量未刷新导致，完全退出当前Claude Code进程、重启终端后重新打开即可读取最新的密钥配置。
2. Windows平台专属问题：安装时提示「文件被占用」，打开任务管理器结束所有claude.exe相关进程后重试即可；便携版启动提示缺少动态链接库，下载安装微软官方VC++运行库合集即可解决。
3. macOS平台专属问题：启动提示「无法打开，因为来自身份不明的开发者」，不要直接双击启动，右键点击图标选择「打开」，在弹出的确认窗口再次点击「打开」即可，也可进入系统设置-隐私与安全性，在页面底部找到被拦截的CC-Switch条目，点击「仍要打开」完成授权；Homebrew安装提示签名校验失败，执行brew update更新本地源后重新运行安装命令即可。
4. Linux平台专属问题：AppImage双击启动无响应，执行sudo apt install fuse3（Deb系）或sudo dnf install fuse3（RPM系）安装FUSE依赖即可解决；deb包安装提示依赖冲突，先执行sudo apt --fix-broken install修复损坏的系统依赖后重新安装即可。
5. 通用鉴权报错：API请求返回401错误，检查粘贴的API Key是否带有多余的首尾空格，同时确认对应服务商的API端点地址配置是否和服务商官方给出的地址完全一致。

7. 更新与卸载说明

7.1 更新操作

所有平台均支持内置一键更新，点击左侧「系统设置」-「检查更新」即可自动拉取最新版本安装包，直接覆盖安装不会丢失本地已保存的所有密钥、配置数据，也可直接从官方分发镜像下载最新版安装包直接覆盖安装即可。

7.2 卸载操作

1. Windows系统：安装版可打开系统设置-应用-已安装应用列表，找到CC-Switch点击卸载，按照向导提示完成操作即可；便携版直接删除解压的软件文件夹即可完全卸载，无任何系统残留。
2. macOS系统：Homebrew安装的版本打开终端执行brew uninstall cc-switch即可完全卸载；DMG手动安装的版本直接将Applications目录下的CC-Switch图标拖拽到废纸篓清空即可。
3. Linux系统：deb包安装的版本执行sudo apt remove cc-switch完成卸载；rpm包安装的版本执行sudo dnf remove cc-switch完成卸载；AppImage版本直接删除对应的AppImage文件即可。
   所有平台卸载软件时都不会删除用户本地存储的密钥配置目录，该目录默认路径为当前用户家目录下的.cc-switch隐藏文件夹，如果需要完全清除所有用户数据，手动删除该目录即可。