CC-Switch v2.4.0 最新版下载安装配置全教程

1. 软件简介

CC-Switch 是一款专为 Claude Code 生态打造的开源API网关代理与多密钥调度管理工具，核心定位是解决原生Claude Code客户端不支持多服务商切换、单密钥额度耗尽后无法自动续用、第三方Claude兼容服务接入繁琐的痛点问题。
软件全程开源无后门，所有调度逻辑本地运行，不会上传任何用户对话数据或API密钥信息，完全符合本地工具的隐私安全要求。
本次教程覆盖的最新正式版版本号为 v2.4.0，该版本新增了Claude 3.5/3.7 Sonnet专属流量调度、故障自动重试队列、Windows系统托盘常驻优化等12项新特性，同时修复了旧版本中macOS系统权限弹窗异常、Linux后台自启失效等已知问题。
用户可通过以下官方直链获取全平台通用安装包资源：

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

2. 全平台下载

所有安装包均已通过官方校验，无捆绑、无篡改，各平台对应安装包信息如下：

  1. Windows 平台
    • 安装版文件名：CC-Switch-v2.4.0-Windows-Installer.exe（标准安装包，支持自动关联环境变量）
    • 便携版文件名：CC-Switch-v2.4.0-Windows-Portable.zip（免安装绿色包，可存放在U盘随时运行）
  2. macOS 平台
    • DMG安装包文件名：CC-Switch-v2.4.0-macOS-Universal.dmg（通用架构，同时支持Intel芯片与Apple Silicon芯片）
    • Homebrew源包名：cc-switch（已上架官方Homebrew第三方源，命令行直接安装无需手动下载）
  3. Linux 平台
    • Debian/Ubuntu系安装包文件名：cc-switch_2.4.0_amd64.deb
    • CentOS/RHEL/Fedora系安装包文件名：cc-switch-2.4.0.x86_64.rpm
    • 全发行版通用文件名：CC-Switch-v2.4.0-Linux-x86_64.AppImage（无需依赖，双击即可运行）

3. 分平台安装教程

3.1 Windows 平台安装

3.1.1 安装版安装流程
  1. 双击下载完成的CC-Switch-v2.4.0-Windows-Installer.exe，在弹出的用户账户控制弹窗中点击「是」授予管理员权限
  2. 自定义选择安装路径，默认路径为C:\Program Files\CC-Switch，请勿设置包含中文、特殊字符的路径，避免程序运行异常
  3. 勾选「创建桌面快捷方式」「添加系统PATH环境变量」两个可选选项，新手用户建议全部勾选
  4. 点击「安装」等待进度条完成，勾选「立即启动CC-Switch」后点击「完成」结束安装
3.1.2 便携版安装流程
  1. 将下载的CC-Switch-v2.4.0-Windows-Portable.zip解压到非系统临时目录，例如D:\Tools\CC-Switch
  2. 右键点击主程序CC-Switch.exe，选择「发送到」-「桌面快捷方式」方便后续启动
  3. 第一次运行时右键点击主程序，选择「以管理员身份运行」，否则会出现本地代理端口绑定失败的问题

3.2 macOS 平台安装

3.2.1 Homebrew 命令安装

确认本地已安装Homebrew环境后，直接在终端依次执行以下命令：

# 添加CC-Switch官方第三方源
brew tap cc-switch/tap
# 执行安装
brew install cc-switch
# 可选：设置开机后台自动运行
brew services start cc-switch

安装完成后直接在终端输入cc-switch即可启动图形化界面。

3.2.2 DMG 手动安装
  1. 双击下载完成的CC-Switch-v2.4.0-macOS-Universal.dmg挂载镜像
  2. 在弹出的镜像窗口中，将CC-Switch图标拖动到右侧的Applications文件夹内，等待拷贝完成即安装结束
  3. 首次启动如果弹出「无法打开CC-Switch，因为来自身份不明的开发者」的提示，打开「系统设置」-「隐私与安全性」，向下滑动页面找到「已阻止使用CC-Switch」的提示，点击「允许」即可正常启动。

3.3 Linux 平台安装

3.3.1 deb格式安装（Debian/Ubuntu系列）

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

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

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

3.3.2 rpm格式安装（CentOS/RHEL/Fedora系列）

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

# CentOS/RHEL 用户执行
sudo rpm -ivh cc-switch-2.4.0.x86_64.rpm
# Fedora 用户推荐使用该命令自动补全依赖
sudo dnf install ./cc-switch-2.4.0.x86_64.rpm
3.3.3 AppImage格式安装（全发行版通用）

不需要提前安装任何依赖，执行以下命令赋予运行权限后即可启动：

# 赋予程序执行权限
chmod +x CC-Switch-v2.4.0-Linux-x86_64.AppImage
# 直接启动程序
./CC-Switch-v2.4.0-Linux-x86_64.AppImage

