Cherry Studio 接入自定义 API 教程：Base URL、Key 与模型（2026）

Cherry Studio 是常用的桌面 AI 客户端，支持多服务商、多模型切换、助手和知识库。它本身不提供模型，模型来自你配置的 API。很多用户卡在同一步：Base URL 填什么、Key 放哪里、模型 ID 怎么加。本文按当前常见版本走一遍完整流程。

说明：Cherry Studio 是其权利人的产品，本文仅作技术接入说明。界面名称和功能入口可能随版本调整，以当前版本为准；模型与价格以站内模型价格为准。

一、接入前准备三样东西

无论用哪家网关，自定义服务商都只需要三样参数：

API Key：在中商起航 AI 网关注册后，到控制台创建，按项目或环境命名。
Base URL：网关的 OpenAI 兼容地址，通常是 https://ai.zhongshangqihang.com/v1。
模型 ID：从模型价格页复制，注意复制 API 标识而不是展示名。

先用一条命令验证 Key 和模型是否可用，再进客户端配置，能少走很多弯路：

export ZSQH_API_KEY="sk-你的密钥"

curl "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、地址和模型三件事至少是通的，问题只会出在客户端配置上。

二、Base URL 到底怎么填

Cherry Studio 的字段叫法可能随版本变化，常见是“API 地址”或“API Host”。建议按下面的口径填写：

配置项	建议填法	说明
服务商类型	OpenAI	使用 OpenAI 兼容协议
API 地址	`https://ai.zhongshangqihang.com/v1`	末尾不加斜杠
API 密钥	`sk-...`	控制台创建的 Key
模型 ID	以价格页为准	手动添加时尤其要核对

不同版本对 /v1 的处理不一样：有的会自动补 /v1，有的要求你写完整。判断方法很简单：401 多半是 Key 问题，404 多半是路径问题。如果填完整地址报 404，就试着去掉 /v1；如果填域名报 404，就补上 /v1。一次只改一个变量，不要同时换 Key、地址和模型。

三、添加自定义服务商

以当前常见版本为例，操作顺序如下（按钮名称以你的版本为准）：

打开 Cherry Studio，点左下角设置（齿轮图标）。
进入“模型服务”或“模型提供方”。
点“+ 添加服务商”。
服务商类型选 OpenAI，或选择 OpenAI 兼容的选项。
填写服务商名称、API 密钥、API 地址。
保存后回到模型列表，继续添加模型 ID。

如果版本里没有“添加服务商”，先升级客户端。旧版本的入口和字段可能不同，照旧教程硬配很容易填错位置。

四、添加模型 ID

保存服务商后，有两种添加模型的方式：

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

模型 ID 必须和价格页完全一致，包括大小写、版本后缀和连字符。手动添加时还要确认模型类型是“对话”或“聊天”；类型选错，模型不会出现在对话界面的选择器里。

模型类型	常见用途	注意
对话模型	日常问答、写作、代码	最常用，先配这个
推理模型	复杂分析、数学、规划	延迟和成本通常更高
视觉模型	图片理解、截图问答	确认网关是否支持图片输入
嵌入模型	知识库、向量检索	需要单独确认接口与模型

如果要用知识库，嵌入模型必须也在网关侧可用；只配了对话模型，上传文档时仍会报错。遇到这种情况，先确认网关是否提供嵌入接口，再决定是否单独配置一个嵌入服务商。

五、验证与排错顺序

配置完成后，新建一个对话，选刚添加的模型，发一句“只回复 OK”。失败时按下面顺序排查，不要一上来就重装客户端：

现象	常见原因	处理
`401 Unauthorized`	Key 错误、过期或没保存	重新粘贴 Key，注意前后空格
`404 Not Found`	Base URL 的 `/v1` 不对	按上一节的方法增减 `/v1`
`model not found`	模型 ID 写错或未开通	对照价格页复制准确标识
获取模型列表失败	网关未开放列表接口	改用手动添加模型 ID
对话中途断流	网络波动或超时	检查代理、降低并发、重试
知识库报错	嵌入模型未配置	单独配置可用的嵌入模型

还有一个容易忽略的点：公司网络或代理软件可能拦截 SSE 流式响应，表现为“能发出去、收不回来”。把流式输出临时关掉测试，如果非流式正常，就重点查代理和防火墙。

六、多模型与日常使用

Cherry Studio 的价值在于把不同任务分开。实用的做法是：

给日常问答配一个通用模型，响应快、成本可控。
给长文总结配一个长上下文模型，单独建助手。
给代码任务配一个代码能力更强的模型。
给知识库单独准备嵌入模型。
每个助手写清系统提示词，减少每次重复交代。

模型越多，越要控制上下文长度。把整篇文档反复塞进对话，会让每次请求都变贵；能放进知识库的先入库，能用摘要的先用摘要。

七、安全与团队使用

Key 存在客户端本机，共用电脑时要考虑系统账户隔离。
不要在公司公用设备上保存长期 Key。
按项目发 Key，方便在网关侧看用量和吊销。
客户端里不要粘贴客户隐私、合同原文和未脱敏数据。
定期检查网关用量，异常增长先停 Key 再排查。

常见问题

Cherry Studio 是免费的吗？

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

为什么填了 Key 还是 401？

先确认 Key 没有多余空格，再确认它属于当前 Base URL 对应的平台。不同网关的 Key 不能混用；也要检查 Key 是否被删除或额度已用完。

Base URL 要不要带 `/v1`？

以当前版本的提示为准。多数 OpenAI 兼容配置需要 /v1，但有的客户端会自动补。判断标准是请求是否打到 /v1/chat/completions，报 404 就调整结尾。

能不能用 Claude 或 Gemini 模型？

可以，前提是网关把对应模型以 OpenAI 兼容格式提供，并且你填的是该模型的准确 ID。原生协议不同的模型，部分参数可能不兼容，以站内文档为准。

配置好后能离线使用吗？

不能。客户端只是界面，推理发生在远端 API。没有网络或网关不可达时，对话无法完成。

下一步

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