Cherry Studio 接入

在 Cherry Studio 里添加 QCode.cc 自定义服务商：设置到模型服务的路径、四种提供商类型各填什么地址、以及 Agent 功能为什么建议 Anthropic 类型

更新于 2026-10-15

本页目录

接入速览
前提条件
配置步骤
验证是否接通
已知限制
提供商类型与 QCode 地址对照
关键配置项说明
常见报错与排查
常见问题
相关文档

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

接入速览¶

项目	说明
可用模型	Claude ✅（Anthropic 类型）· GPT ✅（OpenAI 类型）· 国产 ✅（OpenAI 类型）· Gemini ❌（QCode 暂不提供）
协议与 Base URL	Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai`（API 地址只填根地址，见下）
配置位置	应用内：设置 → 模型服务 → 「+ 添加服务商」
官方文档	服务商配置

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

前提条件¶

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

配置步骤¶

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

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

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

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

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

其余类型¶

OpenAI Responses：类型选它、API 地址同样填 https://api.qcode.cc/openai；QCode 对应接口只服务 GPT 系，Claude 与国产模型不可用（见接入点与 API 格式）。
Gemini（QCode 暂不提供 Gemini，此条仅说明 Cherry 的类型）：API 地址填 https://api.qcode.cc/gemini；Cherry 对 Gemini 类型的具体拼接形态我们未实测，若模型列表或对话报 404，用「根地址 + 尾部 # 关拼接」的方式调整。

验证是否接通¶

在任一聊天窗口选中新配的模型发一句话；或用应用内的模型列表拉取功能（它会请求 <API 地址>/models）。看不到回复时：先确认类型与地址匹配（Claude 用 Anthropic 类型）、再确认没有把 /v1 手写进 API 地址（会被拼成 /v1/v1）。仍不通按故障排查顺序查，每次请求可在 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 图像生成与编辑，未在本页验证 Cherry 侧行为。
官方文档站近期迁移过域名（docs.cherry-ai.com 现 301 到 docs.cherryai.com.cn），旧书签会跳转。

提供商类型与 QCode 地址对照¶

截至 2026-10-15，据 Cherry Studio 官方文档的「提供商类型」说明：OpenAI 兼容类型走 /v1/chat/completions，Anthropic 兼容类型走 /v1/messages，Cherry Agent 要求使用 Anthropic 类型；自定义提供商可接入任何 OpenAI / Anthropic / Gemini 兼容的端点。对应到 QCode：

Cherry Studio 类型	API 地址填	可用模型	Cherry 实际请求
Anthropic	`https://api.qcode.cc/api`	Claude；国产模型也可走	`/api/v1/messages`
OpenAI	`https://api.qcode.cc/openai`	GPT、国产模型	`/openai/v1/chat/completions`
OpenAI Responses	`https://api.qcode.cc/openai`	仅 GPT	`/openai/v1/responses`

中国大陆把 api.qcode.cc 换成 asia.qcode.cc。

关键配置项说明¶

设置项	说明
提供商类型	决定协议和拼接的路径，是最容易选错的一项；选错时错误通常表现为 404 或 `model_not_available_on_endpoint`
API 地址	只填根地址，不要手写 `/v1` 或完整路径；需要固定路径时才在末尾加 `#` 关闭自动拼接
API 密钥	`cr_` 开头的 QCode 密钥，前后不要有空格
模型 ID	手动添加或「获取模型列表」，Claude 与 GPT 的真实 ID 以 qcode.cc/models 为准

常见报错与排查¶

现象	常见原因	处理
`model_not_available_on_endpoint`	Claude 模型挂在了 OpenAI 类型的提供商下	另建一个 Anthropic 类型的提供商，地址填 `https://api.qcode.cc/api`
404	API 地址手写了 `/v1`（被拼成 `/v1/v1`），或类型与地址不匹配	去掉 `/v1`，核对上面的对照表
`Invalid API key`	密钥错或带空格，或把别家的密钥填进来了	重新复制 `cr_` 密钥
「获取模型列表」为空或失败	拉取走 `<API 地址>/models`，类型或地址不对	先修好类型和地址，仍为空就手动添加模型 ID
Agent 功能用不了	当前提供商不是 Anthropic 类型	按路径 A 配置 Anthropic 类型
国内访问不稳	默认域名网络路径不佳	换 `asia.qcode.cc`

仍无法判断时，到 probe.qcode.cc 输入密钥，看请求是否到达 QCode，再按故障排查往下查。

常见问题¶

Cherry Studio 要不要注册它自己的账号？¶

不需要。它是纯本地配置的客户端，只要填入 QCode 的地址和密钥就能用。

为什么同一把密钥要建两个提供商？¶

因为 Claude 只能走 Anthropic 接口，GPT 与国产模型走 OpenAI 接口，而 Cherry Studio 的提供商类型一次只能选一种。两个提供商填同一把 cr_ 密钥，只是地址和类型不同。

想用应用里的 Agent 功能，该怎么配？¶

按官方说明，Cherry Agent 需要 Anthropic 类型的提供商：类型选 Anthropic，API 地址填 https://api.qcode.cc/api，再加入 Claude 模型。

什么时候才需要在 API 地址末尾加 `#`？¶

只有当服务要求固定的完整路径、不希望 Cherry Studio 按类型自动拼接时才需要。QCode 的常规用法按上面的对照表只填根地址即可，不用加。

可以用 Cherry Studio 调用 Gemini 吗？¶

QCode 暂不提供 Gemini 模型，请改用 Claude、GPT 或国产模型。