Cherry Studio 添加 API 服务商完整教程（2026最新版）

开头

Cherry Studio 是一款功能丰富的 AI 客户端，支持自定义 API 服务商。配置只需填写 API 地址和密钥，点击获取模型列表即可使用。本文基于 Cherry Studio 2026 年 8 月最新版本实测，给出从安装到首次对话的完整流程，整个配置过程约 5-10 分钟。

准备工作

开始配置前，你需要：

软件安装：

• Cherry Studio 客户端（从官网 cherry-ai.com 或 GitHub 下载）
• 支持的系统：Windows、macOS、Linux
• 版本要求：0.8 或更高版本

服务商信息：

• Base URL（API 地址，如 https://api.example.com/v1）
• API Key（密钥，通常是 sk- 开头的长字符串）
• Model ID（可选，Cherry Studio 通常可以自动获取模型列表）

预计时间：

• 首次配置：10 分钟
• 熟练后：3 分钟

预算：

• 测试成本：¥0.05-0.2（发送 2 次测试消息）
• 建议先充值小额（¥5-10）测试

安全提醒：

• 从官方渠道下载 Cherry Studio（官网或 GitHub Release）
• 不要使用第三方打包版本（可能被修改或植入后门）
• 为 Cherry Studio 单独创建一把密钥，设置合理额度

详细步骤

第 1 步：安装 Cherry Studio

操作：

1. 访问 Cherry Studio 官网：https://cherry-ai.com
   或 GitHub Release：https://github.com/kangfenmao/cherry-studio/releases
2. 选择对应的操作系统版本下载
   • Windows：.exe 安装包
   • macOS：.dmg 安装包
   • Linux：.AppImage 或 .deb
3. 下载并安装

验证：

• 双击启动 Cherry Studio
• 出现欢迎界面或主聊天窗口
• 界面语言可在设置中切换为中文

安全检查：

• 确认下载来源是官方域名或 GitHub
• Windows 可能提示 SmartScreen 警告，确认文件来源后点击"仍要运行"
• macOS 首次打开需在"系统偏好设置 → 安全性与隐私"中允许

第 2 步：获取服务商 API 信息

操作：

1. 登录你选择的 AI API 中转站
2. 找到"API 文档"或"开发者中心"页面
3. 复制以下信息：

Base URL（API 地址）：

• 通常格式：https://api.example.com/v1
• ⚠️ 注意是否包含 /v1 后缀（根据服务商文档确认）

API Key（密钥）：

• 如果没有密钥，点击"创建新密钥"
• 为 Cherry Studio 单独创建一把，便于管理和撤销
• 设置合理额度（如每日 ¥10，避免盗刷）
• 复制后立即保存到安全位置

实测案例（API Xuan）：

Base URL: https://api.apixuan.com/v1
API Key: sk-abc123...（从用户中心创建）

第 3 步：在 Cherry Studio 中添加模型服务

操作：

1. 打开 Cherry Studio
2. 点击右上角的"设置"图标（齿轮图标）
3. 在左侧菜单找到"模型服务"或"Model Providers"
4. 点击"添加服务商"或"+ Add Provider"

选择服务类型：

Cherry Studio 提供两种方式添加服务商：

方式 1：使用预设服务商（推荐）

• 如果你的服务商在列表中（如 OpenAI、Anthropic、OpenRouter）
• 直接选择对应的预设选项
• 只需填写 API Key

方式 2：添加自定义 OpenAI 兼容服务

• 如果服务商文档注明"兼容 OpenAI 接口"
• 选择"Custom OpenAI"或"自定义 OpenAI"
• 需要填写 API Key 和 Base URL

填写配置字段：

服务名称（可选）：

• 填写便于识别的名字，如"API Xuan"、"我的中转站"
• 仅用于自己识别，不影响功能

API 地址（Base URL）：

• 粘贴第 2 步复制的 Base URL
• 示例：https://api.apixuan.com/v1
• ⚠️ 确认没有多余空格

API 密钥（API Key）：

• 粘贴第 2 步复制的 API Key
• 示例：sk-abc123...
• ⚠️ 确认没有多余空格或换行符

保存配置：

• 点击"保存"或"Save"按钮
• Cherry Studio 会自动测试连接

第 4 步：获取模型列表

配置保存后，需要获取该服务商支持的模型列表。

操作：

1. 在刚添加的服务商卡片中，找到"获取模型"或"Fetch Models"按钮
2. 点击后，Cherry Studio 会自动从服务商获取可用模型列表
3. 等待 3-10 秒，模型列表应该显示在下方

验证标准：

✅ 成功标志：

• 显示模型列表，包含多个模型（如 claude-opus-5、gpt-4o 等）
• 每个模型有名称、价格、上下文长度等信息
• 状态显示为"已连接"或"Connected"

⚠️ 失败信号：

• 提示"无法连接"或"Connection failed"
• 模型列表为空
• 显示 401/404 错误

如果自动获取失败：

不要慌，自动获取失败不一定表示线路不可用。可以手动添加模型：

