# Cherry Studio 配置

[Cherry Studio](https://www.cherry-ai.com/) 是一个跨平台的 AI 桌面客户端,带图形界面、支持多模型切换。把它接到 Clomio,就能用聊天界面调用 Claude、Codex(GPT)、Grok 等模型。

---

## 一、打开模型服务商设置

左下角齿轮「**设置**」→「**模型服务商**」。这里有一排预置服务商,也可以拉到最下面点「**添加自定义服务商**」新建一个。

---

## 二、Base URL 的关键区别:加不加 `/v1`

这是最容易踩的坑。Cherry Studio 会根据服务商**类型**自动拼接请求路径,所以**类型选对、地址后缀写对**最重要:

| 接入方式 | 服务商类型 | Base URL 后缀 |
|----------|-----------|---------------|
| **Anthropic 原生**(接 Claude) | Anthropic | **不加** `/v1`:`https://api.clomio.ai` |
| **OpenAI 兼容**(接 GPT / Grok / Codex 模型等) | OpenAI | **要加** `/v1`:`https://api.clomio.ai/v1` |

- Anthropic 类型下填了 `/v1` 反而会 404。
- 末尾**不要多余斜杠**:✅ `https://api.clomio.ai/v1` ❌ `https://api.clomio.ai/v1/`
- 地址同样可换成另外两条线路(`sub.qazwc.com` / `crs.qazwc.com`),见 [网关线路](#/gateway-lines)。OpenAI 类型换线后仍要保留 `/v1`,例如 `https://crs.qazwc.com/v1`;Anthropic 类型仍不加。
- 不要手动拼完整端点:Base URL 填到版本根即可,不要填成 `/v1/chat/completions`、`/v1/responses` 或 `/v1/messages`。

> 怎么选?接 **Claude** 用 Anthropic 原生类型,能用上 extended thinking、PDF 输入等特性;接 **GPT / Grok** 用 OpenAI 兼容类型。日常聊天写代码,OpenAI 兼容也够用。

建议在 Cherry Studio 里按协议建多个服务商,例如 `Clomio Claude`、`Clomio OpenAI`、`Clomio Grok`,分别保存不同 Base URL 和 Key。不要在一个 OpenAI 服务商里同时塞 Claude 模型,也不要把 Grok Key 放到 Anthropic 类型下。

---

## 三、填密钥与模型

1. **API Key**:填你在控制台 [api.clomio.ai](https://api.clomio.ai) 创建的密钥(注意分组要与模型和协议匹配,见 [创建 API 密钥](#/api-key)):Claude 模型用 Claude/Anthropic 分组;GPT/Codex 模型用 OpenAI 分组;Grok 模型和 Videos 用 Grok 分组。
2. **添加模型**:自定义服务商通常不会自动拉模型列表,需手动点「添加模型」,**手动输入模型 ID**(如 `claude-sonnet-4-6`)。
   - 模型 ID **大小写敏感、必须完全匹配**,填错不会报语法错而是返回 `model not found`。
   - 具体可用的模型名以控制台该分组显示为准。
3. 点「**检查连接**」只代表 Cherry Studio 当前探针通过。回到对话界面后,还要用你真实要用的模型和功能发一次最小请求。

> “检查连接”不是完整能力证明。它可能只测 `/v1/models`、`/v1/chat/completions` 或一个默认文本请求:绿色只说明这条探针通了,不代表当前模型、图片、知识库 embeddings、Responses、Videos、Web Search 都可用；红色也不一定代表 Key 失效,可能只是拿 Chat Completions 去测了 Grok Responses/Videos 分组。最终以真实请求路径为准,排障时记录 HTTP status、响应体和 `x-request-id`。
>
> Cherry Studio 本页主要覆盖聊天/模型服务商接入。Videos 是 Grok-only 的独立视频端点,不要用聊天探针判断它是否可用；请按 [Videos](#/api-videos) 的 `/v1/videos/generations` curl 单独验证。

---

## 四、常见报错

| 报错 | 原因 / 处理 |
|------|------------|
| **401 Unauthorized** | 密钥不对、复制不完整,或分组不匹配。确认这把 Key 属于当前服务商类型要用的分组。 |
| **404 / Invalid URL** | 地址后缀错了。看到 `/v1/v1` 是重复;Anthropic 类型别加 `/v1`;OpenAI 类型别漏 `/v1`;去掉末尾多余斜杠。 |
| **model not found** | 模型 ID 拼错、大小写不符,或 Key 分组没有这个模型,以控制台为准重填/换分组。 |
| **Videos API is not supported for this platform** | Videos 仅 Grok 分组可用;换 Grok 分组 Key 和 Grok/video 模型。 |
| **Embeddings API is not supported for this platform** | 当前 Key 不是 OpenAI 分组。Embeddings 仅 OpenAI 分组可用;关闭客户端向量/知识库索引或换 OpenAI 分组 Key。 |
| **Messages API is not supported for this platform** | 当前分组未开放 Messages 兼容能力。把 Grok 配成 OpenAI 兼容服务商,或换已开放 Messages 的分组。 |
| **SSL 证书错误** | 本机开着代理工具所致。设置 →「代理设置」→ 选「不使用代理」或直连。详见 [故障排查](#/troubleshooting)。 |

---

## 五、curl 快速验证

Cherry Studio UI 报错时,先用同一条线路和同一把 Key 验证协议是否选对。

**OpenAI 兼容:**

```bash
curl https://api.clomio.ai/v1/chat/completions \
  -H "Authorization: Bearer 你的密钥" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'
```

**Anthropic 原生:**

```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"}]}'
```

**Grok / Responses:**

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

如果 Cherry 的“检查连接”固定测试 `/v1/chat/completions`,Grok 分组会失败,这不代表 Grok Responses 不可用。请看实际请求路径,或用上面的 Responses curl 单独验证。

如果 UI 里能看到请求路径或响应体,优先用它定位分组不匹配:

- `/v1/messages` + Grok Key:是否可用取决于分组 Messages ingress；未开放时换 Anthropic/Claude Key或改用 Responses/Chat。
- `/v1/chat/completions` + Grok Key:支持；若 Cherry Studio 检测仍失败，检查模型和分组能力。
- `/v1/responses` + Claude Key:不支持,换 OpenAI/Codex 或 Grok Responses 分组。
- `/v1/embeddings` + Grok/Claude Key:不支持,Embeddings 换 OpenAI 分组。
- `/v1/videos/*` + 非 Grok Key:不支持,Videos 只用 Grok 分组。
- `/v1/web_search` + 非 Grok Key:不支持,Web Search 只用 Grok 分组。

> 想配成命令行编程助手而不是聊天客户端?见 [Claude Code](#/claude-code) / [Codex](#/codex);图形化切换多供应商见 [CC Switch](#/cc-switch)。