下载安装

只从 官方发布页 或官方网站下载。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/dashboard/。
  3. “API Key”粘贴从 青云TOP API 创建的专用模型令牌。
  4. “请求地址”按目标协议填写：Anthropic 使用 https://top.qingyuntop.ai/dashboard/，OpenAI 兼容协议使用 https://top.qingyuntop.ai/v1。
  5. 亚太地区分别改为 https://top.qingyuntop.ai/dashboard/ 或 https://top.qingyuntop.ai/v1。
  6. 模型必须使用 青云TOP API /v1/models 对当前令牌返回的准确 ID。
填写 青云TOP API 名称、官网、打码 API Key 和请求地址

第 4 步：保存并启用

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

客户端协议青云TOP API 地址路径规则
Anthropic Messageshttps://top.qingyuntop.ai/dashboard/不追加 /v1/messages
亚太 Anthropichttps://top.qingyuntop.ai/dashboard/不追加路径

常见问题

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

验证与恢复

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

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。