CC-Switch 下载、安装与使用全指南Windows+macOS+Linux【2026.5.28】

CC‑Switch 是跨平台 AI 编程 CLI（Claude Code/Codex/Gemini 等）统一管理工具，核心是多供应商一键切换、API Key 集中管理、代理与用量追踪，开源免费（MIT 协议）。以下从下载、安装、初始化、核心用法到常见问题，给出 2026 最新全指南。

一、系统要求与下载地址

最低要求

Windows：10+（x64）
macOS：12+（Intel/Apple Silicon）
Linux：主流 x64 发行版（Ubuntu 20.04+、Debian 11+ 等）

下载（2026‑05 最新 v3.14.1）

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

内置预设：支持 PackyCode、MiniMax、Anthropic、OpenRouter 等 50+ 供应商

二、分平台安装步骤

Windows（二选一）

MSI 安装（推荐，支持自动更新）
- 下载 CC-Switch-v3.14.1-Windows.msi
- 双击运行，默认安装，开始菜单启动
便携版（无管理员权限）
- 下载 CC-Switch-v3.14.1-Windows-Portable.zip
- 解压，直接运行 cc-switch.exe，不写注册表

macOS（二选一）

Homebrew（推荐，一键安装/更新）

bash 复制代码

brew tap farion1231/ccswitch
brew install --cask cc-switch
# 更新
brew upgrade --cask cc-switch

手动 DMG 安装
- 下载 CC-Switch-v3.14.1-macOS.dmg
- 拖入「应用程序」；首次启动提示"不明开发者"→ 系统设置→隐私与安全性→仍要打开
- 若提示"文件损坏"：xattr -cr "/Applications/CC Switch.app"

Linux（三选一）

Debian/Ubuntu（.deb）

bash 复制代码

sudo dpkg -i CC-Switch-v3.14.1-Linux.deb

AppImage（通用，免安装）

bash 复制代码

chmod +x CC-Switch-v3.14.1-Linux.AppImage
./CC-Switch-v3.14.1-Linux.AppImage

Arch（AUR）

bash 复制代码

paru -S cc-switch-bin

三、首次启动与初始化（必做）

启动后自动检测本地已安装的 AI CLI（Claude Code/Codex 等）
初始化配置（终端或图形界面均可）

bash 复制代码

cc-switch init

输入 Anthropic API Key（Claude 密钥）
默认环境选 claude-code
配置代理（国内用户建议，如 http://127.0.0.1:7890）

验证：cc-switch ping → 返回 success 即正常

四、核心功能：供应商（Provider）管理

1. 添加供应商（以 Claude Code 为例）

主界面右上角点 + → 选预设（如 MiniMax、OpenRouter）或 Custom（自定义）
填写关键信息：
- Name：自定义（如「My‑MiniMax」）
- API Base URL：https://api.minimaxi.com（末尾不要加 /）
- API Key：你的密钥（sk‑开头）
- Model：选模型（如 claude‑sonnet‑4）
点 Add 保存

2. 一键切换供应商

列表中点击目标供应商右侧 Enable → 状态变为 Active（自动写入 CLI 配置）
系统托盘右键可快速切换，无需打开主界面

3. 常用命令（终端）

bash 复制代码

cc-switch status          # 查看当前环境、API 状态
cc-switch use <环境名>    # 切换环境（如 claude-code）
cc-switch key set <新密钥> # 快速更新 API Key
cc-switch list            # 列出所有可用环境
cc-switch login/logout    # 登录/登出 Claude Code

五、高级配置（代理、MCP、用量追踪）

1. 全局代理（解决国内网络问题）

主界面右上角设置 → Proxy → 填写 http://127.0.0.1:7890 → 启用

2. MCP（模型控制平面）管理

右上角 MCP → 添加/切换 MCP 配置，支持多模型路由与故障转移

3. 用量追踪与成本控制

主界面显示各供应商用量、价格、成功率
支持设置成本预警，超阈值自动切换备用供应商

六、常见问题与避坑

启动提示"无法验证开发者"（macOS）
- 系统设置→隐私与安全性→仍要打开；或终端执行 xattr -cr /Applications/CC\ Switch.app
Claude Code 切换后不生效
- 重启终端（热切换仅 Claude Code 支持）；检查 Base URL 末尾无 /；验证 API Key 有效
国内网络连接失败
- 配置全局代理；优先选国内中转供应商（如 MiniMax、PackyCode）
更新失败
- Windows：重新下载 MSI 覆盖安装；macOS：brew upgrade --cask cc-switch

七、卸载方法

Windows：设置→应用→CC‑Switch→卸载；便携版直接删除文件夹
macOS：brew uninstall --cask cc-switch；或删除 /Applications/CC Switch.app
Linux：sudo dpkg -r cc-switch；AppImage 直接删除文件