Cherry Studio 接入 OpenAI 兼容 API：从安装到排错的完整教程¶

最后核验：2026-07-14

适用范围：Windows、macOS、Linux；Cherry Studio 当前稳定版

预计用时：首次配置约 5～10 分钟

← 返回教程目录

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看教程配套 API。

1. Cherry Studio 适合谁¶

Cherry Studio 是一款跨平台 AI 桌面客户端。它把多个模型服务集中在一个界面中，适合不想反复打开网页、希望统一管理模型和对话的人。

这篇教程使用“自定义 OpenAI 服务商”接入 OpenAI 兼容 API。配置完成后，你可以在 Cherry Studio 中切换服务商提供的不同模型。

2. 开始前准备¶

你需要：

一台 Windows、macOS 或 Linux 电脑；
一个有效的 API Key；
服务商提供的 Base URL；
至少一个准确的模型 ID。

如果还没有 Key，可以在纽智中转站注册后，在控制台创建 API Key，并从模型列表复制模型 ID。

重要： 模型“显示名称”和“模型 ID”可能不同。配置时必须复制接口文档或模型列表中的模型 ID，不要凭名称猜。

3. 下载和安装¶

打开 Cherry Studio 官方 GitHub Releases。
根据系统下载对应安装包：
Windows：通常选择 .exe 安装包；
macOS Apple 芯片：选择 arm64 版本；
macOS Intel 芯片：选择 x64 版本；
Linux：根据发行版选择 AppImage、deb 或 rpm。
安装并启动 Cherry Studio。

macOS 如果提示“无法验证开发者”，先确认文件来自官方发布页，再到“系统设置 → 隐私与安全性”中允许打开。

4. 创建自定义服务商¶

点击左侧边栏底部的“设置”齿轮。
进入“模型服务”。
点击服务商列表底部的“添加”。
填写：
服务商名称：自定义一个容易辨认的名字，例如 我的 API；
服务商类型：选择 OpenAI。
点击“添加”。

选择 OpenAI 表示使用 OpenAI 兼容协议，并不代表只能调用 OpenAI 品牌模型。能调用哪些模型取决于服务商的接口兼容性和你的 Key 权限。

5. 填写 API Key 和 Base URL¶

在刚创建的服务商中填写：

配置项	应填写的内容
API 密钥	控制台创建的完整 Key
API 地址	服务商文档给出的 Base URL
模型	从模型列表复制的模型 ID

Base URL 是否以 /v1 结尾，必须以服务商给出的接入说明为准。不要自行重复添加路径。

常见错误示例：

错误：https://接口地址/v1/v1
错误：https://接口地址/v1/chat/completions
正确：https://接口地址/v1    # 仅示意，以服务商文档为准

Cherry Studio 的 API 地址通常填写 Base URL，不应直接填完整的 /chat/completions 请求地址。

6. 添加模型¶

找到“模型管理”区域。
如果客户端能自动拉取模型，先点击刷新或管理按钮。
如果没有自动出现，点击“添加模型”。
将控制台模型列表中的模型 ID 原样粘贴进去。
保存并打开服务商右侧的启用开关。

建议首次只添加 1～3 个确定可用的模型。模型过多会让选择列表变得混乱，也更难判断是 Key、线路还是单个模型的问题。

7. 检查连接并完成首次对话¶

点击 API Key 旁边的“检查”。
检查通过后回到对话首页。
新建一个助手或新对话。
在模型选择器中选择刚添加的服务商和模型。
发送以下测试内容：

只回复“连接成功”，不要补充其他内容。

能正常流式输出，说明 Key、地址、模型和基础聊天协议均已配置成功。

8. 推荐的基础设置¶

上下文长度¶

上下文越长，后续每轮对话携带的历史内容越多，费用也可能越高。日常问答可以先使用默认值；长文分析或代码任务再按需增加。

温度¶

代码、翻译、事实问答：建议较低温度，例如 0～0.4；
创意写作、头脑风暴：可以提高到 0.7 左右；
如果模型不支持温度参数，保持默认，不要强行填写。

自动标题和翻译¶

自动生成标题、消息翻译等功能也可能调用模型并产生用量。希望控制成本时，先关闭不需要的自动功能。

9. 常见问题排查¶

401 Unauthorized / Invalid API Key¶

按顺序检查：

Key 是否复制完整，首尾是否带空格或换行；
Key 是否已被删除、禁用或过期；
是否误把登录密码、兑换码填成 API Key；
当前服务商是否确实绑定了这把 Key。

403 Forbidden / Permission denied¶

通常表示 Key 没有当前模型的使用权限。回到模型列表确认该 Key 所属分组可调用哪些模型，然后改用同分组模型。

404 Not Found¶

优先检查 Base URL：

是否漏了 /v1；
是否出现重复的 /v1/v1；
是否误填了控制台网页地址；
是否把完整的 /chat/completions 填进了 Base URL。

模型不存在 / Model not found¶

模型 ID 必须区分大小写并完全一致。不要填写营销名称、中文名称或自行缩写。

检查通过，但发送消息失败¶

“检查”有时只验证 Key 或模型列表接口。继续检查：

所选模型是否支持聊天协议；
Key 余额或免费额度是否可用；
当前对话是否携带了模型不支持的图片、工具或超长上下文；
新建一个空白对话，只发送纯文本重试。

一直转圈或连接超时¶

新建对话并发送一句短文本；
切换到另一个可用模型；
暂时关闭联网搜索、MCP、知识库等额外功能；
检查系统时间是否准确；
更新到最新稳定版后重试。

10. 安全与隐私¶

不要把 API Key 发到群聊、Issue、截图或录屏中；
不要把包含 Key 的配置文件提交到 GitHub；
一人一把 Key，泄露后立即删除并重新创建；
处理公司代码、客户资料或个人隐私前，先确认所用服务的隐私政策；
公共电脑使用完毕后删除 Key，并清理本地对话数据。

11. 卸载前备份¶

如果需要重装客户端，先在设置中导出数据。导出文件可能包含对话内容和配置信息，应像备份文件一样妥善保管，不要公开上传。

12. 官方资料¶

配置仍然失败时，提问请同时提供：操作系统、Cherry Studio 版本、错误状态码、Base URL 是否带 /v1、模型 ID。请先遮住完整 API Key。