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

一、工具简介

管理多个AI命令行工具（Claude Code、Codex、Gemini CLI）的API密钥和袋里地址，一直是件挺折腾的事。每次手动改环境变量，不仅容易出错，还特别浪费时间。CC-Switch 就是为解决这个痛点而生的——一个开源的图形化配置管理器，让你能一键切换不同厂商的API，密钥和地址都保存在本地，不会上传到任何地方。不仅省心，而且安全。

二、下载（官方渠道）

1. 下载页

国内用户可以从这个快速入口获取：https://pan.quark.cn/s/d6152047213b

2. 分系统安装包选择

Windows

1. 标准安装版
   ：CC-Switch-xxx-Windows.msi（推荐，安装后能添加到开始菜单和系统托盘，使用体验最完整）

2. 便携免安装版
   ：CC-Switch-xxx-Windows-Portable.zip（解压即用，没有安装流程，适合临时用或U盘携带）

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=shturl.cc/i4Hvhgb3d7exo44qh6yx
# 验证安装
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 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：启用当前配置

选中供应商卡片，点击蓝色

按钮，CC-Switch会自动将配置写入本地环境变量。

步骤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包覆盖安装即可