Cherry Studio 是很多人在桌面端用多模型的首选客户端：一个界面里切换不同模型、管理助手和知识库。接入自定义 AI API 时，真正需要填的只有三项：API 地址、API Key 和模型名称。绝大多数配置失败都出在地址多写了一段、Key 粘贴不完整，或者客户端保留了旧模型。下面以 Zivv 的 OpenAI 兼容接口为例，从零完成配置，并附完整的报错对照表。
为什么选中转站而不是逐家申请
Cherry Studio 支持配多个服务商，但逐家申请意味着多份账号、多张卡、多处充值。接一个 Zivv 的好处很直接：一个 sk- Key 就能调 100+ 模型（Claude、GPT、Gemini 全系），人民币充值 ¥1 = $1，按量计费，价格低至官方几折。客户端里只需要维护一个服务商条目。
配置前准备
先完成三件事：
- 注册并登录 Zivv，充值最低 ¥10 即可
- 在控制台的 API 令牌页面创建一个 Key
- 从模型广场选定一个当前可用的模型，复制其准确名称
建议给 Key 命名为「Cherry Studio - 设备名」，以后看用量、换设备时容易识别。不要把同一个 Key 发给多个人，也不要和服务器、脚本共用一个 Key——桌面客户端和自动化任务的用量特征完全不同，混在一起后你将永远看不清哪边在花钱。
如果你还没有决定用哪个模型，不妨先创建 Key，用后文的 curl 命令把当前可用模型列表拉出来看一眼，再回模型广场对照定价挑选。整个准备过程五分钟以内。
第一步：新增模型服务
打开 Cherry Studio 的设置，进入模型服务（Provider）页面，新增一个 OpenAI 兼容类型的服务，填写：
| 字段 | 内容 | 常见错误 |
|---|---|---|
| API 地址 | https://zivv.pro/v1 | 漏掉 /v1，或多写 /chat/completions |
| API Key | 控制台创建的 sk- Key | 粘贴不完整、前后带空格 |
| 模型 | 从模型广场复制的名称 | 凭记忆手敲、用了已下线版本 |
API 地址填到 /v1 为止，具体接口由客户端自动拼接。如果客户端把地址显示成完整 URL 预览，确认最终请求路径是 /v1/chat/completions 而不是重复拼接的 /v1/v1/...。
如果你之前已经配过其他服务商，建议新建一个条目而不是改旧条目：旧条目里可能残留着旧 Key、旧模型和各种当时的临时设置，新建条目从干净状态开始，出问题时也容易对比定位。配好之后再决定是否删掉不用的旧条目。
第二步：添加和选择模型
如果客户端支持自动获取模型列表，先点刷新，从列表里勾选需要的模型。无法自动获取时手动添加，但名称必须与平台返回的 id 完全一致。不确定时用终端验证一下当前 Key 能看到哪些模型：
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key"选型可以从用途出发：
- 编码、代码解释和长文档：选当前 Claude 系列（如 claude-sonnet-5）
- 通用问答和 OpenAI 兼容工作流：选当前 GPT 系列（如 gpt-5.5）
- 大批量材料、多模态任务：选当前 Gemini 系列（如 gemini-3.5-flash）
模型会持续更新，本文不把某个版本写成永久推荐，名称和价格以模型广场页面为准。
一个实用建议：不要一口气把列表里的几十个模型全部勾上。先启用两三个明确要用的，界面清爽，也避免误选到高价模型跑日常任务。之后需要什么再回来加，反正只是一次勾选的事。
第三步：设置默认模型与功能模型
Cherry Studio 里不止「对话用哪个模型」一处设置。默认助手模型、话题命名、翻译等功能可能各自绑定模型，这是很多人「明明配好了却感觉不对劲」的来源：
- 默认助手模型：日常对话的主力，建议设为当前 Claude 或 GPT 主力档
- 话题命名等辅助功能：每次对话都会静默调用，务必绑到便宜的轻量模型（如 gemini-3.5-flash），别让它默默烧主力模型的钱
- 翻译类高频功能：同理选轻量档，速度更快，成本几乎可以忽略
检查一遍这些角落里的模型绑定，往往能同时解决「莫名扣费」和「响应变慢」两个问题。
第四步：连接测试
保存前先执行 Cherry Studio 自带的连接测试。如果没有测试按钮，就新建一个对话，只发送一句「回复 OK」。等最小对话成功后，再逐项启用联网、工具调用、图片和长上下文——这样出错时能立刻分辨是基础配置错了，还是某个高级能力不被当前模型支持。
这个「先最小、后叠加」的顺序值得坚持。反面教材是一上来就开着联网加知识库问一个复杂问题，失败之后完全无从判断是 Key 错了、模型不支持工具调用，还是知识库检索出了问题，只能盲目重装。最小对话把变量一次锁定一个。
想彻底排除客户端因素，也可以直接在终端发一个最小请求：
curl https://zivv.pro/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"回复 OK"}]}'终端成功而客户端失败，问题一定在客户端配置；终端也失败，按下面的对照表处理。
报错对照：现象 → 原因 → 解法
| 现象 | 原因 | 解法 |
|---|---|---|
| 401 认证失败 | Key 粘贴不完整或带空格 | 重新复制完整 Key，纯文本检查前后 |
| 401 且刚换过 Key | 服务条目里还存着旧 Key | 删除旧值重填，完全退出并重启客户端 |
| 404 页面式错误 | API 地址漏 /v1 或多拼路径 | 地址改为 https://zivv.pro/v1 |
| model_not_found | 模型名拼错或已下线 | 从模型列表刷新后重新勾选 |
| 能列模型但对话失败 | Key 分组不含所选模型 | 控制台检查分组，换分组内模型 |
| 连接超时 | 本地网络或代理拦截 | 检查代理规则，先用 curl 验证连通 |
更细的排查见 API Key 401 排查指南和 404 Model Not Found 排查指南。
费用与用量：怎么花得明白
Cherry Studio 客户端本身免费，费用只来自 API 调用。Zivv 按量计费，充值汇率 ¥1 = $1，人民币直付，各模型价格低至官方几折，用多少扣多少，没有订阅套餐的浪费。
几个让账单可控的习惯：
- 给客户端 Key 单独命名并设额度：桌面端属于交互式使用，正常用量不高，设一个宽松上限即可防意外
- 高频轻任务绑轻量模型：话题命名、翻译这类每天触发几十次的功能，用 gemini-3.5-flash 档位跑，成本几乎可以忽略
- 定期看控制台用量：按 Key 和模型维度检查消耗分布，如果发现轻任务在烧主力模型，回到第三步调整绑定
- 长文档对话注意上下文累积：历史越长每轮越贵，话题告一段落就开新对话
想系统了解 Token 计费口径和预算估算方法，博客里的 Token 费用计算指南有完整的公式和脚本。
多设备和团队建议
每台设备单独创建 Key，比共用一个 Key 好管理得多：
- 用量记录能看出是哪台设备产生的消耗
- 设备丢失或转手时只撤销对应 Key，其他设备不受影响
- 可以按设备设置不同额度，测试机不怕跑飞
- 不影响服务器、Claude Code 或 Codex 用的 Key
团队成员同样一人一 Key，通过团队模式统一充值、共享余额，并为每个成员设独立预算和用量看板。新人入职发一个 Key、离职撤销一个 Key，不需要动任何共享凭据。不要把主账号的 Key 贴进共享文档或群公告——贴出去的那一刻就应视为已泄露。
Key 安全
Cherry Studio 是本地客户端，但 Key 仍然等同密码：
- 不要截图包含完整 Key 的设置页
- 不要导出并公开包含 Key 的配置文件
- 不要把 Key 提交到 Git 仓库
- 怀疑泄露时立即删除重建，并检查近期用量
分享配置教程或求助截图时特别容易翻车：设置页往往完整显示 Key。截图前先把 Key 遮住，或者干脆删掉重建一个再截。重建 Key 只要十秒，追回被盗刷的余额可没这么容易。
常见问题 FAQ
Q：Cherry Studio 本身收费吗？ A：客户端免费，费用只来自 API 调用，按实际 Token 用量从 Zivv 余额扣除，用量在控制台随时可查。
Q：一个服务条目里能同时用 Claude、GPT 和 Gemini 吗？ A：可以。Zivv 的 OpenAI 兼容接口统一暴露全部模型，一个条目里勾选多个模型即可切换。
Q：模型列表刷新不出来怎么办？ A：先用本文的 curl 命令确认 Key 与网络正常；正常的话手动添加模型，名称从返回的 id 复制。
Q：如何知道自己用了多少钱？ A：Zivv 控制台的用量页面按 Key、模型、时间维度展示消耗，建议给 Cherry Studio 的 Key 单独命名以便区分。
Q：知识库、长文档场景该选什么模型？ A：大批量材料的初筛和摘要用轻量档（如 gemini-3.5-flash）控制成本，关键问答和深度分析再交给 Claude 主力档。分两步走通常比全程用顶配模型便宜得多，效果也不差。
最终检查
完成后你应该有：一个用途明确的独立 Key、API 地址 https://zivv.pro/v1、一个从当前列表复制的模型名称、一次成功的最小对话，以及控制台里能看到的用量记录。五项都齐，说明整条链路——账户、Key、地址、模型、计费——全部打通，之后任何问题都可以对照这条基线快速定位。
配置一次，之后换模型只是下拉框里的一次点击。还没有账号的话，注册 Zivv 拿到 Key 再回到第一步，全程不超过五分钟；协议细节与更多客户端配置见 Zivv 文档。