Cherry Studio 怎么配置 API？自定义模型接入与多模型切换完整教程

摘要

Cherry Studio 是一款开源免费的桌面 AI 客户端（GitHub 42k+ Stars），支持 Windows、macOS、Linux 三平台。通过配置自定义 API，你可以在一个界面里同时使用 GPT-5.4、Claude Opus 4.6、Gemini 3.1 Pro、DeepSeek 等 50+ 大模型，不再需要在多个网页之间切换。本文从零开始，手把手教你完成 Cherry Studio 的 API 配置，包括 Base URL 设置、自定义服务商添加、多 Key 轮询，以及常见报错的排查方法。

为什么用 Cherry Studio 而不是 ChatGPT 官方客户端

在选择 AI 桌面客户端时，很多开发者面临一个选择：用 ChatGPT 官方客户端，还是用第三方客户端？

Cherry Studio 的核心优势是模型自由——通过配置 API，你可以接入任意兼容 OpenAI 协议的服务，在一个窗口里按需切换不同模型。

安装 Cherry Studio

Cherry Studio 支持三个平台，下载安装即可使用，不需要配置开发环境：

• macOS：从 GitHub Releases 下载 .dmg 文件
• Windows：下载 .exe 安装包
• Linux：提供 .AppImage 和 .deb 格式

安装完成后打开应用，界面左侧是导航栏，点击齿轮图标进入设置页面。

配置 API：三种方式

方式一：内置服务商（最简单）

Cherry Studio 内置了主流 AI 服务商的配置，只需填入 API Key：

1. 打开 设置 → 模型服务
2. 在左侧服务商列表中找到你要用的供应商（OpenAI、Anthropic、Google 等）
3. 填入对应的 API Key
4. 点击 Check 按钮验证连通性
5. 确保右上角的启用开关已打开

适合已经有各家官方 API Key 的用户。缺点是需要分别管理多个供应商的 Key 和额度。

方式二：自定义服务商 + API 聚合平台（最推荐）

如果你想用一个 Key 调用所有模型，或者在国内需要低延迟访问 GPT/Claude/Gemini，推荐通过 API 聚合平台接入。

第一步：获取 API Key

在 Ofox 注册账号，进入控制台创建 API Key。一个 Key 即可调用 GPT-5.4、Claude Opus 4.6、Gemini 3.1 Pro 等 100+ 模型。

第二步：添加自定义服务商

1. 打开 设置 → 模型服务
2. 点击服务商列表底部的 「+ 添加」 按钮
3. 在弹窗中填写：
   • 服务商名称：填一个你好识别的名字，比如 Ofox 聚合
   • 服务商类型：选择 OpenAI

第三步：配置 API 地址（Base URL）

这是最关键的一步。API 地址的填写规则：

# ✅ 正确写法：只填根地址
https://api.ofox.ai

# ❌ 错误写法：不要加路径
https://api.ofox.ai/v1/chat/completions

Cherry Studio 会自动在根地址后拼接 /v1/chat/completions，所以你只需要填根域名部分。

特殊情况：如果你的 API 服务路径不是标准的 /v1/chat/completions，在 URL 末尾加 # 号。比如 https://api.example.com/custom/path#，这样 Cherry Studio 就不会自动拼接路径。

第四步：填入 API Key

在 API Key 输入框中粘贴你的 Key。如果有多个 Key，用英文逗号分隔：

sk-key1,sk-key2,sk-key3

Cherry Studio 会自动按顺序轮询这些 Key，实现负载均衡。

第五步：添加模型

点击 「+ 添加」 按钮，手动输入你要使用的模型 ID：

具体的模型 ID 以你使用的 API 平台文档为准。在 Ofox 模型列表 可以查看所有可用模型和对应 ID。

第六步：验证并启用

1. 点击 API Key 旁边的 Check 按钮测试连通性
2. 确保右上角的启用开关已打开（这一步很容易忘）
3. 回到对话界面，在模型选择器中就能看到刚添加的模型了

方式三：接入本地模型（Ollama）

如果你在本地部署了模型，Cherry Studio 也能直接接入：

1. 确保 Ollama 已在本地运行（默认端口 11434）
2. 在服务商列表中找到 Ollama
3. API 地址填 http://localhost:11434
4. 点击 管理 按钮，Cherry Studio 会自动检测已加载的模型

