CC-Switch 全平台一键配置正式教程

CC-Switch 全平台一键配置正式教程1. 软件简介CC-Switch 是专为Anthropic Claude Code 官方客户端打造的轻量型API多服务商调度与密钥管理增强工具核心作用是解决原生Claude Code仅支持单密钥绑定、无法灵活切换不同合规API服务商、故障转移缺失的痛点。产品定位为Claude Code生态的官方兼容层中间件完全不修改客户端核心二进制文件所有操作均符合Anthropic客户端使用规范支持全平台全局代理、密钥池轮询、自定义请求路由等扩展能力。软件完全开源所有代码托管至公开代码仓库无数据埋点、无密钥上传行为所有API凭证仅加密存储在用户本地设备。当前最新稳定版本为v1.3.2适配 Claude Code 1.8.0及以上全系列正式版客户端。|下载| https://pan.quark.cn/s/d6152047213b2. 全平台下载所有安装包均已通过SHA256完整性校验无篡改无捆绑各系统对应安装包命名与格式如下Windows平台分为安装版后缀.exe、便携版后缀.zip对应文件名分别为CC-Switch_v1.3.2_windows_x64_setup.exe、CC-Switch_v1.3.2_windows_x64_portable.zipmacOS平台分为通用架构DMG镜像、Homebrew线上安装包对应文件名分别为CC-Switch_v1.3.2_macos_universal.dmg、Homebrew源同步v1.3.2正式版Linux平台分为Deb系deb包、RHEL系rpm包、全发行版兼容AppImage包对应文件名分别为cc-switch_1.3.2_amd64.deb、cc-switch-1.3.2.x86_64.rpm、CC-Switch_v1.3.2_linux_x64.AppImage3. 分平台安装教程3.1 Windows平台安装3.1.1 安装版流程双击下载的CC-Switch_v1.3.2_windows_x64_setup.exe若弹出Windows Defender未知应用风险提示点击「更多信息」-「仍要运行」即可跳过拦截选择自定义安装路径默认路径为C:\Program Files\CC-Switch禁止安装到包含中文、特殊字符的路径下勾选安装向导中的「添加到系统PATH环境变量」「开机自启动CC-Switch调度服务」选项点击下一步直至安装完成桌面自动生成软件快捷方式双击即可启动使用3.1.2 便携版流程解压下载的CC-Switch_v1.3.2_windows_x64_portable.zip到非系统临时目录例如D:\GreenTools\CC-Switch直接双击目录内的CC-Switch.exe即可运行全程不会写入系统注册表关闭软件后无多余系统残留如需创建快捷方式右键点击可执行文件选择「发送到」-「桌面快捷方式」即可3.2 macOS平台安装3.2.1 Homebrew命令安装打开系统终端依次执行以下命令完成安装# 同步最新软件源brew update# 执行CC-Switch安装brewinstallcc-switch/cc-switch/cc-switch# 直接终端启动软件cc-switch首次启动如果提示应用权限异常执行以下命令移除系统隔离属性xattr-dcom.apple.quarantine /Applications/CC-Switch.app3.2.2 DMG手动安装双击下载的CC-Switch_v1.3.2_macos_universal.dmg等待磁盘镜像挂载完成将窗口左侧的CC-Switch图标拖拽到右侧「应用程序」文件夹图标上等待拷贝完成即完成安装首次启动请右键点击启动台内的CC-Switch图标选择「打开」在弹出的安全提示窗口再次点击「打开」跳过苹果公证拦截即可正常进入软件直接双击打开会触发「无法验证开发者」的报错。3.3 Linux平台安装3.3.1 Deb格式适配Debian/Ubuntu/Mint等Deb系发行版打开终端进入安装包所在目录执行以下命令# 执行安装操作sudodpkg-icc-switch_1.3.2_amd64.deb# 若提示依赖缺失自动补全所有缺失依赖sudoaptinstall-f# 启动CC-Switchcc-switch3.3.2 AppImage格式适配所有主流Linux发行版无需系统级安装直接赋予执行权限即可运行# 赋予可执行权限chmodx CC-Switch_v1.3.2_linux_x64.AppImage# 直接启动软件./CC-Switch_v1.3.2_linux_x64.AppImage3.3.3 Rpm格式适配CentOS/RHEL/Fedora等RPM系发行版打开终端进入安装包所在目录执行以下命令# 执行安装操作自动解决依赖sudodnfinstall./cc-switch-1.3.2.x86_64.rpm# 启动CC-Switchcc-switch4. 首次基础配置启动引导界面首次启动软件会自动弹出初始化向导自动扫描本地已安装的Claude Code客户端路径扫描失败时可手动指定对应路径Windows端默认路径为C:\Users\当前用户名\AppData\Local\Programs\Claude\Claude.exemacOS端默认路径为/Applications/Claude.appLinux端默认路径为/opt/Claude/claude。添加API服务商进入左侧菜单栏「服务商管理」页面点击「新增服务商」按钮支持三种服务类型自动适配官方Anthropic原生服务、国内合规第三方代理服务商、OpenAI兼容层自定义服务填入服务商备注名、API端点地址、专属密钥后点击保存所有密钥自动通过AES-256算法加密存储在本地不会上传任何外部服务器。切换默认密钥返回软件首页在顶部下拉选择框直接选中需要绑定的服务商密钥确认后无需重启Claude Code1秒内即可完成密钥切换。内置预设功能软件内置27款主流合规API服务商的端点预设新增服务商时直接在预设列表选中对应服务商无需手动输入API地址仅填入密钥即可完成全部配置大幅降低新手配置门槛。5. 核心功能使用多密钥批量管理支持最多100组密钥批量导入可给不同密钥设置权重分配、过期时间标签、业务场景分组按需调度不同密钥对应不同类型的Claude Code任务避免单密钥超限中断。多维度用量统计自动统计每一组密钥的输入Token消耗量、输出Token消耗量、累计调用次数、剩余可用额度支持按日/周/月生成用量报表一键导出为CSV格式文件留存。智能故障转移开启该功能后当前使用的密钥触发限流、额度耗尽、服务商宕机场景时软件会自动无缝切换到同优先级分组内的其他可用密钥全程不会中断Claude Code的正在进行的对话进程业务零感知恢复。v1.3.2版专属功能新增Claude Code全局请求速率自定义限速、自定义上下文长度截断阈值、全量密钥调用日志导出、局域网内多设备共享密钥池4项新特性支持跨设备同步配置适配团队批量调度场景。6. 常见问题排查Windows端报错「无法注入环境变量」右键点击CC-Switch图标选择「以管理员身份运行」临时关闭360安全卫士、腾讯电脑管家等安全软件的进程拦截规则将CC-Switch加入安全软件白名单即可解决。macOS端报错「应用已损坏无法打开」打开终端执行命令xattr -cr /Applications/CC-Switch.app移除系统隔离属性重启软件即可正常启动。Linux端AppImage启动闪退系统缺失FUSE2依赖包Ubuntu/Debian系执行sudo apt install libfuse2CentOS/RHEL系执行sudo dnf install fuse-libs安装依赖后重启软件即可恢复正常。切换密钥后Claude Code仍报401未授权错误确认无其他代理/ VPN占用CC-Switch默认18789调度端口进入软件设置页修改调度端口为其他空闲端口重启软件后重新校验密钥有效性即可。用量统计数据为空进入软件设置页勾选「启用请求代理记录」选项重启CC-Switch后即可正常捕获Claude Code的所有调用数据统计数据会实时同步更新。7. 更新与卸载说明7.1 更新流程CC-Switch支持静默在线升级点击设置页的「检查更新」按钮即可自动下载最新安装包覆盖升级所有已配置的密钥、服务商信息、自定义规则都会完整保留不会出现配置丢失问题。如需离线升级直接安装最新版安装包即可覆盖旧版本。7.2 卸载流程Windows平台安装版可直接从「控制面板-程序和功能」列表中选中CC-Switch点击卸载便携版直接删除解压后的软件目录即可额外手动删除C:\Users\当前用户名\.cc-switch路径下的配置残留目录。macOS平台Homebrew安装的版本执行brew uninstall cc-switch即可完成卸载DMG安装的版本直接将应用程序目录中的CC-Switch拖拽到废纸篓手动删除~/Library/Application Support/cc-switch配置残留目录。Linux平台deb包执行sudo apt remove cc-switch完成卸载rpm包执行sudo dnf remove cc-switch完成卸载AppImage版本直接删除对应的AppImage文件手动删除~/.config/cc-switch配置残留目录即可。