新手教程：CC Switch

如果你不熟悉命令行配置，推荐用开源桌面工具 CC Switch：它给 Claude Code、Codex、Gemini CLI 等常用 AI 编码工具提供可视化的「供应商」管理，填一次 Base URL 和 Key，之后在官方与 SoleAPI 之间一键切换。全程不需要手动编辑任何配置文件。

准备：拿到你的 API Key

先注册 SoleAPI 并在控制台「API Key」页创建一把密钥（形如 sk-sole-…），详见快速开始。

第 1 步：安装 CC Switch

• macOS：终端执行下面一条命令，或到 Releases 下载 .dmg。

brew install --cask cc-switch

• Windows：到 Releases 下载 MSI 安装包（也有免安装的便携版 ZIP）。
• Linux：Releases 提供 .deb / .rpm / AppImage。
• 官方下载页：ccswitch.io/download（各平台最新版）

第 2 步：一键导入 SoleAPI 供应商

控制台「API Key」页提供导入 CC Switch按钮——新建密钥的成功弹窗里有，每把已有密钥的行内也有。点击后浏览器会拉起本机的 CC Switch 并弹出配置预览，确认即可完成添加：Base URL、密钥全部自动填好，一个字都不用抄。

导入的供应商会自动开启 CC Switch 的用量显示：列表里直接看到余额与累计消费，数据来自 GET https://api.soleapi.com/v1/usage（用你的 API Key 鉴权，返回 remaining / used / total / unit，单位为 Credits）。手动添加时，也可以在供应商的「用量」设置里填这个地址启用。

手动添加（备选）

不方便用一键导入时，也可以手动填写：

1. 打开 CC Switch，顶部选择你要配置的工具标签（比如 Claude Code）。
2. 点击**「添加供应商」**，选择自定义配置，按下表填写：

1. 名称随意（比如 SoleAPI），保存。

第 3 步：启用并验证

1. 在列表里选中刚添加的 SoleAPI，点击**「启用」**——CC Switch 会自动把配置写进对应工具的配置文件。
2. 重启终端（或重启该 CLI 工具）让配置生效；Claude Code 支持热切换，一般不用重启。
3. 打开 Claude Code 随便发一句话，能正常回复就说明接入成功。也可以用下面的命令快速验证 Key 是否可用：

curl https://api.soleapi.com/v1/models \
  -H "Authorization: Bearer sk-sole-你的Key"

之后想切回官方或其他供应商，在 CC Switch 列表（或系统托盘菜单）里点一下对应条目即可，随时可以再切回来。

常见问题

• 报 401：Key 复制不完整或已停用，去控制台核对；错误细节见错误码。
• 报错里出现双斜杠 //v1：Base URL 末尾多了 /，删掉重新启用。
• 切换后不生效：重启终端；确认 CC Switch 里该供应商处于「已启用」状态。
• 点击「导入 CC Switch」没反应：CC Switch 未安装、版本低于 v3.16，或安装后从未启动过（协议未注册）；装好后重新点击即可。