Cherry Studio 和 Chatbox 添加自定义服务商:给非开发同事也能看懂的配置说明

access2026-11-09·Cherry Studio自定义服务商

技术负责人真正要解决的不是「怎么点那几个菜单」,是把复杂接口收敛成几个可填字段,同时把密钥、日志、费用归属放在后台管住。

先说三个字段

任何客户端,界面叫法再花哨,填的都是这三样:

界面可能叫实际含义填什么
API 地址 / API Host / Base URL / 服务商地址请求发到哪儿https://token173.net/v1,通常到 /v1
API Key / 密钥 / 令牌谁在调用后台生成的 Key
模型 ID / 模型名称用哪个模型从平台模型列表复制的字符串

三个必须同源,都来自同一个后台。混用官方 Key 和第三方地址,是 401 的头号原因。

还有个反复出错的点:多数客户端会自己拼 /chat/completions,Base URL 填到 /v1 就够;把完整端点填进去会拼出重复路径。Cherry Studio 有些版本反过来要求去掉末尾斜杠,填之前看一眼字段旁的提示。

Chatbox:最快的最小连通性测试

Chatbox 适合先验证链路。步骤:

  1. 设置 → 模型服务商 → 添加,选「OpenAI Compatible / 自定义」类型;
  2. 填 Base URL(到 /v1)、API Key;
  3. 模型名称手动输入,从平台列表复制,不要从下拉里挑默认值;
  4. 点连接测试,或者发一句「只回复 OK」。

能返回就说明 Key、地址、模型名三样都对。之后再去别的工具里排查,范围会小很多。

Cherry Studio:适合多服务商、多模型对比

  1. 设置 → 模型服务 → 添加提供商,类型选 OpenAI;
  2. API 地址填 https://token173.net/v1,API Key 填后台生成的令牌;
  3. 点「管理」或手动添加模型,逐个填入 ID;
  4. 模型列表为空是常见现象 —— 有些聚合端点不返回 /v1/models,或者返回格式客户端不认,手动添加即可,不影响调用;
  5. 建两个会话,分别挂不同模型,用同一段 prompt 做对照。

第 4 步值得多说一句。遇到过好几次同事以为「模型列表拉不出来 = 平台不兼容」,其实会话能正常回,只是客户端解析列表失败。先发一条消息验证,别卡在列表上。

给非开发同事的一页配置说明

别把完整 Key 发群里。管理员按部门或项目建 Key,然后只发这一页:

服务商名称:(自己起一个好认的,如「部门 AI」)
API 地址  :https://token173.net/v1
模型 ID   :deepseek-v4 / claude-sonnet-5-5 / gemini-3.8-flash(按权限选)
Key       :由管理员通过安全渠道单独提供,或预置在配置里
费用归属  :运营部-Q4内容项目
禁止输入  :客户隐私、合同原文、账号密码、完整 Key、未公开数据
出错找谁  :(内部联系人)

配套一张最简台账,先人工维护就够:日期、部门、用户、项目、模型、任务类型、调用次数、异常、费用归属。等维护不住了,再上后端代理或平台的子账号体系。

管理员先跑一次冒烟测试

发配置之前,自己用部门 Key 打一次:

curl -sS -X POST "https://token173.net/v1/chat/completions" \
  -H "Authorization: Bearer 部门Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4","messages":[{"role":"user","content":"只回复 OK"}]}'

再固定三个测试问题:短文本改写、一段信息摘要、一次风险提醒。三次都过,才开放给同事。

常见问题

现象原因处理
认证失败Key 复制带空格、已回收、地址与 Key 不同源重新生成 Key,检查末尾空格
模型列表为空客户端不解析 /v1/models手动添加模型 ID,再发消息验证
404 model not foundID 手打错、型号已下架从平台列表复制,别照抄文档
能连上但回答很慢长任务读超时、客户端默认超时太短换短问题先测,再调超时
费用混在一起多人共用一个 Key按部门 / 项目拆 Key
Key 被发到群里流程问题立即回收重建,改用预置配置

平台侧要能配合什么

给团队用,光「能聊」不够。后台至少得支持:按项目建多个 Key、每个 Key 设额度上限和可用模型范围、调用记录能按 Key 导出、输入 / 输出 / 缓存分项可查、Key 能单独停用。没有这几样,费用归属只能靠台账猜。

我们这轮部门试用放在 token173.net 上,图的是控制台能按 Key 分开看用量,文本、图像、视频型号都在同一个后台,运营想临时试个生图不用再走一遍采购。试用阶段只开了三个部门 Key,每个都设了额度上限,跑满两周再决定要不要扩。

什么时候该升级

少量同事试用,Chatbox 和 Cherry Studio 够用。任务变成固定流程、要接知识库、要审批,上 Dify;记录已经靠人工维护不住、费用归属说不清,上后端代理,统一记 user_id、project_id、cost_center、model 和状态码。

判断标准不是人数,是台账还管不管得住。

最后

给非开发同事配 API,重点从来不是把客户端填上,是把部门 Key、模型 ID、禁止输入清单、费用归属和回收机制先设计好。这些想清楚了,工具换哪个都只是点几下的事。