4. 首次基础配置

  1. 启动界面初始化：首次启动软件会自动弹出新手配置向导，默认本地代理端口为7892，系统检测到端口未被占用的情况下直接点击下一步即可，若提示端口冲突可手动修改为其他未使用的端口。
  2. 添加API服务商：向导第二步支持三种服务商类型添加，分别为原生Anthropic官方、第三方Claude兼容服务商、OpenAI格式转Claude自定义服务商，用户只需要依次填写服务商备注名称、API调用地址、专属API密钥，点击确认即可完成添加。
  3. 切换默认密钥：在密钥管理列表页，点击目标密钥前方的星形图标即可将其设置为最高优先级默认调用密钥，也可以直接拖拽密钥条目调整调度优先级顺序。
  4. 内置预设功能开启：向导最后一步新手可直接全选三个预设选项：「自动适配Claude Code客户端代理」「自动生成系统环境变量配置脚本」「开机自动后台运行」，无需手动修改Claude Code本地配置文件即可直接使用。

5. 核心功能使用

  1. 多密钥管理：支持最多200条API密钥批量导入，可单独为每条密钥设置每日Token消耗上限、有效期，到达阈值后系统会自动暂停该密钥的调度，避免产生额外的超额费用。
  2. 用量统计：实时展示每条密钥的调用次数、输入/输出Token消耗、剩余额度，支持按日/周/月三个维度导出用量报表，自动生成消费明细，方便用户核对服务商账单。
  3. 故障转移：开启该功能后，如果某条密钥触发限流、额度耗尽、服务商宕机，系统会在1秒内自动将当前未完成的请求转发到下一个可用密钥，全程不会中断Claude Code的对话进程，用户完全感知不到调度切换。
  4. v2.4.0新版专属功能：新增Claude 3.7 Sonnet 200k长上下文专属调度规则，系统会自动识别长文本会话，优先分配支持长上下文配额的密钥；新增本地请求日志加密导出功能，所有日志仅存储在用户本地；新增代理模式一键切换，支持全局代理和仅Claude Code定向代理两种模式，不会影响其他本地软件的网络配置。

6. 常见问题排查

6.1 平台专属问题

  1. Windows 平台
    • 报错：启动提示端口7892被占用：打开软件设置界面，将代理端口修改为7893或其他未被占用的端口，重启软件即可恢复正常
    • 报错：Claude Code无法连接到服务：确认软件是用管理员权限启动，否则系统无法注册本地SSL代理证书，会导致请求校验失败
  2. macOS 平台
    • 报错：启动提示缺少必要权限：打开「系统设置」-「隐私与安全性」-「完全磁盘访问权限」，勾选CC-Switch的权限选项后重启软件即可
    • 报错：Homebrew安装后终端输入cc-switch提示命令不存在：在终端执行brew link --overwrite cc-switch重新链接程序即可
  3. Linux 平台
    • 报错：AppImage双击无响应：确认程序没有放置在包含中文、空格的路径下，重新执行赋权命令即可解决
    • 报错：deb安装后启动无反应：在终端执行cc-switch查看报错信息，如果提示缺少libssl依赖，执行sudo apt install libssl3补全依赖即可启动

6.2 通用问题

添加密钥后Claude Code仍提示认证失败：进入CC-Switch设置页，点击「一键配置Claude Code环境变量」按钮，重启Claude Code客户端即可使新的代理配置生效。

7. 更新与卸载说明

7.1 版本更新

全平台所有版本升级时都会自动保留用户所有配置、密钥数据、历史用量记录，不会丢失用户自定义设置：

  • Windows安装版直接运行新版exe安装包，会自动覆盖旧版本完成升级；便携版直接将新版文件解压到旧版本目录下覆盖替换即可
  • macOS Homebrew用户执行brew upgrade cc-switch即可完成升级，DMG用户直接将新版镜像中的CC-Switch拖动到Applications文件夹覆盖旧文件即可
  • Linux deb/rpm包直接执行新版安装命令即可自动完成升级，AppImage用户直接替换旧的AppImage文件即可

7.2 完全卸载

  • Windows安装版可直接在「控制面板-程序和功能」中找到CC-Switch点击卸载；便携版先退出系统托盘内的程序，直接删除软件所在文件夹即可
  • macOS Homebrew用户执行brew uninstall cc-switch完成卸载；DMG安装版本直接将Applications目录下的CC-Switch拖动到废纸篓即可
  • Linux deb版本执行sudo apt remove cc-switch完成卸载，rpm版本执行sudo rpm -e cc-switch卸载，AppImage直接删除对应文件即可
    所有平台卸载后，用户配置数据默认会保存在用户主目录下的.cc-switch隐藏文件夹中，如果需要完全清除所有数据，手动删除该文件夹即可。
# python
Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

cover

【AI智能体】Codex 制作RAG知识库应用实战操作详解

avatar 智能体开发者社区
cover

22道AI Agent 工程师必会的面试题，别啥都不会就出去找工作

avatar 智能体开发者社区
cover

基于AI agent的智能图书馆

avatar 智能体开发者社区