Cherry Studio 自定义 API 配置教程：多模型与知识库接入（2026）

Cherry Studio 是常用的桌面 AI 客户端，支持 Windows、macOS 和 Linux。它本身不提供模型，模型来自你配置的 API 服务商。除了内置服务商，它也可以添加 OpenAI 兼容的自定义端点，这对使用统一网关的团队很实用：一个 Base URL、一把 Key，就能切换多家模型。

本文按 2026 年常见版本，从安装讲到服务商、模型、助手、知识库和团队使用。界面名称随版本变化，以当前版本为准。

说明：Cherry Studio 是其权利人的产品与商标；OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术接入说明，与上述公司无隶属或合作关系。模型、接口范围与价格以站内模型价格页为准。

一、安装：优先用官方渠道

Cherry Studio 提供桌面安装包，常见下载入口是官网和项目的 GitHub Releases。按系统选择对应安装包：

Windows：下载安装程序，按提示完成安装。
macOS：下载 dmg，拖入应用程序目录；首次打开若被系统拦截，按系统提示放行。
Linux：按项目提供的 AppImage 或发行版包安装。

不建议用来路不明的“绿色版”或改包，桌面客户端会保存 API Key 和聊天记录，来源不可控的安装包风险很高。安装完成后先打开“设置”里的“关于”确认版本，再决定是否升级；旧版本的按钮名称和字段位置可能不同。

二、准备三样参数

自定义服务商只需要三样东西，但每一项都容易填错：

配置项	建议填法	说明
服务商类型	OpenAI	使用 OpenAI 兼容协议
API 地址	`https://ai.zhongshangqihang.com/v1`	填到 `/v1`，不要填完整接口路径
API 密钥	`sk-...`	在网关控制台创建，按项目命名
模型 ID	站内价格页的 API 标识	不是网页上的展示名

Key 在注册中商起航 AI 网关后到控制台创建。建议一个项目一把 Key，方便看用量、限额和吊销。模型 ID 从模型价格页复制，注意大小写、连字符和版本后缀。

三、添加自定义服务商

以当前常见版本为例，操作顺序如下：

打开 Cherry Studio，点击左下角齿轮图标进入设置。
选择“模型服务”。
点击服务商列表下方的“+ 添加服务商”。
在“添加自定义提供商”里填写“提供商名称”，例如“中商起航网关”。
填写“API 密钥”。
在“端点设置”里选择 OpenAI；如果网关提供 Responses 协议，也可以在“更多设置”里选择 OpenAI Responses。
填写 API 地址，例如 https://ai.zhongshangqihang.com/v1。
点击“添加”保存。

如果版本里找不到“+ 添加服务商”，先升级客户端。不同版本对端点类型的叫法不完全一样，但核心字段不变：名称、Key、地址。图像生成和图像编辑是单独的 Base URL 选项，不要和对话模型的地址混在一起填。

四、添加模型并检查连通性

保存服务商后，回到该服务商的模型列表，有两种添加方式：

获取模型列表：客户端向网关请求可用模型，成功后勾选需要的模型。
手动添加：点击“+”直接输入模型 ID。网关没有开放列表接口，或拉取失败时用这种方式。

模型 ID 必须和价格页完全一致。手动添加后还要确认模型类型是“对话”或“聊天”；类型选错，模型不会出现在对话界面的选择器里。嵌入模型、图像模型要按用途单独添加。

界面上的“检查”按钮主要验证 API Key 是否可用，不等于每个模型都对你开放。保存后新建一个对话，选刚添加的模型，发一句“只回复 OK”，这才是完整验证。

五、先用 curl 验证，再回客户端

配置卡住时，先用一条最小请求区分问题在网关还是在客户端：

export ZSQH_API_KEY="sk-你的密钥"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型ID",
    "messages": [{"role": "user", "content": "只回复 OK"}]
  }'

返回里有 choices，说明地址、Key 和模型至少是通的，问题多半在客户端字段或网络代理。返回 401 先查 Key 和空格，返回 404 先查 /v1 与模型 ID，返回 429 先看用量和并发。一次只改一个变量，避免同时换 Key、地址和模型。

六、助手：把模型分配到具体任务

Cherry Studio 的“助手”可以保存系统提示词、模型和参数，适合把重复工作固定下来。实用的分工方式是：

