# Cherry Studio 接入

> **最后核实**：2026-09-18 · 📄 依据官方文档（Cherry Studio v2.0.14，2026-09-09 发布）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（Anthropic 类型）· GPT ✅（OpenAI 类型）· 国产 ✅（OpenAI 类型）· Gemini ✅（Gemini 类型，拼接形态未实测） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai` · Gemini：`https://api.qcode.cc/gemini`（API 地址只填根地址，见下） |
| 配置位置 | 应用内：设置 → 模型服务 → 「+ 添加服务商」 |
| 官方文档 | [服务商配置](https://docs.cherryai.com.cn/) |

Cherry Studio 是中文用户里最常见的开源桌面 AI 客户端之一（Windows / macOS / Linux），聊天、翻译、知识库、MCP 都在这一个窗口里。**没有账号体系，纯本地配置**——接上任何 OpenAI / Anthropic 兼容端点就能用。

## 前提条件

- 已安装 Cherry Studio（官网下载分 Global 与 CN 两套包，x64 / ARM64；系统最低版本官方未明示，以[下载页](https://www.cherryai.com.cn/)为准）。**不需要** Cherry Studio 账号，也不需要任何模型厂商账号。
- 一把 QCode.cc 的 `cr_` 密钥（[控制台](https://qcode.cc/dashboard)创建）。
- 中国大陆网络建议把下文所有 `api.qcode.cc` 换成 `asia.qcode.cc`，能力完全一致。

## 配置步骤

打开 **设置 → 模型服务**，点击列表下方的「**+ 添加服务商**」，在「添加自定义提供商」弹窗中操作。官方规则：**「API 地址」只填根地址、不带 `/v1` 与路径**——Cherry Studio 会按你选的类型自动拼接（如 OpenAI 类型拼 `/v1/chat/completions`）；确需关闭拼接，在地址末尾加 `#`。

### 路径 A：接 Claude 模型（Anthropic 类型，推荐）

1. 类型选 **Anthropic**。
2. API 地址填 `https://api.qcode.cc/api`。
3. API 密钥填你的 `cr_` 密钥。
4. 在端点/模型设置中加入要用的模型 ID（如 `claude-sonnet-5`），或获取模型列表。
5. 官方文档明确：**Cherry Agent 功能需要支持 Anthropic 协议的端点**——想用应用内的 Agent 能力，就按本路径配置。

### 路径 B：接 GPT 与国产模型（OpenAI 类型）

1. 类型选 **OpenAI**。
2. API 地址填 `https://api.qcode.cc/openai`（Cherry 自动拼成 `/openai/v1/chat/completions`）。
3. API 密钥填同一把 `cr_` 密钥。
4. 模型 ID 填在售的 GPT 系（`gpt-5.6` 等）或国产系（`glm-5.3`、`kimi-k3`、`deepseek-v4.1-flash`、`qwen3.8-max` 等），以 [qcode.cc/models](https://qcode.cc/models) 为准。

### 其余类型

- **OpenAI Responses**：类型选它、API 地址同样填 `https://api.qcode.cc/openai`；QCode 这条腿**只服务 GPT 系**，Claude 与国产模型不可用（见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）。
- **Gemini**：API 地址填 `https://api.qcode.cc/gemini`；Cherry 对 Gemini 类型的具体拼接形态我们未实测，若模型列表或对话报 404，用「根地址 + 尾部 `#` 关拼接」的方式调整。

## 验证是否接通

在任一聊天窗口选中新配的模型发一句话；或用应用内的模型列表拉取功能（它会请求 `<API 地址>/models`）。看不到回复时：先确认类型与地址匹配（Claude 用 Anthropic 类型）、再确认没有把 `/v1` 手写进 API 地址（会被拼成 `/v1/v1`）。仍不通按 [故障排查](/docs/reference/troubleshooting) 顺序查，每次请求可在 [probe.qcode.cc](https://probe.qcode.cc) 看到。

## 已知限制

- **Claude 不能走 OpenAI 类型**：QCode 的 OpenAI 腿对 Claude 模型直接拒绝（`model_not_available_on_endpoint`），要 Claude 请用 Anthropic 类型。
- API 地址**不要**手写 `/v1/chat/completions` 等完整路径——官方默认行为是拼接；例外时才用尾部 `#`。
- 官方中英文文档对设置页标签存在 `Model Services` / `Model Provider` 两种写法，界面实际以你的客户端版本为准；弹窗按钮「获取模型列表」在不同版本可能显示为「同步模型」。
- 图片生成 / 图片编辑有独立的 Base URL 配置项；QCode 的图像模型（`gpt-image-2`）接入方式见 [gpt-image-2 图像生成与编辑](/docs/usage/image-2)，未在本页验证 Cherry 侧行为。
- 官方文档站近期迁移过域名（docs.cherry-ai.com 现 301 到 docs.cherryai.com.cn），旧书签会跳转。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)
- [工具兼容总览](/docs/ide/tool-compatibility)
- [国产模型接入](/docs/usage/cn-models)
- [订阅、官方 API 与 QCode Key](/docs/reference/subscription-vs-api-key)
- [故障排查指南](/docs/reference/troubleshooting)