Cherry Studio 适合在一个桌面客户端里使用多个模型。接入自定义 AI API 时，真正需要填写的只有三项：API 地址、API Key 和模型名称。问题通常出在地址多写了一段、Key 粘贴不完整，或者客户端保留了旧模型。
下面以 Zivv 的 OpenAI 兼容接口为例完成配置。
配置前准备
先完成三件事：
- 注册并登录 Zivv
- 在 API 令牌页面创建一个 Key
- 从 模型广场 选择一个当前可用模型
建议给 Key 命名为“Cherry Studio - 设备名”，以后查看用量或更换设备时容易识别。不要把同一个 Key 同时发给多人。
新增模型服务
在 Cherry Studio 的模型服务设置中新增 OpenAI 兼容服务，填写：
| 字段 | 内容 |
|---|---|
| API 地址 | https://zivv.pro/v1 |
| API Key | 控制台创建的 sk- Key |
| 模型 | 从模型广场复制的模型名称 |
API 地址填到 /v1 即可，不要填写完整的 /chat/completions。客户端会自动拼接具体接口。
添加和选择模型
如果客户端支持自动获取模型列表，先执行刷新。无法自动获取时，手动添加模型，但名称必须与平台返回的 id 完全一致。
可以先从用途出发：
- 编码、代码解释和长文档：选择当前 Claude 系列
- 通用问答和 OpenAI 兼容工作流：选择当前 GPT 系列
- 大量材料、图片或多模态任务：选择当前 Gemini 系列
模型会持续更新，本文不把某个版本写成永久推荐。名称和价格以 模型广场 为准。
先运行连接测试
保存前先执行 Cherry Studio 的连接测试。如果客户端没有测试按钮，新建一个对话，只发送“回复 OK”。
测试成功后再启用联网、工具调用、图片和长上下文。这样出错时更容易判断是基础配置，还是高级能力不被当前模型支持。
401 怎么处理
401 表示身份没有通过：
- 重新复制完整 Key，检查前后空格
- 确认使用的是 API Key，不是登录密码
- 删除旧服务中的旧 Key
- 完全退出并重启 Cherry Studio
也可以用 curl 请求模型列表，判断 Key 本身是否有效。详细步骤见 API Key 401 排查指南。
404 或找不到模型怎么处理
优先检查两项：
- API 地址必须是
https://zivv.pro/v1 - 模型名称从当前模型列表复制
如果仍然失败，确认 Key 分组允许该模型，并删除客户端缓存的旧模型。完整清单见 404 Model Not Found 排查指南。
多设备和团队建议
每台设备单独创建 Key，比共用一个 Key 更容易管理：
- 可以看出哪台设备产生用量
- 设备丢失时只撤销对应 Key
- 可以给不同设备设置不同额度
- 不影响服务器、Claude Code 或 Codex 的 Key
团队成员也应一人一个 Key，并通过 团队模式 分配预算。不要把主账号 Key 写进共享文档或群公告。
Key 安全
Cherry Studio 是本地客户端，但 Key 仍然等同密码：
- 不要截图完整 Key
- 不要导出并公开包含 Key 的配置
- 不要把 Key 提交到 Git 仓库
- 怀疑泄露时立即删除并重建
最终检查
完成后你应该有：
- 一个用途明确的独立 Key
- API 地址
https://zivv.pro/v1 - 一个从当前列表复制的模型名称
- 一次成功的最小对话
- 可在控制台看到的用量记录
第一次使用 API 的用户可以先阅读 AI API 新手入门。协议、SDK 和更多客户端配置在 Zivv 文档 中持续更新。