CC-Switch 完整下载+安装+配置教程

一、工具简介

CC-Switch 是开源图形化工具，用于统一管理 Claude Code / Codex / Gemini CLI 多厂商API，一键切换密钥、中转地址，不用手动改环境变量，本地运行密钥不上传。

二、下载（官方渠道）

---

国内备用（高速）： https://pan.quark.cn/s/d6152047213b

---

2. 分系统安装包选择

Windows

1. 标准安装版：CC-Switch-xxx-Windows.msi（推荐，可添加开始菜单、托盘）
2. 便携免安装版：CC-Switch-xxx-Windows-Portable.zip（解压即用，无安装流程）

macOS

1. Homebrew一键安装（推荐）

brew tap farion1231/ccswitch
brew install --cask cc-switch

2. 手动安装：CC-Switch-xxx-mac.dmg，拖入「应用程序」

Linux（Ubuntu/Debian）

1. deb包：cc-switch_xxx_amd64.deb

sudo dpkg -i cc-switch_*.deb
sudo apt-get install -f

2. 通用免安装：CC-Switch-xxx-x86_64.AppImage，赋予执行权限运行

三、安装步骤

Windows（MSI安装版）

1. 双击下载的 .msi 文件，出现安全提示点「允许」
2. 一路下一步，可自定义安装路径（建议非C盘）
3. 勾选创建桌面快捷方式，完成安装
4. 开始菜单打开 CC-Switch

Windows 便携版

1. 解压zip到纯英文路径（不要中文/空格文件夹）
2. 直接双击 CC-Switch.exe 启动，无需安装

macOS

1. Homebrew安装完成后，启动台打开 CC-Switch
2. 首次打开如提示“无法验证开发者”：系统设置 → 安全性与隐私 → 仍要打开

四、前置依赖（必须先装，否则CC-Switch无法使用）

CC-Switch 只是配置管理器，需要先安装对应AI命令行工具：

1. Claude Code（最常用）

先安装Node.js，再终端执行：

npm install -g @anthropic-ai/claude-code
# 国内慢加镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
# 验证安装
claude --version

2. Codex（OpenAI）

npm install -g @openai/codex

3. Gemini CLI

npm install -g @google/gemini-cli

五、完整配置流程（以Claude Code为例）

步骤1：选择对应AI分组

打开CC-Switch，顶部工具栏点击 Claude 图标（Claude Code分组）

步骤2：添加API供应商（右上角 + 号）

弹出填写框，3个必填项：

1. 供应商名称：自定义（如 Claude官方、中转47code、DeepSeek）
2. API Key：从对应平台复制 sk-xxxx 密钥（无空格）
3. Base URL（请求地址）
   • Anthropic官方：https://api.anthropic.com
   • 第三方中转平台：平台提供的API根地址
4. 可选：备注、默认模型，点击添加/保存

步骤3：测试连通性

供应商列表右侧有试管图标，点击测试：

• 提示「运行正常」= 密钥&地址无误
• 401报错：API Key错误/过期
• 连接超时：网络/中转地址失效

步骤4：启用当前配置

选中供应商卡片，点击蓝色启用按钮，自动写入本地环境变量

步骤5：全局设置优化（新手必做）

左上角齿轮「设置」→ 通用：

• 勾选：跳过Claude Code官方登录验证（避免强制跳转Anthropic账号）
• 开启托盘常驻、开机自启（按需）

六、验证配置是否生效

1. 关闭所有终端，重新打开CMD/PowerShell/终端
2. 输入命令测试：

# Claude测试
claude
# 查看当前加载模型
/model

能正常弹出对话、列出模型即配置成功。

七、多供应商快速切换

1. 主界面列表内多个供应商，点「启用」一键切换
2. 系统托盘右键CC-Switch图标，快速切换供应商，无需打开主窗口

八、常见报错排查

1. 测试连接401 Unauthorized
   • API Key复制带空格、密钥已过期、余额不足
2. 请求超时/连接失败
   • Base URL填错、中转服务失效、本地网络拦截
3. 执行claude提示无配置
   • 未点「启用」供应商；关闭终端重新打开；重启CC-Switch
4. Windows报安全拦截
   • MSI安装包右键「属性」→ 解除锁定后再安装

九、卸载更新

• Windows：控制面板卸载程序，删除安装目录残留
• macOS：brew uninstall --cask cc-switch 或拖App到废纸篓
• 更新：重新下载最新Release包覆盖安装即可