CC Switch 完整接入总览

你将完成什么 ​

这组教程把 CC Switch 当作配置管理工具，而不是 API 服务本身。你会先安装 CC Switch 和目标客户端，再在梭子蟹创建专用 API Key、选择正确分组、读取当前可用模型，最后让客户端发出一条可核对的请求。

本组教程覆盖九个受管应用：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi。

本文固定参考 官方 CC Switch v3.20.0 Release、官方仓库 和 官方用户手册。界面文字可能随版本改变；看不到某个按钮时不要猜配置文件，先核对当前 Release。

准备与下载 ​

1. 打开上面的官方 Release，确认标签是 v3.20.0。
2. Windows 先在 PowerShell 执行下面的架构检查。输出 x64-based PC 才选择 Windows x64；输出 ARM64-based PC 才选择 ARM64 包。

(Get-CimInstance Win32_ComputerSystem).SystemType

3. Windows 可选 MSI 或 Portable ZIP；macOS/Linux 只选择 Release 当前列出的对应资产。不要使用镜像、推广链接或重新打包文件。
4. 安装后打开 CC Switch，确认主窗口和应用切换器正常显示，再安装目标客户端。

从 v16 升级到 v17 时，首次启动会自动尝试备份旧数据库，再执行结构迁移。备份警告不一定会阻止迁移，所以升级前仍要退出 CC Switch，并手动复制 ~/.cc-switch/cc-switch.db 与 ~/.cc-switch/backups/。如果随后要从 v17 降级回 v16，先完全退出 CC Switch，再恢复升级前备份；不要让旧程序直接打开已经迁移的新数据库。

首次启动 ​

第一次启动目标客户端时先完成它自己的引导或登录，然后退出正在运行的客户端。CC Switch 需要在客户端关闭时写入配置；不要在它正在写入时强制结束进程。

每个客户端的独立教程都说明了官方安装命令、首次启动命令、配置文件位置和重新打开的时机：

API Key、分组与模型 ​

如果账户还没有余额，先按 兑换码与钱包 完成兑换或充值；然后按 创建 API Key 建立专用 Key。CC Switch 只负责保存和切换配置，不负责充值，也不会替你创建 Key。

在梭子蟹创建一把只给目标客户端使用的专用 Key。创建时要同时确认：

• 账户有可用余额或有效订阅；
• 分组允许目标平台和目标端点；
• 需要图片、工具或 Responses 时，分组也开放对应能力；
• Key 建立后不再把完整值放进公开仓库、截图、录屏或共享 .env。

保存 Key 后，先用同一把 Key 读取模型列表。下面的 cURL 命令使用 <API_KEY> 文档占位符；不要把尖括号或真实 Key 写进命令文本。

$secureKey = Read-Host "API key" -AsSecureString
$env:SUOXIE_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password
try {
  # GET /v1/models：先确认同一把 Key 与分组能看到模型
  curl.exe --fail-with-body https://suoxie.codes/v1/models `
    -H "Authorization: Bearer $env:SUOXIE_API_KEY"
} finally {
  Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
}

read -rsp 'API key: ' SUOXIE_API_KEY
echo
export SUOXIE_API_KEY
# GET /v1/models：先确认同一把 Key 与分组能看到模型
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

这种写法避免把 Key 放进命令文本和 PowerShell 历史，但展开后的 Key 仍会出现在 curl.exe 子进程参数中，本机高权限进程可能看到它。只在可信个人电脑的私密会话中运行；不要在共享主机或录屏环境执行。

只从返回的 data[].id 复制 <MODEL_FROM_V1_MODELS>。模型列表证明当前 Key/分组能看见该 ID，但不证明目标客户端会发送它能理解的协议；首个真实请求仍必须验证。

按默认映射导入、保存、启用并发送首个请求 ​

按下面顺序操作即可。CC Switch 的默认映射只提供客户端入口、协议和角色槽位；Key、分组和真实模型 ID 必须填你自己的值。不要下载或转发含真实凭据的配置文件。

先选导入方式 ​

已有默认 Provider： 退出目标客户端，在 CC Switch 顶部切换到对应应用（例如 Claude Code），点击 将 Claude Code 中已有的供应商导入。选择要导入的 Provider，核对应用、Base URL、API 格式和模型映射，再点击确认。这样会复用现有映射，不会重复创建 Provider。

没有 Provider： 点击右上角 +，选择 应用专用 Provider，再选择 自定义配置 / Custom。不要选择 Universal Provider，除非你确实要让多个客户端共用一份配置。

填写五个字段 ​

1. Provider 名称：填 梭子蟹 或 suoxie-openai，只用于识别。
2. Base URL：填 https://suoxie.codes/v1，不要追加 /responses、/chat/completions 或 /messages。
3. 认证：在 API Key 字段粘贴刚创建的 <API_KEY>，认证方式选择 Bearer。
4. API 格式：梭子蟹 OpenAI 接入选择 OpenAI Responses API 或 OpenAI Chat Completions，必须与实际上游一致；不要选 Anthropic Messages 直连来承载 OpenAI URL。
5. 模型：点击 获取模型列表 / Fetch Models，从同一把 Key 返回的列表选择 <MODEL_FROM_V1_MODELS>，不要手写旧型号。

