Cherry Studio桌面客户端API基础配置教程

# Cherry Studio 基础配置教程

> 适用对象：Cherry Studio 桌面客户端（Windows / macOS / Linux）  
> 中转站地址：`https://api.zaimod.com`  
> 目标：把中转站作为自定义提供商接入，添加 Claude / Gemini 等模型并开始对话  
> 说明：本篇讲的是**基础接入**（提供商类型选 OpenAI）。如果你要用 MCP 工具调用，请看配套的《CherryStudio 接入中转站并调用 MCP 教程》，那里类型要选 Anthropic。

---

## 一、开始之前

### 1.1 准备清单

| 项目     | 应该填什么                                    | 说明                                                  |
| ------ | ---------------------------------------- | --------------------------------------------------- |
| 提供商类型  | **OpenAI**                               | 走 `/v1/chat/completions`，一种类型可同时接 Claude、Gemini、GPT |
| API 密钥 | `sk-` 开头的令牌                              | 中转站控制台「API 令牌」页新建                                   |
| API 地址 | `https://api.zaimod.com`                  | 只写到域名，不带 `/v1`                                      |
| 模型 ID  | 如 `claude-sonnet-4-5`、`gemini-2.5-flash` | 以控制台模型列表的实际 ID 为准                                   |

### 1.2 先搞清楚「OpenAI 类型」和「Anthropic 类型」的区别

Cherry Studio 的提供商类型决定了客户端怎么拼请求路径，这一步选错，后面全是 404 或工具失效：

| 提供商类型          | 客户端实际请求                    | 适用场景                                     |
| -------------- | -------------------------- | ---------------------------------------- |
| **OpenAI**（本篇） | `<地址>/v1/chat/completions` | 通用对话。一个提供商下能挂 Claude、Gemini、GPT 多个系列，最省事 |
| Anthropic      | `<地址>/v1/messages`         | 需要 **MCP 工具调用**、需要原生 Claude 参数时使用        |

两种类型都能对话，差别在协议层。**只想聊天就用 OpenAI 类型**；要做文件读写、联网抓取这类工具调用，换 Anthropic 类型更稳。

### 1.3 地址栏的两个后缀约定

API 地址只填域名即可，客户端会自动补 `/v1/chat/completions`。填完后地址栏下方会有一行灰字，实时显示最终的请求地址，可以据此核对。

灰字末尾还有一句提示，说的是地址栏的特殊后缀：

- 地址**以 `/` 结尾** → 忽略默认的版本段（拼成 `<地址>chat/completions`）
- 地址**以 `#` 结尾** → 强制完全按你输入的内容请求，不做任何拼接

正常填 `https://api.zaimod.com` 用不到这两个技巧，只在遇到版本段重复（如 `/v1/v1/...`）时才需要。

---

## 二、安装

### 步骤 1 · 下载并安装客户端

- 官网：`https://www.cherry-ai.com/`
- 下载页（按系统选包）：`https://docs.cherry-ai.com/cherry-studio/download`

装完直接打开，无需登录。

---

## 三、配置提供商

### 步骤 2 · 添加提供商

左侧边栏点 **设置（齿轮）** → 「模型服务」区 → 滚到最底部点 **「+ 添加」**。

弹窗两项：

| 字段    | 填什么                   |
| ----- | --------------------- |
| 提供商名称 | 随便输入，如 `cxhao`，只是显示名  |
| 提供商类型 | 下拉选 **OpenAI**（本篇用这个） |

点 **确定**。

![](/uploads/editor/20261031/img_6ae5f419e8a945.34690328.png)

*① 点底部「+ 添加」→ ② 名称随便输入 → 类型选 OpenAI → 确定*

### 步骤 3 · 填密钥与地址

新增的提供商出现在左侧列表里，点进去：

1. 右上角**开关打开**（显示 ON / 绿色，未开启时填了也不生效）
2. **API 密钥**：粘贴 `sk-` 令牌，**不要加 `Bearer ` 前缀**，客户端会自己加
3. **API 地址**：填 `https://api.zaimod.com`

