CC Switch 通用设置

下载安装

只从 官方发布页 或官方网站下载。macOS 根据处理器选择 aarch64 或 x64，Windows 选择匹配架构的 .msi，Linux 选择发行版对应的 .deb、.rpm 或 AppImage。 安装后打开“设置 → 关于”核对版本，再回到主界面选择需要管理的客户端。 !在 CC Switch 的关于页面核对已安装版本

• Windows

• macOS

• Linux

1. 打开官方 Releases 页面并展开当前版本的 Assets。
2. 普通电脑选择 Windows x64 .msi；ARM 设备选择标有 ARM64 的包。
3. 运行安装程序，完成后从开始菜单启动 CC Switch。

使用 Homebrew 时依次执行：

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

手工下载时，Apple Silicon 选择 aarch64，Intel 选择 x64，安装后从“应用程序”启动。

在 Releases 的 Assets 中复制当前版本的真实文件名。Debian/Ubuntu 下载 .deb 后执行：

sudo dpkg -i ./cc-switch_<version>_amd64.deb

Fedora/RHEL 使用匹配架构的 .rpm；其他发行版可使用 AppImage。不要照抄 <version>。

备份原配置

完全退出 Claude Code，然后备份配置并记录校验和。不存在的文件会自动跳过：

mkdir -p "$HOME/cc-switch-backup"
cp -p ~/.claude/settings.json "$HOME/cc-switch-backup/claude-settings.json" 2>/dev/null || true
shasum -a 256 ~/.claude/settings.json 2>/dev/null

备份可能包含密钥或登录态，不要上传到云盘、公开仓库或工单。

添加 青云TOP API Provider

下面以 Claude Code 分支演示通用操作。截图只展示需要点击或填写的区域，令牌已经遮挡；Claude Desktop 的模型映射请参考对应教程。

第 1 步：选择客户端分支

打开 CC Switch，在顶部图标栏选择要配置的客户端。不同分支会生成不同格式的配置文件，请确认当前选中的是正确客户端。 !在 CC Switch 顶部选择目标客户端分支

第 2 步：打开自定义 Provider

点击右上角橙色 +，然后在“添加新供应商”页面选择“自定义配置”。 !点击加号后选择自定义配置

第 3 步：填写 青云TOP API 信息

依次填写：

1. “供应商名称”填写 青云TOP API。
2. “官网链接”填写 https://top.qingyuntop.ai。
3. “API Key”粘贴从 青云TOP API 创建的专用模型令牌。
4. “请求地址”按目标协议填写：Anthropic 使用 https://top.qingyuntop.ai，OpenAI 兼容协议使用 https://top.qingyuntop.ai/v1。
5. 亚太地区分别改为 https://top.qingyuntop.ai 或 https://top.qingyuntop.ai/v1。
6. 模型必须使用 青云TOP API /v1/models 对当前令牌返回的准确 ID。

第 4 步：保存并启用

不需要继承本机插件、Hook 或环境变量时，关闭“应用通用配置”，然后点击“保存”。返回 Provider 列表后点击 青云TOP API 卡片；卡片出现蓝色边框并成为当前项，表示切换完成。 !青云TOP API Provider 已保存并切换为当前项

常见问题

• 顶部没有目标应用：打开“设置 → 通用 → 应用可见性”确认没有隐藏。
• Provider 已添加但客户端仍走旧地址：确认卡片显示“使用中”，完全退出并重启客户端。
• 模型不存在：用同一令牌重新查询 /v1/models，不要使用截图中的示例 ID。
• 同时运行桌面版和 CLI：两者可能覆盖数据库或实时配置；一次只使用一种管理方式。

验证与恢复

重启目标客户端，发送只包含 ping 的最小请求。成功回复后再启用工具调用、长上下文或自动执行等能力。 测试结束后切回原 Provider，关闭本地代理或路由接管，完全退出 CC Switch，再比较配置文件校验和。若不同，先确认没有进程仍在写配置，然后从备份恢复。