Cherry Studio 接入指南

在 Cherry Studio 中配置 TokenPlus 的 OpenAI 兼容接口，添加模型并验证对话。

本指南介绍如何在 Cherry Studio 中添加 TokenPlus 作为自定义服务商，通过 API 密钥使用 TokenPlus 平台的模型。

准备工作

打开 Cherry Studio 官网，下载适合您操作系统的安装包。Windows 用户运行安装程序，macOS 用户打开安装包并将应用拖入「应用程序」，Linux 用户按所选安装包格式完成安装。
按照 TokenPlus 快速入门完成注册、实名认证和充值，确保账户有可用余额。
准备所属项目的 TokenPlus API 密钥。

本文以 Cherry Studio 桌面端的首次配置流程为例，不同版本的界面可能略有差异。

获取 TokenPlus API 密钥

创建成功后，复制完整密钥，稍后填入 Cherry Studio。

完整密钥只在创建成功时显示一次，请妥善保存。不要将密钥放入公开仓库、聊天记录或截图；本文配置截图中的密钥已隐藏。

添加服务商

1. 打开服务商配置

首次打开 Cherry Studio，阅读并同意隐私协议后，点击「配置其他服务商」。

在「选择服务商」页面，点击左下角「添加服务商」。如果已经完成首次设置，可从主界面左下角「设置」进入服务商配置页面。

2. 填写 API 配置

在「添加自定义提供商」弹窗中填写以下信息：

配置项	填写内容
提供商名称	`TokenPlus`，或便于识别的自定义名称（截图中为 `tokenplus`）
API 密钥	在 TokenPlus 项目空间创建的完整 API 密钥
端点类型	`OpenAI`
端点地址（API Base URL）	`https://api.tokenplus.cn/v1`

核对下方的请求路径，最终聊天补全请求地址应为：

https://api.tokenplus.cn/v1/chat/completions

端点地址填写 API Base URL，不要将 /chat/completions 一并填入，也不要重复添加 /v1。

确认无误后，点击「添加」。

添加模型

在弹出的「选择模型」窗口中，搜索并勾选需要使用的模型，再点击右下角「添加所选模型」。可以按需选择，不必添加全部模型。

截图中的模型仅用于演示，实际可用模型以获取结果和 TokenPlus 模型广场为准。请选择支持 OpenAI Chat Completions 的对话模型。

后续需要更新列表时，可回到 TokenPlus 服务商页面点击「同步模型」。如果需要手动添加模型，点击模型区域右侧的「+」，从 TokenPlus 模型详情页复制完整模型调用标识作为模型 ID，不要仅填写展示名称；模型能力及参数以对应模型详情为准。

验证连通性

1. 检测并启用服务商

添加模型后，等待「检测并启用」流程完成。确认添加模型、模型验证和启用服务商均显示成功，再点击「完成」。如果检测失败，先按本文末尾的常见问题核对配置。

点击首次设置页面右下角「下一步」，按界面提示完成剩余设置并进入主界面。后续也可以在服务商页面点击「检测」重新验证连接，并确认右上角的服务商开关已开启。

2. 选择模型并发送测试消息

进入「Cherry 助手」，点击对话顶部的模型选择器，在 TokenPlus（截图中为 tokenplus）分组下选择刚刚添加的模型。

在 Cherry Studio 对话模型选择器中选择 TokenPlus 下的模型

发送一条测试消息，例如：

你好，请用一句话介绍你能帮我做什么。

收到正常回复即表示接入成功。

您还可以进入 TokenPlus 项目空间的调用日志，核对请求结果、模型和费用。

常见问题

获取模型失败或提示密钥无效

确认密钥来自 TokenPlus、复制完整且没有多余空格，并检查是否已过期或被停用。核对端点类型为 OpenAI，端点地址为 https://api.tokenplus.cn/v1，然后重试同步模型或检测。

提示找不到模型

重新同步模型，或从模型广场复制完整模型调用标识后手动添加。展示名称不一定等于请求使用的模型 ID；同时确认所选模型支持 OpenAI Chat Completions。

模型已添加，但对话没有使用 TokenPlus

确认 TokenPlus 服务商已启用，并在当前对话的模型选择器中明确选择 TokenPlus 分组下的模型。

检测或对话请求失败

查看 TokenPlus 调用日志中的错误信息，检查账户余额、项目预算和密钥消费限额。如果没有对应调用记录，请核对接口地址和本地网络；如果提示输出超限，请降低最大输出 Token 数。更多排查说明见常见问题。