![](/uploads/editor/20261031/img_6ae5f42602be00.48045812.png)

*红字处填中转地址；下方灰字是客户端提示的最终请求地址*

填完可点密钥右侧的 **「检测」** 按钮试连通性。它只验证「地址能连 + 密钥有效」，**不校验模型名**，所以检测通过后仍要确认模型 ID 写对。

> 这张截图也被《CherryStudio 接入中转站并调用 MCP 教程》引用过。那篇选的是 Anthropic 类型，图里灰字却是 `/v1/chat/completions`，属于跨篇复用导致的图文不符——在本篇里它是对的。

---

## 四、添加模型

### 步骤 4 · 逐个添加模型

在提供商配置页下方找到 **「模型」** 区域，点 **「+ 添加」**，弹窗三个字段：

| 字段    | 填什么                       | 说明                       |
| ----- | ------------------------- | ------------------------ |
| 模型 ID | 中转站里的**准确**模型名            | 必填，写错就报模型不存在             |
| 模型名称  | 一般与 ID 相同                 | 聊天界面显示的名字，可自定义           |
| 分组名称  | 如 `claude-3`、`gemini-2.5` | 仅客户端内归类，**不影响请求**，也不影响计费 |

![](/uploads/editor/20261031/img_6ae5f445814188.32291465.png)

*④ 点「+ 添加」逐条录入；右侧可见已建好的 claude-3、claude-sonnet、gemini-2.5 三个分组*

### 步骤 5 · 确认模型已挂到该提供商下

添加完成后，模型区会按分组列出所有模型，每个模型后面有一排图标（可用能力标识）和编辑、删除按钮。

一个 OpenAI 类型提供商下可以同时挂多个系列，这也是本篇推荐用它做基础接入的原因：

| 分组              | 模型示例                         |
| --------------- | ---------------------------- |
| `claude-3`      | `claude-3-7-sonnet-20250219` |
| `claude-sonnet` | `claude-sonnet-4-20250514`   |
| `gemini-2.5`    | `gemini-2.5-flash`           |

> 上表是原文截图里的型号，**已不是最新**。请打开中转站控制台的模型列表，复制当前可用名称。分组名只是你自己起的标签，叫什么都不影响调用。

---

## 五、选择模型并对话

### 步骤 6 · 在聊天页切换模型

回到聊天界面，点**顶部中间的模型名**，弹出模型选择框：

- 顶部有搜索框，模型多时直接搜
- 列表按提供商分组，同名模型要看清后面所属的提供商  
  |  |  |  
  | --- | --- |
- 选中后，顶部显示为 `模型名 | 提供商名`

![](/uploads/editor/20261031/img_6ae5f452846fe2.77470419.png)

*⑤ 顶部模型名 → 搜索或点选目标模型*

### 步骤 7 · 发送消息验证

发一句话，能正常回复即接入成功。同时核对顶部显示的两段信息：

- 前半段是模型 ID，要与你在步骤 4 填的一致
- 后半段是提供商名称，要与步骤 2 起的名字一致

若显示的不是你新建的提供商，说明当前选中的是内置提供商，回去重新选。

---

## 六、配置速查表

| 配置项    | 值                                  |
| ------ | ---------------------------------- |
| 提供商类型  | **OpenAI**（基础对话）/ Anthropic（需 MCP） |
| 提供商名称  | 任意                                 |
| API 密钥 | `sk-...`（不加 `Bearer` 前缀）           |
| API 地址 | `https://api.zaimod.com`（不带 `/v1`）  |
| 自动请求路径 | `/v1/chat/completions`             |
| 模型 ID  | 控制台模型列表里的准确名称                      |
| 分组名称   | 任意（仅界面归类）                          |
| 开关状态   | 必须为 ON                             |

---

## 七、常见问题