1. 点击"手动添加模型"或"Add Model Manually"
2. 输入 Model ID（从服务商文档获取）
3. 示例：claude-opus-5、gpt-4o、gpt-4o-mini
4. 保存后即可使用

第 5 步：启用模型并测试

获取模型列表后，需要启用模型才能使用。

操作：

1. 在模型列表中找到你要使用的模型（如 claude-opus-5）
2. 确认该模型的开关处于"开启"状态（通常是蓝色或绿色）
3. 如果是灰色，点击开关启用它

新建对话并选择模型：

1. 回到 Cherry Studio 主界面
2. 点击"新建对话"或"New Chat"
3. 在对话顶部的模型选择器中，选择刚配置的模型
4. 确认选择器显示的是正确的模型（如"Claude Opus 5 @ API Xuan"）

重要提醒： 很多"已经填好却不能用"的情况，是因为：

• 模型未启用（开关是灰色的）
• 对话中选中了另一个未配置的模型
• 旧对话中的配置没有更新

测试 1：纯文本连接测试

为了准确定位问题，先关闭所有附加功能，只测试纯文本：

操作：

1. 在设置中关闭以下功能（如果已开启）：
   • 联网搜索 / Web Search
   • 知识库 / Knowledge Base
   • 图片识别 / Vision
   • 工具调用 / Tool Use
2. 在新对话中发送简单消息：请回复：测试成功
3. 观察响应

验证标准： ✅ 成功标志：

• 1-5 秒内收到回复
• 回复内容包含"测试成功"
• 无错误提示

⚠️ 失败信号：

• 一直转圈无响应
• 返回 401/403/404 错误
• 提示"模型不可用"

测试 2：功能测试

操作： 发送一段约 300 字的文本，要求总结为 3 点：

请将以下内容总结为 3 点：
人工智能技术正在快速发展，影响着各个行业。从医疗诊断到金融分析，
AI 都在提升效率和准确性。未来，AI 将与人类更深入地协作，
解决更复杂的问题。同时，我们也需要关注 AI 的伦理和安全问题，
确保技术发展造福全人类。

验证标准： ✅ 成功标志：

• 准确总结为 3 点
• 中文回复正常，无乱码
• 输出格式清晰（如使用数字列表）

第 6 步：验证账单与上下文

操作：

1. 回到服务商控制台
2. 找到"用量记录"或"账单明细"
3. 查看最近 2 次请求的记录

验证清单：

• 有 2 条调用记录（对应 2 次测试）
• 模型名称与配置一致（如 claude-opus-5）
• Token 消耗合理
  • 测试 1：约 10-20 tokens
  • 测试 2：约 150-250 tokens
• 扣费金额准确（可手动计算验证）

手动计算示例（Claude Opus 5，2026-08-14 价格）：

测试 2：
输入：150 tokens × ¥108/M = ¥0.016
输出：80 tokens × ¥540/M = ¥0.043
总成本：¥0.059

实际扣费：¥0.06（四舍五入）✅

测试上下文连续性：

1. 在同一对话中继续发送：刚才我让你总结了什么内容？
2. 验证 AI 能否正确引用之前的对话
3. 如果无法引用，可能是上下文功能未启用或服务商不支持

第 7 步：逐步开启附加功能

纯文本测试成功后，可以逐步开启附加功能。

操作：

功能 1：联网搜索

• 在设置中开启"联网搜索"
• 发送测试消息：今天的日期是多少？
• 验证是否能获取实时信息

功能 2：图片识别（需要支持 Vision 的模型）

• 选择支持图片的模型（如 gpt-4o、claude-opus-5）
• 上传一张图片
• 发送：描述这张图片的内容
• 验证是否能正确识别

功能 3：知识库（如果使用）

• 上传文档到知识库
• 发送与文档相关的问题
• 验证是否能引用文档内容

逐步开启的好处：

• 出错时容易定位是哪个功能导致的
• 避免多个功能同时开启导致混乱
• 可以分别测试每个功能的稳定性和成本

结果验证

配置成功的标准：

✅ 完整验证清单：

• 服务商已添加并显示"已连接"状态
• 模型列表已获取（自动或手动）
• 至少一个模型已启用
• 纯文本测试成功（收到正确回复）
• 账单有记录且扣费准确
• 上下文连续性正常（能引用之前的对话）
• 附加功能按需开启并测试成功

✅ 可以开始使用的信号：

• 连续 3 次请求都成功
• 响应速度满足需求（通常 < 5 秒首字）
• 账单透明且扣费准确

⚠️ 需要继续调试的信号：

• 偶尔超时（检查网络和服务商稳定性）
• 账单扣费异常（检查模型映射是否正确）
• 某些功能不可用（确认服务商是否支持）

常见错误

错误 1：401 Unauthorized（鉴权失败）

症状：

Error: 401 Unauthorized
Invalid API Key

原因：

• API Key 复制不完整
• API Key 包含多余空格
• API Key 已过期或被撤销

解决方法：

1. 回到服务商控制台，重新创建新的 API Key
2. 复制时确保完整选中（通常是 sk- 开头）
3. 粘贴后检查是否有多余空格
4. 在 Cherry Studio 中更新密钥并保存
5. 重新点击"获取模型"测试

