1\. 安装 Claude Desktop

从 Claude 官方下载页 下载客户端。macOS 用户打开 DMG 后，把 Claude.app 拖到“应用程序”。完整系统要求和安装说明见 Anthropic 帮助中心。 !Claude Desktop 官方 macOS 安装镜像 安装后先退出 Claude Desktop。CC Switch 写入 Provider 后需要重新启动，运行中的客户端不会可靠地热加载配置。

2\. 在 CC Switch 选择 Claude Desktop

  1. 打开 CC Switch。
  2. 在顶部应用切换器中选择 Claude Desktop，不要选成 Claude Code。
  3. 如果看不到该分支，打开“设置 > 通用 > 首页显示”，确认 Claude Desktop 没有被隐藏。
  4. 点击右上角加号，选择“自定义配置”。

Claude Desktop 与 Claude Code 使用不同配置。Claude Code 读取 ~/.claude/settings.json，Claude Desktop 则读取自己的 3P Profile。

3\. 填写 青云TOP API Provider

依次填写：

  1. 供应商名称：青云TOP API。
  2. 官网链接：https://top.qingyuntop.ai/dashboard/。
  3. API Key：粘贴 青云TOP API 模型令牌，截图或分享时保持掩码。
  4. 请求地址：https://top.qingyuntop.ai/dashboard/，不要手动追加 /v1/messages。
  5. API 格式：Anthropic Messages（原生）。
  6. 青云TOP API 模型不是 Claude Desktop 能直接识别的角色名时，开启“需要模型映射”。
CC Switch Claude Desktop 分支中的 青云TOP API Provider 配置

4\. 配置模型映射

当前 CC Switch 表单提供 Sonnet、Opus、Fable、Haiku 角色路由。CC Switch 会把客户端选择的角色映射到 青云TOP API 的真实模型 ID。

  1. 点击“获取模型列表”。
  2. 把需要使用的 Sonnet、Opus、Fable、Haiku 角色映射到 青云TOP API 控制台实际存在的模型 ID。
  3. 供应商只有一个模型时，至少填写一个角色，其他空角色会继承首个有效映射。
  4. 只有模型确实支持 1M 上下文时才勾选 1M。
  5. 保存前核对模型 ID，不要照抄截图里的值。
CC Switch 中的 Claude Desktop 模型角色映射

5\. 启用本地路由

  1. 保存 Provider，回到供应商列表并启用 青云TOP API。
  2. 打开“设置 > 路由 > 本地路由”，启用“在主页显示路由开关”。
  3. 回到 Claude Desktop 分支，打开本地路由。
  4. 确认路由显示为运行中，默认监听 127.0.0.1:15721。
  5. 完全退出并重新启动 Claude Desktop。

模型映射模式下，Claude Desktop 连接到：

http://127.0.0.1:15721/claude-desktop

CC Switch 负责角色映射、协议转换和上游鉴权，因此使用过程中必须保持运行。 !CC Switch 的 Claude Desktop 本地路由已启动

6\. 官方模式的登录边界

如果 CC Switch 启用的是“Claude Desktop 官方”，客户端会进入 Anthropic 登录流程。这不是 青云TOP API API Key 的输入页。 !Claude Desktop 官方模式首次启动界面 点击 Get started 后，可以选择 Google 登录或邮箱登录。只使用自己的合法账号，不要把 青云TOP API Key 填进邮箱或密码输入框。 !Claude Desktop 官方账号登录边界 恢复官方模式时，在 CC Switch 中启用“Claude Desktop 官方”，完全退出客户端后重启。官方模式不需要 青云TOP API Key，也不依赖本地路由。

7\. 验证 青云TOP API 接入

只有 3P 界面正常出现后才继续：

  1. 在 Claude Desktop 选择已映射的角色模型。
  2. 发送一条最短消息。
  3. 确认客户端显示正文回复。
  4. 打开 青云TOP API 控制台，确认出现同一时间的请求记录。
  5. 核对请求模型与 CC Switch 的实际映射一致。

客户端回复、青云TOP API 请求记录和模型映射三项必须同时成立。只看到本地端口、Provider 已启用或登录页，都不能算接入成功。

常见问题

启动后进入 Sign In

当前读取的是官方 1P 配置。需要 青云TOP API 时，回到 CC Switch 的 Claude Desktop 分支启用 青云TOP API Provider，然后完全退出并重启客户端。

3P 模式窗口空白

先完全退出 Claude Desktop，再确认 CC Switch 仍在运行、本地路由已开启、当前 Provider 仍是 青云TOP API，然后重新启用 Provider 并重启。仍然空白时，恢复“Claude Desktop 官方”，不要继续尝试发送消息。

CC Switch 已启用，但请求没有出现在 青云TOP API

确认当前分支是 Claude Desktop。模型映射模式还必须保持本地路由运行。若客户端没有正文回复或 青云TOP API 没有请求记录，继续检查本地路由和模型映射。

模型映射后报模型不存在

重新获取 青云TOP API 模型列表，复制实际模型 ID。Claude Desktop 显示的是角色名称，真实上游模型由 CC Switch 映射。

配置文件位置

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json
~/Library/Application Support/Claude-3p/claude_desktop_config.json
~/Library/Application Support/Claude-3p/configLibrary/_meta.json
~/Library/Application Support/Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json

Windows：

%LOCALAPPDATA%\Claude\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\configLibrary\_meta.json
%LOCALAPPDATA%\Claude-3p\configLibrary\00000000-0000-4000-8000-000000157210.json

这些文件由 CC Switch 管理。配置异常时，回到 CC Switch 重新启用当前 Provider，不要手改文件里的 Key 或本地路由令牌。更多字段和模式说明见 CC Switch Claude Desktop 官方手册。

发布前检查

以下检查适用于客户端中选择 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 判定成功。