Cherry Studio

Cherry Studio 是支持 Windows、macOS 和 Linux 的多模型桌面客户端。通过添加自定义 OpenAI 服务商，可以让 Cherry Studio 使用 AGTCloud 的 Chat Completions 兼容入口。

本教程只介绍普通聊天接入。文件、图片、工具调用、推理、知识库、Agent、MCP 和其他高级能力取决于 Cherry Studio 版本及目标模型的实际支持范围。

准备工作

开始前，请确认你已经：

准备好受支持的 Windows、macOS 或 Linux 设备；
注册并登录 AGTCloud；
在 API Keys 页面创建 AGTCloud API Key；
从模型广场复制当前 API Key 可见且支持 Chat Completions 的模型 ID。

下载并安装 Cherry Studio

从 Cherry Studio 官方下载页获取安装包。下载页和安装包名称可能随版本更新，请根据操作系统与处理器架构选择当前版本。

常见的 Intel 或 AMD 电脑选择 Windows x64 常规安装版；
Windows ARM 设备选择 ARM64 安装包；
下载完成后运行安装程序，并按照界面提示完成安装。

不确定设备架构时，可以在 设置 → 系统 → 系统信息 中查看“系统类型”。

安装完成后启动 Cherry Studio。如果首次启动出现初始化、数据目录或更新提示，请按当前版本界面完成设置。

添加 AGTCloud 服务商

打开模型服务设置

打开 Cherry Studio，进入 Settings → Model Provider。中文界面中的名称可能显示为“设置 → 模型服务”。

添加自定义服务商

点击服务商列表中的 Add 或“添加”，新建一个自定义服务商。Provider Name 填写 AGTCloud，Provider Type 选择 OpenAI。

填写连接信息

Cherry Studio 字段	填写内容
`Provider Name`	`AGTCloud`
`Provider Type`	`OpenAI`
`Chat Endpoint / Protocol`（如有）	`OpenAI Chat Completions`
`API Key`	`your-api-key`
`API Host`	`https://api.agtcloud.cn/v1/`
`Custom Headers`	默认留空

将 your-api-key 替换为在 API Keys 页面创建的 AGTCloud API Key。若当前版本提供聊天协议选择，请使用 OpenAI Chat Completions。

启用服务商

保存配置后，打开服务商右上角的启用开关。服务商未启用时，已经添加的模型也不会出现在聊天页面的模型列表中。

API Host 需要以 / 结尾

请填写 https://api.agtcloud.cn/v1/。不要填写完整的 /v1/chat/completions 请求地址，否则 Cherry Studio 再次拼接路径时可能产生重复 Endpoint。

获取并添加模型

打开模型管理

在 AGTCloud 服务商配置页点击 Manage。Cherry Studio 会尝试根据当前 API Host 和 API Key 获取可见模型。

将模型加入列表

在返回的模型列表中找到支持 Chat Completions 的模型，点击右侧的 +。只有加入服务商模型列表的模型，才会出现在聊天页面的模型选择器中。

无法加载时手动添加

如果模型列表没有正常加载，请先检查 API Host、API Key 和服务商启用状态。也可以从模型广场复制模型 ID，然后使用 Cherry Studio 当前版本提供的手动添加入口填写 MODEL_ID。

检查连接

点击 API Key 输入框附近的连通性检查按钮。Cherry Studio 通常会使用已添加列表中的最后一个聊天模型进行检查；如果检查失败，请先确认列表中至少存在一个当前 API Key 可以调用的聊天模型。

模型配置以实际能力为准

不需要一次添加全部模型。模型的上下文长度、文件输入、图像理解、工具调用和推理能力，以当前模型和协议入口的实际支持范围为准。

请用三句话介绍你自己。

检查结果

如果客户端能够正常接收回复，说明 API Host、API Key 和模型的基础连接已经建立。本步会产生正常的 API 用量。

常见问题

现象	优先检查	处理方式
AGTCloud 模型未显示	服务商开关和模型添加状态	启用服务商，并确认目标模型已经加入服务商模型列表
`Manage` 返回空列表	API Host、API Key、当前账户模型范围	重新填写 API Host 和 API Key，或从模型广场复制 `MODEL_ID` 后手动添加
连通性检查失败	已添加模型、模型协议和 Key 权限	确保列表中最后一个聊天模型可由当前 Key 通过 Chat Completions 调用
返回 `401`	API Key 内容和令牌状态	重新复制有效 API Key，并确认填写内容没有多余空格
返回 `403`	令牌权限、模型权限和账户状态	在控制台检查 API Key 状态及当前账户的模型可用范围
返回 `404`	API Host、重复路径和模型 ID	使用 `https://api.agtcloud.cn/v1/`，不要填写完整 Endpoint，并重新核对模型 ID
请求路径重复	API Host 填写了完整请求地址	恢复为以 `/` 结尾的 `https://api.agtcloud.cn/v1/`，再重新检查连接
高级功能调用失败	模型真实能力、协议支持和客户端版本	先关闭文件、工具、知识库或推理等高级功能，再使用普通文本完成验证
回复中断或缓慢	网络代理、上下文长度和模型状态	使用较短的新话题重试，并检查本地网络与当前模型运行状态

遇到无法定位的问题时，请记录请求时间、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key。

安全建议

不要把 API Key 放入截图、聊天导出、日志或共享配置；
不要在首次验证中提交密码、客户资料、私有文件或其他敏感内容；
多人共用设备时，使用完毕后删除 Cherry Studio 中保存的凭证；
导出或分享 Cherry Studio 配置前，先确认其中不包含 API Key。