CC Switch：Claude Desktop

准备 ​

预计 15 分钟。本路径适用于 Windows 和 macOS 的 Claude Desktop 第三方 profile；CC Switch v3.20.0 不写入 Linux Desktop 3P profile，WSL 是 Claude Code 环境而不是 Desktop 安装。它不适用于把 OpenAI URL 当作 Anthropic 直连。

你将安装 CC Switch v3.20.0 和 Claude Desktop，创建专用 Key 与分组，读取 /v1/models，映射 Sonnet/Opus/Haiku，启用正确模式，发送一次请求，核对用量并保留回滚数据。位置：备份现有 Claude-3p profile 和 CC Switch 状态。预期结果：可恢复已知可用 profile。不要用猜测的 JSON 覆盖现有 profile；找不到备份时先停止切换。

下载 ​

仅从 CC Switch 官方 v3.20.0 Release 下载适合系统和架构的安装包，再从 Anthropic 官方 Claude Desktop 下载页 下载 Desktop。

预期结果：两者均从官方来源安装。不要下载二次打包安装包，也不要在安装时把 Key 写入配置。只有 Linux Desktop 时，使用官方 Desktop 模式或 Claude Code，不要尝试不支持的 CC Switch profile 写入。安装失败时先解决系统或网络错误。

首次启动 ​

位置：先打开 CC Switch，进入 关于 并确认显示 v3.20.0；再启动 Claude Desktop，从 帮助 -> 关于 或平台等价入口读取已安装客户端版本（version）。值来源：两个已安装应用。若使用官方服务，完成官方登录，创建新会话并确认主窗口能接受消息。

预期结果：CC Switch 关于页面显示 v3.20.0，Desktop 显示来自官方安装包的客户端版本（version），且官方会话可用。不要假设 Claude Code 的 ~/.claude/settings.json 控制 Desktop；它使用独立的 3P profile。任一版本看不到、CC Switch 不是 v3.20.0、Desktop version 与预期安装不符或启动失败时，都不要继续；先修复安装再添加第三方 Provider。

API Key 与分组 ​

位置：在梭子蟹控制台为本次 Desktop 安装创建专用、可撤销、有限额的 <API_KEY>，并授权目标分组。真实 Key 只来自该私密控制台会话。

不要手工把 Key 写进 Desktop profile，也不要在 Git、截图、Shell 历史或共享目录中公开。CC Switch 的本地 Provider/profile 可能保存完整 Key，因此要限制文件权限、禁止云同步或分享，若本地 profile 泄露则立即撤销 Key。分组未授权时修复权限，不要猜模型或切换到无关 Provider。

GET /v1/models ​

位置：映射角色前用同一把 Key 查询模型。URL 含 /v1；其 Bearer token 用于梭子蟹 OpenAI 兼容模型列表 API，不是 Anthropic Messages 直连认证。预期结果：将 data[].id 原样复制为 <MODEL_FROM_V1_MODELS>。

Windows PowerShell：

$secureKey = Read-Host 'API key' -AsSecureString
$keyPtr = [IntPtr]::Zero
try {
  $keyPtr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
  $env:SUOXIE_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($keyPtr)
  curl.exe --fail-with-body --show-error https://suoxie.codes/v1/models -H "Authorization: Bearer $env:SUOXIE_API_KEY"
}
finally {
  Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
  if ($keyPtr -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($keyPtr) }
}

macOS/Linux：

read -r -s -p 'API key: ' SUOXIE_API_KEY; printf '\n'
curl --fail-with-body --show-error https://suoxie.codes/v1/models -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

不要复制另一把 Key 的模型或从列表结果推断协议支持。401/403 时修复 Key、分组、授权或余额；网络错误先修复连通性。

Provider 与协议边界 ​

位置：在 CC Switch 选择 Claude Desktop，再选择直连或路由 Provider。两条路径彼此独立：

预期结果：直连仅保留原生 Messages；路由将 Desktop Messages 转换为所选 OpenAI 协议并转换回来。/v1/models 可见不等于协议转换。上游格式不明时不要按直连保存。

模型映射 ​

位置：在 Claude Desktop Provider 的角色映射行分别填写菜单显示名和实际 ID。Sonnet 是日常默认，Opus 用于复杂工作，Haiku 是快速轻量角色。值来自同一份 /v1/models。

需要区分三种角色时，应为路由 Provider 填写三个槽位。CC Switch v3.20.0 的空槽位会自动沿用第一个已填模型，并优先采用 Sonnet；例如 Sonnet 已填而 Opus、Haiku 留空时，两个空槽位都会沿用 Sonnet 模型。空槽位不会发现或授权新模型。直连模式要求原生上游提供 Claude 兼容角色 ID。不要写死某个过时 GPT 型号，也不要把菜单显示名当作上游 ID。

启用与本地路由 ​

位置：在 Claude Desktop 入口点击 保存/应用，再点击 启用。直连仅用于原生 Anthropic Messages。梭子蟹 OpenAI Provider 则进入 设置 -> 路由 -> 本地路由，打开总开关及 Claude Desktop 接管。本地地址是 http://127.0.0.1:15721/claude-desktop；CC Switch 将角色映射并转换协议，再用 Bearer 认证请求 https://suoxie.codes/v1。

预期结果：目标 Provider 已启用且 CC Switch 持续运行。接管活动时不要停止本地路由。激活失败时关闭接管、选择已验证 Provider，并检查 Responses 或 Chat Completions 选择。

首个请求 ​

位置：保存并启用后完全退出 Claude Desktop（包括后台进程），再重新打开，让它读取新的 3P profile。新建会话发送 Reply with OK。

预期结果：新会话收到文本回复。不要使用旧会话，也不要在活动 profile 不确定时重复请求。失败时记录响应码并按下方错误检查。

用量核对 ​

位置：成功回复后打开 Key 用量。值来源：上文的请求时间和专用 Key。预期结果：将 Key、分组、端点、真实上游模型 ID、输入/输出 token、费用和 Provider 逐项核对。

不要根据角色菜单或卡片变化推断成功。没有记录时先刷新、清除筛选并扩大日期范围，再只尝试一次。端点或模型不同表示映射 Provider 未生效。

错误 ​

回滚与安全 ​

位置：选择 Claude Desktop Official 或此前验证过的 Provider 并点击 启用，停止本地路由前关闭 Desktop 接管，然后完全退出并重开 Desktop，再重复最小请求。确认旧路径正常，且其用量记录与目标 Key、端点一致。确认后，最后撤销本轮专用测试 Key。若该专用 Key 是仍需长期使用的正式 Key，只撤销本轮临时测试 Key，不影响正在使用的正式 Key。

恢复前保留 CC Switch 的 ~/.cc-switch/cc-switch.db 和 ~/.cc-switch/backups/，同时保留 Claude-3p profile 备份并核对其内容。不要删除唯一可用 profile、数据库或备份，也不要用猜测 JSON 覆盖。回滚后仍显示错误 Provider 时，先检查启用项和路由状态，再考虑凭据变更。