Cherry Studio
- 官方主页：cherry-ai.com
- 官方文档：docs.cherry-ai.com
- 模型服务配置：模型服务设置 / 自定义服务商
- GitHub：github.com/CherryHQ/cherry-studio
- 协议类型：OpenAI 兼容 / Anthropic Messages / Gemini（按服务商类型选择，可在同一应用里并存）
安装
Cherry Studio 是桌面客户端，支持 Windows、macOS、Linux。从官方下载页获取对应平台安装包，其余以官方为准：
- macOS：
.dmg（Intel / Apple Silicon 分包） - Windows：
.exe安装器或免安装.zip - Linux：
.AppImage/.deb/.rpm
也可在 GitHub Releases 选择具体版本。
安装后打开应用，在 设置 → 关于我们 中可查看当前版本号；遇到问题时建议先升级到最新版。
对接 TokenBay
对接机制
Cherry Studio 是图形界面客户端，不使用环境变量，所有网关配置都在应用内 设置 → 模型服务 面板完成：新增一个「自定义服务商」，选择服务商类型（决定走哪种协议），填入 API 地址（Base URL） 与 API 密钥。凭证以 Authorization / x-api-key 头随请求发送，由 Cherry Studio 自动处理。
TokenBay 的同一把 Key 可同时用于三种协议，建议按需添加多个服务商：
- OpenAI（推荐起步）：覆盖全部文本模型（GPT、Claude、Gemini、DeepSeek、GLM、Qwen 等都可经 OpenAI 兼容协议调用）。
- Anthropic：走原生 Anthropic Messages 协议，适合 Claude 系列及支持该协议的模型，功能最完整（prompt caching 等）。
- Gemini：走原生 Gemini 协议，适合
gemini-*系列。
Base URL 拼接规则（务必看）：Cherry Studio 会在你填的地址后自动拼接协议对应的路径（OpenAI→
/v1/chat/completions、Anthropic→/v1/messages、Gemini→/v1beta/...）。
- 所以 API 地址只填根域名
https://api.tokenbay.com（不带/v1、不带结尾斜杠、不带具体 endpoint）。- 如果你填了完整路径想让它原样使用、不拼接，则地址必须以
#结尾（官方约定）。一般情况下用根域名即可，无需此写法。
1. 获取 API Key
登录 TokenBay 控制台 → API 密钥 → 创建密钥。复制以 sk- 开头的完整字符串。明文仅显示一次，离开页面后无法再查看。
2. 添加 OpenAI 兼容服务（推荐起步）
进入 设置（左下角齿轮）→ 模型服务，点列表下方 + 添加，在弹窗里：
| 字段 | 值 |
|---|---|
| 服务商名称 | TokenBay (OpenAI)（自定义，便于识别） |
| 服务商类型 | OpenAI |
点 添加 后，在该服务商详情页填写：
| 字段 | 值 |
|---|---|
| API 密钥 | 你的 TokenBay API Key（sk-...） |
| API 地址 | https://api.tokenbay.com |
填好后：
- 点 API 密钥输入框右侧的 检查 / Check 按钮做连通性校验（会用模型列表里最后一个对话模型测试，需先添加好模型）。
- 在 管理 / 添加 中加入要用的模型 ID（见下文推荐模型），点模型右侧 + 加入模型列表。
- 务必打开右上角的启用开关，否则该服务商不生效，模型选择器里看不到对应模型。
3. （可选）添加 Anthropic 服务
需要让 Claude 系列走原生 Anthropic 协议（功能更完整）时，按第 2 步再加一组：
| 字段 | 值 |
|---|---|
| 服务商名称 | TokenBay (Claude) |
| 服务商类型 | Anthropic |
| API 密钥 | 同一把 TokenBay Key |
| API 地址 | https://api.tokenbay.com |
Cherry Studio 会自动在地址后拼 /v1/messages，不要手动加路径。
4. （可选）添加 Gemini 服务
需要 gemini-* 走原生 Gemini 协议时：
| 字段 | 值 |
|---|---|
| 服务商名称 | TokenBay (Gemini) |
| 服务商类型 | Gemini |
| API 密钥 | 同一把 TokenBay Key |
| API 地址 | https://api.tokenbay.com |
Cherry Studio 会自动拼接 /v1beta/... 路径，同样只填根域名。
5. 推荐模型
| 用途 | 模型 ID | 走哪个服务商 |
|---|---|---|
| 通用旗舰 | gpt-5.5 | TokenBay (OpenAI) |
| 主力编码 | claude-sonnet-4.6 | TokenBay (Claude / OpenAI) |
| 复杂重构 / 长上下文 | claude-opus-4.8 | TokenBay (Claude / OpenAI) |
| 轻量 / 快速响应 | claude-haiku-4.5 | TokenBay (Claude / OpenAI) |
| 编码替代（OpenAI 系） | gpt-5.3-codex | TokenBay (OpenAI) |
| 多模态 / 视觉 | gemini-3.1-pro-preview | TokenBay (Gemini / OpenAI) |
模型 ID 直接透传上游，无前缀。完整可用列表见 模型清单 或 控制台 Models 页面。
模型名格式：TokenBay 的模型名称中版本号仅接受小数点形式（如
claude-sonnet-4.6、gpt-5.5），不要写成连字符形式（claude-sonnet-4-6、gpt-5-5）。上表为示例；接入前请到控制台核对准确的 Model ID，并确认 API Key 所属分组已授权该模型（未启用的模型需在控制台分组设置中授权）。
6. 进阶配置（多 Key / 流式 / 长任务）
- 多 Key 轮询：单个服务商支持多个 Key，用英文逗号分隔填入 API 密钥栏（如
sk-xxx1,sk-xxx2），Cherry Studio 会从前到后循环使用。 - 流式响应：默认开启，TokenBay 兼容标准 SSE。长任务若出现卡顿/截断，可先在该服务商或对话设置里关掉流式复测，定位是网络还是协议问题。
- 长任务超时：长上下文/Agent 任务耗时较长，如出现中断，先用
curl排查到api.tokenbay.com的连通性与代理，再确认上游模型并发/速率限制。