选择规则：Codex 优先选 Responses；只支持 Chat Completions 的客户端选 Chat；Claude Code/Desktop 使用 GPT 时，按对应教程启用本地路由并选择路由实际使用的上游格式。只看到模型出现在列表中，不代表协议已经兼容。

打开默认模型映射 ​

对 Claude Code、Claude Desktop 或其他发送 Anthropic Messages 的客户端：

1. 打开 需要模型映射 开关。
2. 在 模型映射 表中保留 Sonnet、Opus、Haiku 三个角色槽位。
3. 菜单显示名可以写 梭子蟹 Sonnet、梭子蟹 Opus、梭子蟹 Haiku；实际请求模型逐行填同一份 /v1/models 返回的真实 ID。
4. 保存后检查每一行的显示名和实际 ID 都有值。空槽位只会复用已有角色，不会自动授权新模型。

对 Codex：关闭 Claude 角色映射，填写 Codex 的主模型字段，并选择 Responses 或 Chat 路由。每个客户端的独立页给出对应字段，不要把 Claude 的变量复制到 Codex。

需要对照截图时，打开 Claude Desktop 的模型映射步骤；本地路由开关的位置见 Claude Code 的路由步骤。两页截图只用于定位控件，实际状态仍以你当前安装的 v3.20.0 界面和首个请求为准。

保存、启动路由并发送请求 ​

1. 点击 添加 / 保存，回到 Provider 卡片后点击 启用 / 设为当前。
2. 若界面标记 需要本地路由 / Needs Local Routing，进入 设置 → 路由 → 本地路由，先启动路由总开关，再打开目标客户端接管。常用监听地址是 127.0.0.1:15721。
3. 完全退出并重新打开目标客户端；只关闭 CC Switch 不算重启客户端。
4. 发送最小请求 Reply with OK。看到文本回复后，打开 Key 用量，按时间、Key、端点和真实模型核对记录。

先保存并启用 Provider，再重启目标客户端。客户端无法干净重开时先停在这里，修复重启边界后再发请求。

请求链路：客户端 → 127.0.0.1:15721（仅需协议转换时）→ CC Switch Provider → https://suoxie.codes/v1 → 真实模型 → 梭子蟹用量记录。

深链或 SQL 只用于迁移已有配置，不是首次配置入口；导入前先备份，导入后仍必须完成上面的最小请求。

协议边界 ​

上面的共享流程只负责 Key 和模型。文件格式、协议和重启时机请进入对应的独立教程。Claude Code、Claude Desktop、Codex 在 CC Switch 中是三个不同入口，不要把一个客户端的变量复制到另一个。

各客户端关键字段 ​

Claude 使用 GPT 时，Claude 发出 Anthropic Messages（通常是 /v1/messages），而上游可能只接受 OpenAI Responses 或 Chat Completions：在 Provider 中选择实际上游格式，打开本地路由和目标客户端接管，再把 Sonnet、Opus、Haiku 映射到当前 Key 的 /v1/models 返回的真实 ID。直接模式只适用于真实 Anthropic Messages 端点，不能把 OpenAI URL 填进 Anthropic Base URL。

Codex 最适合 OpenAI Responses；Gemini CLI 不是通用 OpenAI 客户端；Grok Build 的 api_backend 必须匹配上游；OpenCode、OpenClaw、Hermes、Pi 的字段以各自独立页为准。Base URL 是否保留 /v1 取决于字段要求，不要粘贴 /v1/chat/completions 或 /v1/messages 到只接受 API 根地址的字段。

核对 Key 用量 ​

保存 Provider 后按这五个检查点核对，不需要重复配置步骤：

某一步没有证据时只改一个字段；关闭 CC Switch 不等于重启客户端，各客户端的重启边界以独立教程为准。

常见错误 ​

回滚与凭据安全 ​

回滚顺序固定为：先启用原来的官方或已验证 Provider；需要本地路由时先关闭对应应用的路由接管；按客户端要求重启；确认旧配置能完成短请求后，再删除本轮新 Provider 或撤销测试 Key。CC Switch 数据库通常位于 ~/.cc-switch/cc-switch.db，自动备份位于 ~/.cc-switch/backups/；升级前要另外复制一份，不要直接覆盖唯一数据库。

完整 API Key 可能保存在 CC Switch 本地 Provider 中。不同应用使用不同、可撤销且有限额的 Key；泄露后立即撤销并新建。不要把 Key 放进 Git、截图、录屏、聊天、脚本、云盘同步目录或共享文件夹。

下一步 ​

选择上方与你使用的客户端对应的独立教程。完成首个请求和用量核对后，再阅读上线前检查；需要理解分组规则时查看选择分组。