1\. 安装并检查

从 CC Switch CLI 官方发布页下载与系统架构匹配的版本。解压后先查看帮助：

cc-switch --version
cc-switch --help
cc-switch provider --help

不同版本的子命令可能变化，以下命令应以当前 --help 输出为准。

2\. 备份 Claude Code 配置

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

3\. 使用交互界面

直接运行：

cc-switch

在交互界面中选择 Providers，新增自定义 Provider，然后填写：

Name: 青云TOP API
Base URL: https://top.qingyuntop.ai/dashboard/
API Key: 青云TOP API 创建的专用令牌
Model: /v1/models 返回的 Anthropic 模型 ID

保存后把 青云TOP API 切换为当前 Provider，再完全退出并重启 Claude Code。

4\. 查看当前状态

先从帮助中确认当前版本支持的命令，再列出 Provider 和当前选中项。不要猜测 Provider ID，也不要把真实 API Key 放在命令行参数中。

5\. 恢复

在 CC Switch CLI 中切回原 Provider。若需要恢复文件，确认 Claude Code 和 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 判定成功。