# CC Switch 配置

不想碰命令行配置?[CC Switch](https://github.com/farion1231/cc-switch)(开源,作者 farion1231)是一个供应商切换小工具:点几下就能给 Claude Code / Codex 配好 Clomio,还能在多个密钥、多条[网关线路](#/gateway-lines)之间一键切换。

---

## 一、下载安装

到 [CC Switch Releases](https://github.com/farion1231/cc-switch/releases) 下载对应系统的安装包:

| 系统 | 文件 | 要求 |
|------|------|------|
| Windows | `.msi` | Windows 10+ |
| macOS | `.dmg` | macOS 12 (Monterey)+ |
| Linux | `.AppImage` / `.deb` | 主流发行版 |

- **Windows**:双击 `.msi`,若弹「Windows 已保护你的电脑」→「更多信息」→「仍要运行」。
- **macOS**:打开 `.dmg`,把图标拖进「应用程序」。若提示「无法验证开发者」→ 系统设置 → 隐私与安全性 → 「仍要打开」;或在图标上右键 →「打开」。

> CC Switch 只负责**写配置**,工具本身(Claude Code / Codex)仍需另外装好,见 [Claude Code](#/claude-code) / [Codex](#/codex)。运行这些 CLI 还需要 [Node.js 环境](#/nodejs)(若用 npm 安装方式)。

---

## 二、添加 Clomio 供应商

1. 打开 CC Switch。初次使用时列表为空或只有官方 official,都属正常。
2. 顶部选择要配置的工具(**Claude** 或 **Codex**)。
3. 点右上角 **`+`** → 选「**自定义配置**」。
4. 填写表单。Claude 和 Codex 要分开建供应商:

| 工具/协议 | 供应商名称示例 | 请求地址 | API Key 分组 |
|-----------|----------------|----------|-------------|
| Claude Code / Anthropic-compatible | `clomio-claude` | `https://api.clomio.ai`(**不带 `/v1`**,且**不要**勾「完整 URL」) | Claude/Anthropic 分组;或允许 Messages 调度的 OpenAI 分组 |
| Codex / OpenAI-compatible | `clomio-codex` | `https://api.clomio.ai/v1`(**带 `/v1`**) | OpenAI/Codex 分组 |
| Grok / OpenAI-compatible Responses | `clomio-grok` | `https://api.clomio.ai/v1`(**带 `/v1`**) | Grok 分组 |

5. 点「**+ 添加**」。

> 请求地址也可填另外两条线路:`https://sub.qazwc.com` 或 `https://crs.qazwc.com`,国内通常更稳。可以各建一个供应商,卡顿时一键切换。详见 [网关线路](#/gateway-lines)。
>
> 如果在 CC Switch 里配置 **Codex / OpenAI-compatible** 供应商,Base URL 按 OpenAI 规则写成 `https://api.clomio.ai/v1`(或其它线路 + `/v1`);不要把 Claude/Anthropic 的 `https://api.clomio.ai` 直接照搬过去。

### 关于「完整 URL / Full URL Endpoint Mode」

这是 CC Switch 的高级例外模式,不是 Clomio 常规接入方式。默认情况下,CC Switch 会把你填的请求地址当作“前缀”,再按客户端类型拼出 `/v1/messages`、`/v1/responses` 或 `/v1/chat/completions`。

只有遇到供应商要求非标准路径、必须直接请求某个完整 endpoint 时,才启用「完整 URL」。启用后,请求地址必须写成完整端点,例如 `https://example.com/custom/path/messages`;不要只写 `https://api.clomio.ai` 或 `https://api.clomio.ai/v1`。Clomio 推荐保持关闭:Claude 填 `https://api.clomio.ai`;Codex/OpenAI/Grok 填 `https://api.clomio.ai/v1`。

---

## 三、启用并检测

添加后,供应商出现在列表里:

1. 先点蓝色「**启用**」按钮。
2. 再点「**检测**」入口。
3. 顶部出现**绿色提示**,说明这个检测路径成功;最终仍以实际 `claude` / `codex` 会话和 request_id 为准。

若检测报错,先分清它测试的是哪个客户端协议:

- **Claude Code / Anthropic-compatible**:Base URL 不带 `/v1`,请求最终会落到 `/v1/messages`。
- **Codex / OpenAI-compatible**:Base URL 带 `/v1`,请求最终会落到 `/v1/responses` 或 `/v1/chat/completions`。
- **Grok**:Base URL 也带 `/v1`,可走 Responses、Chat、Images、Videos、Web Search 和 Voice；Messages 是否可用以分组能力为准。
- 看到请求里出现 `/v1/v1/...` 就是双写了 `/v1`;看到 `Videos API is not supported for this platform`,说明用了非 Grok 分组调用 Videos。
- 看到 `Messages API is not supported for this platform`,说明当前分组未开放 Messages 兼容能力；切换 Claude/Anthropic 分组或使用 Responses/Chat。
- 看到 `Embeddings API is not supported for this platform`,说明当前客户端在调 embeddings,但 Key 不是 OpenAI 分组。

反过来也一样:检测通过不代表所有能力都能用。很多 GUI 只测 `/v1/models` 或一条最小聊天请求,不会覆盖 Responses 工具调用、Claude extended thinking、Images、Embeddings、Web Search 或 Grok-only Videos。遇到具体能力失败时,用本文 curl 或对应 API 参考单独验证。

| 检测报错 | 多半原因 | 处理 |
|---|---|---|
| `/v1/v1/messages` | Claude 供应商地址多写 `/v1` | 改成线路根地址,例如 `https://api.clomio.ai` |
| `/v1/chat/completions` + Grok Key | 当前检测的模型或分组未开放 Chat | 改用 Responses 或换已开放 Chat 的 Grok 分组 |
| `This group does not allow /v1/messages dispatch` | OpenAI 分组未开放 Messages 兼容能力 | 换 Claude 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组 |
| `Videos API is not supported for this platform` | 非 Grok 分组调视频 | 换 Grok 视频分组 Key |

也可以把 [CC Switch 用户手册](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/README.md) 链接和报错截图一起发给能识别图片的 AI 排查,或对照 [故障排查](#/troubleshooting)。

---

## 四、从控制台一键导入(更快)

控制台 [api.clomio.ai](https://api.clomio.ai) 的「API 密钥」页,密钥旁通常有「**导入到 CCS**」按钮:点它 → 浏览器弹窗点「允许」→ CC Switch 自动填好地址和密钥,省去手动复制粘贴。

---

## 五、日常使用

- **切换工具**:顶部点 `Claude` 或 `Codex`,确认对应供应商已启用、检测通过,再去终端用 `claude` / `codex`。
- **切换线路 / 密钥**:在列表里点另一个供应商「启用」即可,无需改终端里的任何东西。
- **会话管理**:CC Switch 右上角有会话管理入口,可按工具筛选历史会话并「恢复会话」继续之前的内容。

---

## 六、curl 快速验证

把下面的 `你的密钥` 换成当前供应商里同一把 Key。Claude 供应商用 Claude/Anthropic 分组验证;Codex/OpenAI 供应商用 OpenAI/Grok 分组验证。

**Claude / Anthropic-compatible:**

```bash
curl https://api.clomio.ai/v1/messages \
  -H "Authorization: Bearer 你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}'
```

**Codex / OpenAI-compatible:**

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer 你的密钥" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.5","input":"ping","max_output_tokens":1}'
```

> 配好后回终端运行 `claude` 或 `codex` 验证。更深入的用法见 [Claude Code 进阶](#/claude-advanced) / [Codex 进阶](#/codex-advanced)。