# Cherry Studio 集成

> 在 Cherry Studio 里添加自定义提供商,一把 Key 接 OpenAI / Anthropic / Gemini 三种协议

来源：https://qd.zsopc.com/docs/integrations/cherry-studio

> [Cherry Studio](https://github.com/CherryHQ/cherry-studio) 是开源的桌面 AI 客户端(Windows / macOS / Linux)。本页步骤按 Cherry Studio v2.2.2(2026-11-13 发布)的界面与[官方文档](https://cherryai.com/docs/en/pre-basic/providers/zi-ding-yi-fu-wu-shang/)核对。旧版本里的「提供商类型」下拉框,在这一版改成了按协议分别填地址。

## 准备 API Key

在 [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) 创建 API Key(`sk-gpushare-` + 64 位十六进制,创建后可在 Key 详情页随时重新查看)。

## 添加提供商

1. 左侧 **设置** → **模型服务** → 列表底部 **+ 添加服务商**,弹出「添加自定义提供商」
2. 填:
   - **提供商名称**: 随意,如 `小战AIhub`
   - **API 密钥**: 你的 `sk-gpushare-...`
   - **端点设置** → **OpenAI**: `https://qd.zsopc.com`
   - 可选:**Anthropic** 也填 `https://qd.zsopc.com`;展开 **更多设置** 还有 **OpenAI Responses** 与 **Gemini**,同样填 `https://qd.zsopc.com`
3. 点 **添加**,再打开提供商页面右上角的启用开关(不打开,模型不会出现在选择器里)

每个地址栏下方会预览最终请求路径。Cherry Studio 自己补 API 版本(OpenAI / Anthropic / Responses 补 `/v1`,Gemini 补 `/v1beta`),所以只填域名即可:

| 地址栏 | 填写 | 最终请求 |
|---|---|---|
| OpenAI | `https://qd.zsopc.com` | `https://qd.zsopc.com/v1/chat/completions` |
| Anthropic | `https://qd.zsopc.com` | `https://qd.zsopc.com/v1/messages` |
| OpenAI Responses | `https://qd.zsopc.com` | `https://qd.zsopc.com/v1/responses` |
| Gemini | `https://qd.zsopc.com` | `https://qd.zsopc.com/v1beta/models/{model}:generateContent` |

> 地址末尾**不要**加 `#`:`#` 的意思是「不自动补版本号」,请求会少掉 `/v1`。

## 添加模型

- 点 **同步模型** 从 `GET /v1/models` 拉列表;或点旁边的 **+** 手动填模型 ID(如 `claude-sonnet-4-6`、`gpt-6.1-sol`、`gemini-3.1-pro-low`、`deepseek-v4.1-flash`)
- 同步时弹出的「模型管理」会把新模型默认全部勾上,其中图像、视频等模型不能在对话里用,取消勾选即可。完整列表见 [模型列表](../reference/models.md)
- 填好后点 **检测**(Model Check)测试连通,它默认用最后添加的那个对话模型

## 每个模型走哪种协议

默认所有模型都走标了「默认」的那一栏(没手动设过就是 OpenAI 一栏)。只填 OpenAI 一栏就能调全部文本模型 —— Claude、Gemini 也能这样调,网关会自动做协议翻译,见 [兼容矩阵](../reference/compatibility-matrix.md)。

想让 Claude 走 Anthropic 原生协议:Anthropic 一栏也填上地址,然后在模型的设置里把 **模型用途** → **对话** → **对话协议** 改成 Anthropic。这一项只在配置了不止一种协议时出现。Gemini 同理。

> Cherry Studio 还能接 MCP 服务器。想在对话里出图、做视频、做音乐,可以接本平台的 [MCP 媒体工具](./mcp.md)。

## 常见问题

| 现象 | 排查 |
|---|---|
| 401 `invalid_api_key` | Key 是否复制完整(共 76 字符);可在 [Key 详情页](https://qd.zsopc.com/dashboard/keys) 重新查看 |
| 404 | 看地址栏下方的预览路径,确认没有加 `#`,也没有重复的 `/v1` |
| 模型选择器里没有这个提供商 | 提供商页面右上角的启用开关没打开 |
| 400 `model_not_found` | 模型 ID 拼写,须与 [模型列表](../reference/models.md) 一致 |
| 400 `model_not_allowed` | 这把 Key 设了模型白名单,不含该模型 |
| 402 `quota_exceeded` | 余额不足。所有 Key 共享同一账户余额,到 [充值页](https://qd.zsopc.com/dashboard/billing) 充值 |

错误码完整说明见 [错误码](../reference/errors.md)。

## 其他客户端

- [Chatbox](./chatbox.md) — 桌面 / 手机客户端
- [LobeChat](./lobechat.md) — 可自托管的对话应用
- [NextChat](./nextchat.md) — 轻量网页对话
- [Open WebUI](./open-webui.md) — 自托管 ChatGPT 风格界面
