Cherry Studio 接入指南

概述#

Cherry Studio 是支持 Windows、macOS 和 Linux 的多模型桌面客户端。通过它的自定义 OpenAI 提供商，可以使用 APIMAX 账号下支持 Chat Completions 协议的文本与多模态模型。

使用前准备#

1. 从 Cherry Studio 官网 下载并安装最新版客户端。
2. 登录 APIMAX 控制台，在 API Keys 创建一个 Key。
3. 在模型页面确认计划使用的模型 ID。

添加 APIMAX 提供商#

1. 打开 Cherry Studio，进入 设置 → 模型服务（部分版本显示为“模型提供商”）。
2. 点击 添加，选择 OpenAI 或 OpenAI 兼容。
3. 按下表填写：

API Host 建议保留结尾的 /。客户端会在该地址后拼接 models、chat/completions 等路径。

添加模型#

保存提供商后，打开模型管理：

1. 点击 获取模型、管理 或 刷新模型列表。
2. 从返回列表中勾选需要的模型。
3. 如果客户端版本无法自动获取，可以点击手工添加，并填写 APIMAX 模型页显示的完整模型 ID。
4. 建议先添加一个常用对话模型完成连通性验证，再逐步添加视觉或推理模型。

不要根据其他平台文档猜测模型名。模型 ID 不正确通常会返回 model_not_found 或无可用渠道。

开始对话#

1. 返回聊天页并创建新会话。
2. 在模型选择器中选择 APIMAX 下的模型。
3. 输入“只回复：连接成功”。
4. 收到回复后，到 APIMAX 控制台的用量日志确认请求记录。

对于图片理解、文件解析、工具调用等能力，是否可用取决于所选模型和 Cherry Studio 当前版本。基础文本对话成功不代表每个扩展能力都受支持。

常见问题#

无法获取模型列表#

• 确认 API Host 为 https://api.apimax.ai/v1/，不要填到 /chat/completions。
• 检查 API Key 是否完整、有效。
• 尝试手工添加控制台中显示的模型 ID。

401 Unauthorized#

• Key 前后可能包含空格或换行，重新复制。
• Key 已被删除或禁用时，需要创建新 Key。

404 Not Found#

• 通常是 API Host 路径错误。Cherry Studio 的 OpenAI 兼容配置应填 https://api.apimax.ai/v1/。
• 不要额外填写完整的 /v1/chat/completions 请求地址。

对话报参数错误#

• 某些推理模型不接受自定义 temperature、top_p 或传统 max_tokens 参数。
• 先关闭高级采样参数再测试，或切换到普通对话模型。

主入口无法连接#

先排查本机网络、代理和 DNS。如果确认是入口故障，可把 API Host 临时改为控制台公布的备用入口，并保持相同的 /v1/ 路径。

安全建议#

• Cherry Studio 配置保存在本机，仍应为该客户端单独创建 Key。
• 导出客户端配置前检查是否包含明文 API Key。
• 不要在会话中粘贴密码、私钥或生产环境密钥。