前言

这篇文章就是我自己的 Cherry Studio 记录：Windows 安装 + 接入自建 API，以及常见踩坑排查方式。
（本文示例 API：https://api.baiyiai.online/；Key 形如 sk-xxxx。）

Cherry Studio 是一款跨平台桌面 AI 客户端（Windows / macOS / Linux）。通过配置 OpenAI-compatible 网关，可以在同一套界面中切换不同厂商/系列的模型，实现桌面端统一入口。

本文记录 Windows 环境下的安装与配置流程，示例 API 如下：

• Base URL：https://api.baiyiai.online/
• API Key：sk-xxxx
• 模型示例：gemini-3.1-pro-preview、claude-opus-4-6、gpt-5.2-chat

---

1. Cherry Studio 简介

Cherry Studio 的定位更偏“桌面工作台”而不仅是聊天框，常见能力包括：

• 多提供方与本地模型接入（例如 Ollama、LM Studio 等）
• 支持填写 OpenAI 的 API Key 与自定义 API Address（适合接入自建 OpenAI-compatible 服务）
• 多模型对话、助手/角色、文档处理、搜索、备份等（具体能力随版本与插件而变化）

---

2. 安装（Windows）

2.1 下载

建议从官方仓库/官方发布页获取 Windows 安装包（通常为 .exe 或 .msi），避免第三方打包带来的安全风险。

2.2 安装

按安装向导完成安装后启动 Cherry Studio。

---

3. 核心目标：接入自建 API（OpenAI-compatible）

自建网关常见参数形态：

• Base URL：https://<domain>/v1（或不带 /v1，取决于网关实现与客户端拼接方式）
• API Key：sk-xxxx
• 模型：必须使“具体 model id”（字符串），而不是“厂商名/系列名”

示例 model id：

• gpt-5.2-chat
• claude-opus-4-6
• gemini-3.1-pro-preview

---

4. Cherry Studio 配置步骤（推荐流程）

4.1 打开 Provider 设置

进入：

Settings（设置） → Providers（提供方） → OpenAI

（不同版本菜单名称可能略有差异，通常位于“设置 → 模型/提供方”。）

4.2 填写关键字段

• API Key：填 sk-xxxx
• API Address / Base URL：填 https://api.baiyiai.online/
• Model（模型）：填一个确认存在的 model id，例如 gpt-5.2-chat

保存后新建对话，选择对应模型发送一条最简单的测试消息（例如“回复 ok”）用于验证连通性。

---

5. 模型名（model id）填写要点

Cherry Studio 依赖模型标识符（model id）完成调用。常见误区是将 “gemini / claude / chatgpt” 等厂商/系列名当作模型名填写，导致 “model not found / invalid model”。

应填写网关侧暴露的实际 model id，例如：

• gemini-3.1-pro-preview
• claude-opus-4-6
• gpt-5.2-chat

---

6. 最快排错：先用命令行验证接口

为了区分“客户端配置问题”与“网关侧问题”，建议先在 Windows PowerShell 中发起最小请求。

6.1 测试 Chat Completions

将 key 与模型名替换为实际值：

curl.exe https://api.baiyiai.online/chat/completions `
  -H "Authorization: Bearer sk-xxxx" `
  -H "Content-Type: application/json" `
  -d "{\"model\":\"gpt-5.2-chat\",\"messages\":[{\"role\":\"user\",\"content\":\"回复ok\"}]}"

常见返回含义：

• 成功返回 JSON 且包含回复内容：接口、鉴权、模型名大概率无误
• 401/403：API Key 无效、权限不足或鉴权格式不匹配（例如不是 Bearer）
• model not found / invalid model：model id 不存在或未授权
• 404：请求路径不匹配（通常与 Base URL 是否应包含 /v1 有关）

6.2 （可选）测试 Models 列表

如果网关实现了模型列表接口：

curl.exe https://api.baiyiai.online/models `
  -H "Authorization: Bearer sk-xxxx"

返回中的 data[].id 通常就是可直接用于 Cherry Studio 的 model id（复制粘贴最稳）。

---

7. 常见坑：Base URL 是否需要包含 /v1

示例 Base URL 使用：

• https://api.baiyiai.online

但部分客户端会自动拼接 /v1，导致路径变成：

• /v1/chat/completions

出现 404 时，可依次尝试以下 Base URL 变体（每次只改一处便于定位）：

1. https://api.baiyiai.online（不带 /v1）
2. https://api.baiyiai.online/v1（带 /v1）
3. https://api.baiyiai.online/v1/（末尾带斜杠）

---

8. 默认模型选择（示例策略）

先跑通再扩展，可设置一个通用对话模型为默认：

• 默认：gpt-5.2-chat
• 长文/写作/深度分析：claude-opus-4-6
• 需要 Gemini 特性的任务：gemini-3.1-pro-preview

---

9. 配置清单（模板）

• 客户端：Cherry Studio（Windows）
• Provider：OpenAI（OpenAI-compatible 网关）
• API Key：sk-xxxx
• API Address / Base URL：https://api.baiyiai.online/
• 可用模型示例：
  • gpt-5.2-chat
  • claude-opus-4-6
  • gemini-3.1-pro-preview

---

10. 结语

Cherry Studio 适合作为桌面端统一入口，通过 OpenAI-compatible 网关将多家模型纳入同一套配置体系。实践中建议先用 curl 验证通路，再回到 Cherry Studio 完成 Provider 配置，可显著降低排错成本。