错误 2：404 Not Found（资源未找到）

症状：

Error: 404 Not Found
Endpoint not found

原因：

• Base URL 填写错误
• 缺少 /v1 后缀或多了其他路径

解决方法：

1. 核对服务商文档，确认 Base URL 格式
   • 正确：https://api.example.com/v1
   • 错误：https://api.example.com 或 https://example.com
2. 在 Cherry Studio 中更新 Base URL
3. 保存并重新测试

错误 3：模型列表为空

症状：

• 点击"获取模型"后，列表为空
• 或提示"No models found"

原因：

• Base URL 或 API Key 配置错误
• 服务商不支持自动获取模型列表
• 网络问题

解决方法：

1. 检查 Base URL 和 API Key 是否正确
2. 尝试手动添加模型：
   • 点击"手动添加模型"
   • 输入 Model ID（如 claude-opus-5）
   • 保存
3. 如果手动添加后能正常使用，说明服务商不支持自动获取，但功能正常

错误 4：模型已添加但无法使用

症状：

• 模型在列表中，但发送消息无响应
• 或提示"模型不可用"

原因：

• 模型未启用（开关是灰色的）
• 对话中选中了其他模型
• 旧对话的配置未更新

解决方法：

1. 检查模型的开关是否处于"开启"状态（蓝色或绿色）
2. 新建对话，重新选择模型
3. 确认对话顶部的模型选择器显示的是正确的模型
4. 如果仍无法使用，尝试删除并重新添加该模型

错误 5：连接成功但扣费异常

症状：

• 能正常收到回复
• 但账单扣费远超预期

原因：

• 服务商将 Model ID 映射到了更贵的模型
• Cherry Studio 的上下文设置过长
• 附加功能（如联网搜索）产生额外费用

解决方法：

1. 在服务商控制台查看用量明细，确认实际使用的模型
2. 检查 Cherry Studio 的"最大上下文长度"设置，降低到合理值
3. 关闭不必要的附加功能（如联网搜索、知识库）
4. 手动计算应扣费用，与实际对比
5. 如果差异 > 10%，联系服务商客服

错误 6：附加功能无法使用

症状：

• 开启"联网搜索"后无效果
• 上传图片后无法识别
• 工具调用功能报错

原因：

• 服务商不支持该功能
• 当前模型不支持该功能
• 功能配置不正确

解决方法：

1. 确认服务商是否支持该功能（查看文档或咨询客服）
2. 确认当前模型是否支持：
   • 图片识别：需要 Vision 模型（如 gpt-4o、claude-opus-5）
   • 工具调用：需要支持 Function Calling 的模型
3. 检查功能配置是否正确（如联网搜索的 API Key）
4. 先关闭该功能，使用纯文本模式

费用说明

配置成本：

• Cherry Studio 软件：免费（开源）
• 测试消息（2 次）：¥0.05-0.2
• 建议首次充值：¥5-10

日常使用成本（基于 Claude Opus 5）：

• 简单问答（50 字）：¥0.03-0.05/次
• 文章总结（300 字）：¥0.20-0.40/次
• 长对话（10 轮）：¥2-5/次
• 附加功能（联网搜索、图片识别）：额外 ¥0.05-0.30/次

优化成本建议：

• 使用更便宜的模型处理简单任务（如 Claude Sonnet、GPT-4o-mini）
• 完成一个主题后新建对话，避免上下文过长
• 按需开启附加功能，不用时关闭
• 定期检查账单，及时发现异常

安全提醒

1. 软件来源安全：

   • 只从官网或 GitHub Release 下载
   • 不要使用第三方打包版本（可能被植入后门）
   • 定期检查更新，修复安全漏洞

2. API Key 安全：

   • 为每个客户端创建独立的 API Key
   • 设置合理额度（如每日 ¥10）
   • 定期检查用量，及时发现盗刷
   • 旧设备不用时，立即撤销对应的 API Key

3. 数据备份与迁移：

   • Cherry Studio 支持导出配置和对话
   • 导出前检查是否包含 API Key
   • 如果要分享配置，只分享 Base URL 和模型名称
   • 不要分享包含 API Key 的配置文件

4. 隐私保护：

   • 不要在对话中输入敏感信息（密码、身份证号、银行卡号）
   • 了解服务商的隐私政策（是否记录对话内容）
   • 真正敏感的任务建议使用官方 API

5. 定期维护：

   • 每 1-3 个月检查一次配置
   • 更新 Cherry Studio 到最新版本
   • 复查服务商的价格和服务条款
   • 备份重要对话到本地

---

测试日期: 2026-08-14
测试软件: Cherry Studio 最新版本
测试平台: API Xuan
测试模型: Claude Opus 5

相关阅读：

• Chatbox 配置自定义 AI API：从填地址到测试模型
• 不会编程也能用 AI API：用客户端完成第一次对话
• AI API 连接失败怎么办？新手通用排查顺序
• 如何选择 AI API 中转站？7 个关键指标检查表