日常问答用一个响应快、成本可控的通用模型。
长文总结单独建助手，配长上下文模型，并在提示词里限定输出结构。
代码任务用代码能力更强的模型，明确要求先读文件再改。
翻译、润色各建一个助手，把术语表和风格要求写进系统提示词。
每个助手只解决一类问题，避免提示词越堆越长。

也可以在设置里指定默认模型，减少每次新建对话时的选择成本。模型越多，越要控制上下文：能放进知识库的资料先入库，能先摘要的不要整篇反复粘贴。

七、知识库：嵌入模型不是必选项

创建知识库的入口在左侧“知识库”，点“新增”，填写能说明资料边界的名称，然后选择嵌入模型。当前版本提供三种方式：

不使用：只做 BM25 关键词检索，不需要额外配置，适合先验证流程。
云端嵌入模型：需要对应的嵌入模型服务可正常调用，检索会结合关键词和向量。
本地嵌入模型：先在“设置 → 本地模型”下载嵌入模型，再回到知识库选择。

嵌入要走网关，先确认网关提供嵌入接口和对应模型；没有就选“不使用”或本地嵌入。创建后点“添加资料”，先导入一两份答案明确的文件，处理完再测试提问。

更换嵌入模型可能触发“重建知识库”。重建前确认新模型可用，不要同时更换模型和分块设置，否则无法判断效果变化来自哪一项。

八、常见故障的排查顺序

现象	常见原因	处理
`401 Unauthorized`	Key 错误、带空格或未保存	重新粘贴，确认 Key 属于当前网关
`404 Not Found`	API 地址多了或少了 `/v1`	只保留到 `/v1`，不要填完整路径
`model not found`	模型 ID 错误或未开通	从价格页复制准确标识
获取模型列表失败	网关未开放列表接口	改用手动添加模型 ID
知识库效果差	分块、检索方式或资料质量	先用小资料集测试，再调整分块
对话中途断流	代理、防火墙或网络波动	关掉流式测试，检查代理与超时

公司网络或代理软件可能拦截 SSE 流式响应，表现为“能发出去、收不回来”。临时关闭流式输出，如果非流式正常，就重点查代理和防火墙，而不是反复改模型。

九、团队使用：共享的是规范，不是 Key

Cherry Studio 是桌面客户端，公开文档没有把多用户权限管理列为核心能力。团队使用更像“统一配置规范 + 各自本地客户端”。建议：

每人用自己的网关 Key，按人命名；离职或泄露时单独吊销。
在网关侧看用量和限额，按项目拆分成本。
把常用助手的系统提示词整理成文本模板，统一分发。
知识库资料放在团队可控的共享位置，避免各自维护不同版本。
备份用 WebDAV 或 S3 兼容存储，但要知道备份里包含 Provider 配置和 API Key。
不要把备份文件发到群里，也不要放在不受信任的共享网盘。
不在公用电脑保存长期 Key，不在对话里粘贴客户隐私和未脱敏合同。

团队若需统一审计、额度和权限，重点应放在网关侧。

常见问题

Cherry Studio 是免费的吗？

客户端本身可以免费使用，但模型调用费用由你配置的 API 服务商收取。具体以客户端当前版本和网关价格页为准。

Base URL 要不要带 `/v1`？

多数 OpenAI 兼容配置需要带 /v1，填到 https://ai.zhongshangqihang.com/v1 即可。不要填 /v1/chat/completions，客户端会自己拼接接口路径。

获取模型列表失败怎么办？

先确认网关是否开放模型列表接口。没有开放或请求失败时，点“+”手动输入模型 ID，效果一样。模型 ID 以价格页的 API 标识为准。

知识库必须配置嵌入模型吗？

不是。当前版本可以选“不使用”，用 BM25 关键词检索完成基本问答。需要向量检索时再配置云端或本地嵌入模型，并确认对应服务可调用。

团队可以共用一把 Key 吗？

不建议。共用 Key 无法区分用量，一人泄露全组受影响。按人、按项目或按环境分别发 Key，配合网关的限额和用量报表更可控。

下一步

Cherry Studio 的接入不复杂，难的是把 Base URL、Key 和模型 ID 三处对齐。先用 curl 跑通，再进客户端；出问题按 401、404、model not found 的顺序排查。需要统一模型入口和用量管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。