Cherry Studio 怎么接入 API 中转配置教程

Cherry Studio 是桌面上最省事的多模型客户端之一：一个窗口里切 GPT、Claude、Gemini、DeepSeek，本地知识库和助手也自带。但它默认只认官方服务商列表，很多人卡在"想用自己的中转地址"这一步——找不到地方填 base_url，或者填了之后模型下拉框是空的。

这篇按实际操作顺序走一遍：添加服务商 → 填地址和 Key → 手动写模型列表 → 配套设置 → 出问题怎么查。

先说结论#

• Cherry Studio 添加自定义服务商的入口在「设置 → 模型服务」，选「OpenAI」类型再加，不要选具体厂商
• 填写三样东西：API 地址（带上 /v1）、API 密钥、模型 ID 列表
• 模型不会自动拉取，必须手动填模型 ID，大小写和连字符要和请求时完全一致
• 地址少写 /v1 或写成 /v1/chat/completions 都会导致 404，这是最高频的一个坑
• 配置完先用「检查」按钮测一个最便宜的模型，通过后再配助手和知识库

一、添加自定义服务商#

打开「设置 → 模型服务」，左下角点「添加」，服务商类型选 OpenAI。选 OpenAI 的含义是"按 OpenAI 兼容协议发请求"，而不是"只能用 OpenAI 的模型"——任何实现了 /v1/chat/completions 的服务都能这样接。

添加后填三个字段：

• 名称：自己看的，写「zaimod」或「主力中转」都行
• API 地址：https://api.zaimod.com/v1
• API 密钥：在控制台创建的 Key，形如 sk- 开头的一串

注意地址末尾不要带斜杠，也不要把 /chat/completions 写进去。客户端会自己在后面拼路径。

二、手动填模型 ID#

Cherry Studio 对自定义服务商不会自动请求模型列表，需要在「模型」区域手动添加。点「添加模型」，填的是模型 ID，不是显示名。

常用写法参考（具体可用型号以控制台模型页为准）：

模型 ID 必须和请求体里的 model 字段一字不差。常见错误是写成「GPT-4o mini」（带空格和大小写），服务端按精确字符串匹配，找不到就报模型不存在。

填完之后，每个模型后面可以设上下文长度和最大输出 tokens。这两项只影响客户端的截断策略，不改变服务端计费，填保守一点没坏处。

三、用命令行先确认地址能通#

在配客户端之前，先确认地址和 Key 本身没问题，能把排查范围砍掉一半：

curl -sS https://api.zaimod.com/v1/chat/completions \
  -H "Authorization: Bearer $ZAIMOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "只回复 ok"}]
  }'

返回一段 JSON 且 choices[0].message.content 里有内容，说明 Key、地址、模型 ID 三样都对，后面出问题就只可能是客户端配置问题。返回 401 是 Key 问题，返回 404 是地址问题，返回 400 且提示模型不存在则是模型 ID 问题。

四、配套设置#

服务商配好之后，还有几处值得顺手调整：

• 默认模型：在「设置 → 默认模型」里把对话、翻译、标题生成分开指定。标题生成这种高频小请求一律用最便宜的模型，能省下可观的量。
• 知识库嵌入模型：知识库需要单独的 embedding 模型，在「设置 → 模型服务 → 嵌入模型」里归到同一个服务商下，否则建库时会报找不到模型。
• 流式输出：默认开启。若遇到长回复中途断开，先关掉流式判断是不是网络层问题。
• 代理：配了中转地址之后，客户端的系统代理要放行该域名，否则请求可能被本地代理拦掉。

五、配置后不出字怎么查#

按这个顺序查，基本三步内能定位：

1. 点「检查」按钮：客户端会发一次最小请求，失败会直接显示状态码和错误消息。
2. 看状态码：401 → Key 错或已被禁用；404 → 地址错；400 → 模型 ID 错或请求体字段不合法；429 → 触发频率限制，降低并发。
3. 复制报错原文：客户端显示的报错通常就是上游返回的 JSON，里面的 message 字段往往直接写明了原因。

如果检查通过但对话里不出字，多半是当前会话选的模型不在你添加的那个列表里——会话顶部的模型选择器默认可能还是别家的模型。

FAQ#

一定要用 /v1 结尾吗？

对 OpenAI 兼容协议的服务，是。客户端按「base_url + /chat/completions」拼路径，少了 /v1 就拼错。少数服务把路由放在根路径，那种情况才不需要。

一个服务商里能填多个 Key 吗？

不建议。Cherry Studio 一个服务商对应一个 Key，多 Key 轮换请交给网关侧做，见多个 API Key 怎么管理和限流。

模型列表里能混多家的模型吗？

可以。中转服务本身就把多个厂商的模型统一到一个地址和一个 Key 下，在同一个服务商里把 GPT、Claude、DeepSeek 的 ID 都加上即可，切换只是换个下拉框。

换机器要重新配吗？

配置可以导出，导出文件里含 Key，跨机器传输请走加密通道，不要丢在公共网盘里。

延伸阅读#

• Cherry Studio、Cursor、Cline 三件套怎么配：多客户端共用一套 Key 的配法
• OpenAI 兼容协议到底兼容了什么：理解 base_url 和路径拼接的由来
• 为什么换 base_url 会突然报错：迁移时最容易踩的结构差异
• 模型价格对比：按 token 单价挑默认模型

还没有可用的 Key？注册后即可创建，一个地址、一个 Key 覆盖全部模型，配好上面三样就能直接用。