Cherry Studio / Chatbox / LobeChat：桌面客户端的 base_url 配置要点

为什么先讲这一类

桌面客户端（Cherry Studio、Chatbox、LobeChat、NextChat 等）是接中转站门槛最低的一类：填三个字段就能用。也正因为简单，很多人把它当成「验证中转站能不能用」的标准 —— 而这恰恰是问题所在。

能聊天只证明了一件事：/v1/chat/completions 的纯文本路径能通。 它不能证明工具调用、图片输入、结构化输出可用。

配置三要素

1. Base URL

两类客户端对 URL 的处理不同：

• 要求填完整路径的：https://<域名>/v1/chat/completions
• 要求填到 /v1 的：https://<域名>/v1
• 允许只填域名的：自动补 /v1

判断方法：填完先点「测试」，不通就换另一种写法。两三次之内就能找到正确的形态。

高频错误：把 /v1 填了两次（https://<域名>/v1/v1）。这在「允许只填域名」的客户端里很常见 —— 它自动补了 /v1，你又手填了。

2. API Key

有些客户端会把 Key 直接放在 Authorization: Bearer 里，有些会放在 x-api-key。中转站大多认前者。如果测试一直 401，先确认客户端用的是哪种。

3. 模型名 ★最常错

和 Cursor 一样：必须手动添加模型名，且必须与中转站一致。

在 Cherry Studio / LobeChat 这类客户端里，通常是「添加模型」→ 输入模型 ID。填错的表现是：测试连接显示成功（因为测试通常只验证端点可达），但一发消息就 404 或 400。

最稳的做法：先 curl 拿清单。

curl -s https://<域名>/v1/models -H "Authorization: Bearer $KEY" | head -c 2000

「测试成功」≠「能用」

这是本文最想强调的一点。分三步验证，不要停在第一步：

第 2 步经常被忽略：如果输出是「等几秒然后整段出现」，说明这家站的流式是伪流式（做了缓冲转发）。对交互式使用影响明显。

第 3 步：桌面客户端里最常用的高级能力是图片输入（截图问答）。测一句话：「这张图里有什么」+ 一张图。如果不支持，有些站会直接 400，有些会忽略图片只处理文字（后者更隐蔽）。

多客户端共用一个中转站

如果你同时用桌面客户端、IDE 插件、脚本，建议做一件小事：在中转站里为每个客户端开一个独立的 Key。

好处：

1. 用量可分离：出了问题知道是谁在打；
2. 可单独封禁：某个客户端配置出问题导致高频重试时，不会拖垮其它用途；
3. 便于排查：站方后台的调用日志可以按 Key 过滤。

这一项在 Cherry Studio 这类会做「多模型并发请求」的客户端上尤其有用 —— 有的客户端会在你发一句话时同时打多个模型做对比，用量远超预期。

LobeChat 自部署的额外注意点

LobeChat 可以自己部署（提供 Docker 镜像）。这时请求是从你的服务器发出的，需要注意：

1. 服务器能访问到中转站。如果中转站在国内、服务器在海外，可能有反向的网络问题；
2. 环境变量里的 Key 不要写进镜像。用运行时注入，否则镜像分享出去等于泄露；
3. 注意出站 IP。如果站方有 IP 白名单，要加服务器的出口 IP，而不是你本机的。

一个选择建议

如果你只是为了验证一家中转站是否适合自己，桌面客户端是最快的工具 —— 五分钟能跑完文本与图片两项测试。

但如果你要做生产评估，桌面客户端测不出关键信息。至少还要补：

• 用 curl 跑工具调用测试（见本站《函数调用兼容性》）；
• 跑流式的六项检查（见《流式输出（SSE）的六种异常》）；
• 看站方后台的用量统计是否准确（对账能力）。

这三项才是决定能不能用于生产的判据。