本地模型适合对数据隐私要求极高、或者不需要联网的场景。

多模型切换实战

配置好多个模型后，Cherry Studio 的多模型能力就体现出来了。

场景一：同一问题多模型对比

在对话界面，你可以选择多个模型同时回答同一个问题。比如让 GPT-4.1 和 Claude Opus 4.6 同时回答一个代码问题，对比两者的思路差异。

场景二：按任务选模型

实际使用中，不同任务适合不同模型：

• 写代码：Claude Opus 4.6 或 Claude Sonnet 4.6（推理能力强，代码质量高）
• 分析长文档：Gemini 3.1 Pro（100 万 token 上下文窗口）
• 日常快速问答：GPT-4.1-mini 或 Gemini 3.1 Flash-Lite（速度快、成本低）
• 中文内容创作：DeepSeek V4（中文理解和表达能力优秀）
• 数据分析：GPT-4.1（工具调用能力强）

Cherry Studio 让你在一个窗口内按需切换，不用登录多个网站。

场景三：300+ 预设助手

Cherry Studio 内置了 300 多个预设 AI 助手角色，覆盖翻译、写作、编程、分析等场景。每个助手可以指定使用不同的模型，实现「对的模型做对的事」。

常见问题排查

问题 1：Check 按钮显示连接失败

排查步骤：

1. 检查 API Key 是否正确——复制时是否多了空格或换行
2. 确认 Base URL 只填了根地址，没有多余路径
3. 确认网络可以访问该 API 地址（在浏览器中试试能不能打开）
4. 如果用的是自定义路径的 API，确认 URL 末尾加了 #

问题 2：模型列表为空

自定义服务商不会自动拉取模型列表，需要你手动添加模型 ID。点击「+ 添加」按钮，输入准确的模型 ID。

注意：点击「管理」按钮时，弹出的模型列表不会自动全选添加，你需要手动点击每个模型旁边的 + 按钮。

问题 3：服务商配置好了但对话界面看不到

最常见的原因是忘记打开启用开关。回到设置 → 模型服务，确认服务商右上角的 toggle 开关是打开状态。

问题 4：返回 401 错误

API Key 无效或过期。检查：

• Key 是否正确复制
• Key 是否还在有效期内
• 如果用多 Key 轮询，确认所有 Key 都有效，无效的 Key 会导致部分请求失败

问题 5：返回 429 错误（请求太频繁）

API 供应商的速率限制。解决方案：

• 配置多个 API Key 做轮询，分摊请求压力
• 降低发送频率
• 联系 API 供应商提升配额

进阶技巧

多 Key 轮询实现高可用

如果你的使用量比较大，可以准备多个 API Key 配置轮询：

sk-primary-key,sk-backup-key-1,sk-backup-key-2

Cherry Studio 按顺序轮询，当某个 Key 的配额用完或出错时，自动切换到下一个。这在团队共用时特别实用。

搭配知识库使用

Cherry Studio 内置了知识库功能，你可以上传 PDF、Word、文本文件，让 AI 基于你的文档回答问题。搭配不同模型使用效果各异：

• 用 Gemini 3.1 Pro 处理超长文档（100 万 token 上下文）
• 用 Claude Opus 4.6 做深度分析和推理
• 用 GPT-4.1-mini 做快速检索问答

数据安全

Cherry Studio 的所有使用数据都存储在本地，不会上传到任何第三方服务器。API 请求直接从你的电脑发送到 API 服务端，Cherry Studio 本身不做任何数据中转。

总结

Cherry Studio 是目前最好用的开源 AI 桌面客户端之一，配置自定义 API 后可以变成真正的「全模型客户端」：

1. Base URL 只填根地址，系统自动拼路径；特殊路径加 #
2. 多 Key 用英文逗号分隔，自动轮询实现负载均衡
3. 模型需要手动添加 ID，不会自动拉取
4. 别忘了打开启用开关，这是最常见的配置遗漏

用 API 聚合平台（如 Ofox）配合 Cherry Studio，一个 Key 就能在桌面端自由切换 GPT、Claude、Gemini、DeepSeek 等 50+ 大模型，告别在多个网页之间反复横跳。