Cherry Studio 使用配置

本教程说明如何在 Cherry Studio 中添加 Poke API 服务商，配置 API 地址和密钥，获取模型列表并开始对话。

Cherry Studio 不同版本的按钮位置或名称可能略有变化，但核心配置相同：服务商类型选择 OpenAI，API 地址填写 Poke API 根地址，密钥使用控制台创建的 API Key。

一、准备

开始前请准备：

• 已安装 Cherry Studio 桌面客户端；
• 已登录 Poke API 控制台；
• 一个可用的 API Key；
• API Key 已绑定需要使用的模型分组。

服务根地址为：

https://www.poke2api.com

不要重复添加 /v1

Cherry Studio 的 API 地址填写根地址即可，不要填写 https://www.poke2api.com/v1，也不要填写完整的 /v1/chat/completions 请求路径。客户端会自动拼接协议路径。

API Key 属于敏感信息，请勿发送给他人，也不要上传到公开仓库或包含在公开截图中。

二、打开模型服务设置

1. 打开 Cherry Studio；
2. 点击左下角的 设置；
3. 在左侧进入 模型服务。

三、添加服务商

在服务商列表底部点击 添加。

在弹窗中填写：

配置项	建议内容
提供商名称	Poke API，也可以填写任意便于识别的名称
提供商类型	OpenAI

确认后，左侧服务商列表中会出现新建的 Poke API 服务商。

四、填写 API 地址和密钥

选中刚创建的服务商，在右侧填写：

配置项	填写内容
API 密钥	控制台中创建的 API Key
API 地址	https://www.poke2api.com

填写完成后，Cherry Studio 通常会预览实际请求地址。聊天请求的预览地址应类似：

https://www.poke2api.com/v1/chat/completions

如果预览中出现 /v1/v1/，说明 API 地址多填写了一层 /v1，请改回根地址。

点击 API 密钥输入框旁的 检测，验证地址和密钥是否能够访问服务。

五、获取模型列表

点击 获取模型列表。Cherry Studio 会使用当前 API Key 请求模型目录，并显示该 Key 当前可见的模型。

如果模型列表为空，请依次检查：

1. API 地址是否为完整根地址 https://www.poke2api.com；
2. API Key 是否完整、有效且未撤销；
3. API Key 是否已绑定至少一个可用分组；
4. 当前用户是否仍有分组权限、有效订阅或可用额度；
5. 点击 检测 后是否出现明确错误。

模型列表由 API Key 的实际权限决定。更换 Key、调整分组绑定或管理员修改模型后，应重新获取模型列表。

六、启用模型

获取模型后，可以按组或按单个模型添加：

1. 点击模型组右侧的 +，添加该组模型；
2. 或点击单个模型右侧的 +，只添加需要的模型；
3. 添加后的模型会出现在当前服务商的已启用模型列表中。

建议只启用常用模型，避免模型选择器过长。模型名称请保持服务端返回的原始名称，不要自行重命名为另一个上游模型。

七、开始对话

完成配置后：

1. 返回 Cherry Studio 对话页面；
2. 新建对话；
3. 在模型选择器中选择刚配置的 Poke API 服务商；
4. 选择一个已启用的聊天模型；
5. 发送简单测试消息。

收到真实回复后，才表示 API 地址、密钥、分组、模型和上游账号均可正常工作。

推荐的首次测试

先使用简单、短小的消息：

请只回复：连接成功

首次测试不建议同时开启大量工具、超长上下文、图片理解或联网功能。基础对话成功后，再逐项启用高级能力，便于定位问题。

八、多分组 API Key

Poke API Key 可以绑定多个分组。Cherry Studio 正常使用时无需手动设置 X-Sub2API-Group-ID：

• 服务端会按 Key 的分组优先级寻找支持当前模型和端点的候选；
• 当前分组不可用且请求尚未产生有效输出时，可以按服务端规则尝试其他绑定分组；
• 调整 Key 的分组绑定后，建议在 Cherry Studio 中重新获取模型列表并重启相关对话。

如果长期只使用一种模型或一个固定分组，建议创建独立 API Key，而不是让客户端长期保存固定分组请求头。

九、图片模型说明

Cherry Studio 的 OpenAI 服务商配置主要用于聊天和兼容模型调用。即使模型列表中出现图片模型，是否能在 Cherry Studio 界面直接调用 OpenAI Images 端点，仍取决于所安装的 Cherry Studio 版本和对应功能入口。

需要稳定调用文生图或图片编辑时，推荐使用：

• Poke API 控制台的 练习场 → Image / 图片模式；
• POST /v1/images/generations；
• POST /v1/images/edits。

具体操作见 图片生成 API 教程。不要把图片模型作为普通聊天模型发送到 /v1/chat/completions 后期待返回图片。

十、常见问题

检测失败

• API 地址只填写 https://www.poke2api.com；
• 检查地址前后是否有空格；
• 重新复制完整 API Key；
• 确认系统时间正确，网络可以访问服务域名；
• 保留 Cherry Studio 显示的真实错误信息用于排查。

返回 401

密钥缺失、错误、已撤销或复制不完整。重新从控制台复制 API Key，不要复制密钥名称或其他说明文字。

返回 403

当前用户或 API Key 无权使用目标分组，或者客户端仍保存了失效的固定分组信息。重新获取模型列表，必要时删除并重新添加服务商。

可以获取模型，但对话时提示模型不可用

模型目录表示该 Key 可以看到模型，不保证上游账号在任意时刻都可调度。请检查：

• 模型是否属于该 Key 已绑定的分组；
• 当前分组是否有可用额度；
• 模型是否暂时限流或无可用账号；
• 模型名称是否被手动修改；
• 更换另一个当前可用模型后是否恢复。

请求地址出现 /v1/v1/

把 API 地址从：

https://www.poke2api.com/v1

改为：

https://www.poke2api.com

修改分组后仍显示旧模型

1. 点击 获取模型列表；
2. 删除已失效的旧模型；
3. 重新添加当前返回的模型；
4. 新建对话或重启 Cherry Studio。

相关教程

• 快速开始
• 图片生成 API 教程
• API 脚本接入