CC Switch：Claude Code

准备 ​

预计 15 分钟。本路径适用于已支持 Claude Code 的 Windows、macOS、Linux 与 WSL；它不适用于仅靠改 URL 就想把 OpenAI 端点变成 Anthropic 的情况，也不适用于无法在路由 Provider 使用期间保持 CC Switch 运行的环境。

你将安装 CC Switch v3.20.0 和 Claude Code，为此客户端创建一把可撤销 Key，选择已授权分组，复制实时模型 ID，配置正确协议，发送一次请求并保留回滚点。位置：改动前备份现有 ~/.claude/settings.json。预期结果：可恢复此前可用配置。不要用猜测值覆盖；若它已丢失，先恢复再继续。

下载 ​

仅从 CC Switch 官方 v3.20.0 Release 下载适合系统和架构的安装包并打开，再从官方 Claude Code setup 页面安装 Claude Code。

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

macOS、Linux 或 WSL：

curl -fsSL https://claude.ai/install.sh | bash

预期结果：两者均从官方来源安装。不要使用转存安装包，也不要把 API Key 写入安装命令。安装失败时先解决系统、网络或官方安装器错误。

首次启动 ​

位置：先打开 CC Switch，进入 关于，确认已安装应用显示 v3.20.0；然后在非敏感项目目录打开终端并运行下列命令。值来源：CC Switch 关于页面和已安装的 Claude Code 可执行文件。

claude --version

运行一次 claude，若要使用官方服务则按 Anthropic 提示完成官方登录或引导。预期结果：CC Switch 关于页面显示 v3.20.0，Claude Code 打印版本并进入提示符。不要把官方登录当成梭子蟹 Key 配置。若关于页面不是 v3.20.0、看不到客户端版本或找不到命令，则不要继续；先修复安装并重开终端。

API Key 与分组 ​

位置：在梭子蟹控制台创建仅供 Claude Code 使用、可撤销且有限额的 <API_KEY>，并为它授权可访问目标端点和模型的分组。真实 Key 只来自该私密控制台会话。

不要把 Key 写入 Git、截图、Shell 历史、工单或聊天。分组名不是模型 ID。目标分组不可用时，先修复权限，不要试猜其他模型名。

GET /v1/models ​

位置：创建 Provider 前在私密终端执行。该 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 Code，新增或编辑 Provider。下列两条路径必须二选一：

预期结果：原生 Messages 保持原协议，OpenAI Provider 明确标记为转换。能看到 /v1/models 只证明模型可见，不证明 Anthropic 兼容。上游协议不明时先确认，再保存。

模型映射 ​

位置：若为路由 Provider，在 Claude Code 入口的高级模型字段配置。每个值均来自同一份 /v1/models。ANTHROPIC_MODEL 是主请求路径的显式主模型覆盖；角色映射仍各自生效：Sonnet 是日常默认角色，Opus 是复杂任务角色，Haiku 是快速轻量角色，小型快速覆盖项用于 Claude Code 请求该快速角色时。设置 ANTHROPIC_MODEL 会覆盖主会话的 Sonnet 默认选择，但不会替代其他角色映射。

不要把某个过时 GPT 型号写死，也不要把角色标签当作上游 ID。所需 ID 不在列表中时返回 /v1/models 选择已授权 ID，不要将占位符保存为真实配置。

启用与本地路由 ​

位置：点击 保存/应用，再在 Claude Code 入口点击 启用/设为当前。真实 Anthropic Messages 直连到此为止；梭子蟹 OpenAI Provider 则进入 设置 -> 路由 -> 本地路由，打开总开关及 Claude Code 接管。面向客户端的 ANTHROPIC_BASE_URL 会变成 http://127.0.0.1:15721；这是本地 Anthropic 兼容网关，CC Switch 仍使用 Bearer 认证请求上游 https://suoxie.codes/v1。

完成控件操作后的预期结果：CC Switch 保持运行、路由已启动，并已启用 Claude Code 接管。下图只用于定位本地路由设置：截图中的状态是 Stopped，且画面没有显示 Claude Code 接管控件，不能据此证明路由已启用。发送请求前要另行启动路由并启用 Claude Code 接管。接管仍启用时不要停止本地路由。失败时关闭接管、恢复已验证直连 Provider，并检查选的是 Responses 还是 Chat Completions。

首个请求 ​

位置：首次启用接管、关闭接管或恢复直连 Provider 后，关闭当前终端会话并新开一个。发送一个最小请求：

claude -p "Reply with OK"

预期结果：收到文本回复，而不只是 Provider 卡片变色。不要连续重复发送来排障。失败时根据响应码和下文错误检查修复，再只重试一次。

用量核对 ​

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

不要根据菜单标签或本地路由状态推断成功。没有记录时先刷新、清除筛选并扩大时间范围，再发送下一次请求。Key、分组、端点或模型不一致说明当前 Provider 不是预期配置。

错误 ​

回滚与安全 ​

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

恢复任何客户端配置前，保留 CC Switch 的 ~/.cc-switch/cc-switch.db 与备份目录 ~/.cc-switch/backups/ 的副本；只恢复已知可用的备份，不要恢复猜测的 JSON。不要删除唯一可用的 profile、数据库或备份。回滚后端点不符时，先检查当前 Provider 和路由状态，不要先改凭据。