| 现象                      | 原因                                          | 处理                               |
| ----------------------- | ------------------------------------------- | -------------------------------- |
| 提供商列表里是灰的、无法使用          | 右上角开关没打开                                    | 打开开关，变绿/ON                       |
| 对话报 404                 | API 地址带了 `/v1`，成了 `/v1/v1/chat/completions` | 改成纯域名                            |
| 对话报 401 / Invalid token | 密钥错、含空格，或手动加了 `Bearer`                      | 重新粘贴令牌，只留 `sk-` 开头部分             |
| 模型列表里找不到刚加的模型           | 添加时挂到了别的提供商下                                | 点开对应提供商核对                        |
| 提示模型不存在                 | 模型 ID 与中转站不一致                               | 从控制台复制准确 ID 重建                   |
| 「检测」通过但对话失败             | 检测不校验模型名                                    | 重点核对模型 ID                        |
| 换了模型回复风格突变              | 选到了其他提供商的同名模型                               | 看顶部显示的后半段（竖线后面就是提供商名）            |
| 聊天正常但 MCP 用不了           | 用了 OpenAI 类型                                | 需要工具调用时改用 Anthropic 类型，见配套 MCP 篇 |

---

## 附录 A · 原文勘误

原文全长 401 字符，只有 4 个标题和 4 张图，步骤序号全靠图上的红字手写：

1. **没有可执行的步骤文字**：全文只有「配置地址和密钥」「添加模型」「选择模型使用」三个标题，具体点哪里、填什么全靠看图。已按图还原为 7 个步骤并逐条写清点击位置。
2. **漏了「开关要打开」**：截图中开关是 ON 状态，但原文未说明。开关关闭时填了密钥和地址也不生效，这是新手最常见的卡点，已写入步骤 3 与 FAQ。
3. **未说明提供商类型该选哪个**：原文截图里选的是 OpenAI，但正文完全没提；而同批的 MCP 篇选的是 Anthropic。两篇放在一起看会让人误以为随便选。已在 1.2 用表格说清两者差异与适用场景。
4. **地址行被 `***` 包裹**：原文是 `***API地址填写： …***`，在 Markdown 里 `***` 是加粗斜体标记，渲染后这一行格式错乱，域名可能被吃掉。
5. **未解释地址栏后缀提示**：截图灰字里的「/ 结尾忽略 v1 版本，# 结尾强制使用输入地址」是 Cherry Studio 的真实特性，原文一字未提，遇到路径重复时无从下手。已补 1.3 节。
6. **「检测」按钮的作用被高估**：原文未说明它只验连通性与密钥，不校验模型名。已注明，避免检测通过后仍失败时找不到方向。
7. **模型示例已过时**：`claude-3-5-sonnet-20241022`、`claude-3-7-sonnet-20250219`、`gemini-2.5-flash` 都是旧型号，照抄容易报模型不存在。已改为「以控制台列表为准」。  
   |  |  |  
   | --- | --- |
8. **截图之间提供商名不一致**：步骤 4 的配置页提供商叫「随便填写」，步骤 6 的聊天页顶部却显示 `| OpenAI`，说明两张图不是同一次配置截的。不影响操作，但看的时候容易以为配错，已在此说明。
9. **下载只给了官网首页**：未给直达下载页，已补 `https://docs.cherry-ai.com/cherry-studio/download`。

---

## 附录 B · 地址变更对照

| 位置              | 原地址                                    | 现地址                     |
| --------------- | -------------------------------------- | ----------------------- |
| 提供商配置页 → API 地址 | `https://api.zaimod.com`（原文被 `***` 包裹） | `https://api.zaimod.com` |
| 控制台入口（获取令牌）     | 原主站域名                                  | `https://api.zaimod.com` |

除域名外，提供商类型、路径拼接规则、参数均未改动。**旧平台令牌不能沿用**，需在新平台重新生成。

上一篇：Cherry Studio接入中转站调用MCP{else}上一篇：没有了下一篇：Dify 添加自定义模型（接入中转站）教程{else}下一篇：没有了