手里已经有一把中转 API key,想接到自己常用的客户端里用,结果发现:在 Cursor 里填法是一套,换到 Cline 又是另一套,LobeChat、ChatBox、NextChat 各有各的脾气。最折磨人的不是不会填,而是每换一个客户端就要重新踩一遍同样的坑——到底要不要带 /v1、模型名填什么、为什么测试报 404。本文把这些客户端的填法整理成一张对照速查表,再讲清楚背后几个通用规律,让你接下来换任何客户端都能照着填、一次填对。
全文以 OpenAI 兼容形态的中转为例,客户 Base URL 统一写作 https://api.apipifa.com/v1(OpenAI 兼容端点)。各客户端界面会随版本更新,以下字段名与位置以你当前用的版本实际界面为准,本文给的是判断逻辑,不是逐像素的截图说明。
先上对照速查表。横向是客户端,纵向是三个最容易填错的点:接口类型选哪个、Base URL 怎么填(含要不要 /v1)、模型名注意点。
| 客户端 | 接口类型选哪个 | Base URL 填法(以 apipifa 为例) | 模型名注意点 |
|---|---|---|---|
| Cursor | Settings > Models 页 "Override OpenAI Base URL"(OpenAI 兼容) | 填 https://api.apipifa.com/v1,必须带 /v1;Cursor 会自动在后面拼 /chat/completions | 点 "+ Add Model" 手动加模型名,名字要和中转端一致 |
| Cline | API Provider 选 "OpenAI Compatible" | Base URL 填 https://api.apipifa.com/v1;别把 /v1/chat/completions 整条贴进去 | Model ID 单独一栏,填中转端 /v1/models 返回的准确名字 |
| LobeChat | 自定义服务商,SDK/请求格式选 OpenAI | 代理/接口地址填 https://api.apipifa.com/v1;若回复为空,多半是 /v1 没带对 | 在该服务商下手动添加模型,或拉取模型列表后选 |
| ChatBox | 添加提供方,API 模式选 "OpenAI API Compatible" | API 域名/Host 填 https://api.apipifa.com/v1 | 拉不到列表就手动输模型 ID,Chatbox 会直接用你输的名字 |
| NextChat | 自定义接口(OpenAI 接口) | 接口地址填 https://api.apipifa.com/v1;不要贴成 /v1/chat/completions | 自定义模型名一栏填准确模型名,大小写、横杠都要对 |
| Cherry Studio | 添加提供方,类型选 OpenAI | 填 https://api.apipifa.com/v1/(末尾带 /,见下文)或 https://api.apipifa.com(让它自动补全) | OpenAI 兼容模式下通常不自动拉列表,手动添加模型 ID |
这张表覆盖了大多数人会遇到的组合。下面几节把表里没法一句话说完的关键点拆开讲——尤其是 /v1 的有无、Cherry Studio 的末尾斜杠、还有 Anthropic 类客户端那个反直觉的坑。
这是所有坑里最值钱的一条。中转地址后面到底要不要带 /v1,取决于客户端用的是哪种 SDK 协议:
一句话记忆:OpenAI 兼容要 /v1,Anthropic 原生只要根域名,Gemini 走 /v1beta。 本文示例 apipifa 是 OpenAI 兼容形态,所以客户 Base 统一是 https://api.apipifa.com/v1。
为什么很多人在这里栽?因为同一个中转站往往同时提供 OpenAI 兼容端点和 Anthropic 兼容端点,而同一个客户端在"OpenAI 模式"和"Claude 模式"下对 Base URL 的要求正好相反。你在某个客户端的 Anthropic 模式里填了带 /v1 的地址,测试就会报 404;同样这段地址放在 OpenAI 模式里却是对的。所以填之前先确认两件事:客户端这一栏走的是哪种协议、对应该端点该不该带 /v1。
大多数客户端里,Base URL 末尾不要多带一个 /。多一个斜杠,有些客户端拼出来就是 .../v1//chat/completions,双斜杠在部分网关上会被判成无效路径报错。复制粘贴时尤其要检查行尾——从网页控制台复制地址,经常会把多余的空格或斜杠也带进来。
但 Cherry Studio 是个反直觉的特例,值得单独记:它的官方说明里有一条规则——如果你只填根地址(不以 / 结尾),它会自动补全 /v1/chat/completions;如果你填的地址以 / 结尾,它就只在后面接 chat/completions、不再替你补 /v1。 所以在 Cherry Studio 里,你要么填 https://api.apipifa.com/v1/(自己把 /v1 写全并以斜杠收尾,让它只接 chat/completions、拼出 .../v1/chat/completions),要么填 https://api.apipifa.com(让它自动补成 .../v1/chat/completions)。最容易出错的是填 https://api.apipifa.com/v1(带 /v1 但末尾没斜杠),拼接结果可能和你预期不符。遇到 Cherry Studio 报路径类错误,先回来核这个末尾斜杠规则;它还支持在地址末尾用 # 关闭自动补全、强制按你填的原样发,实在拼不对时可作为兜底。
很多客户端预置了一份官方模型列表(比如自带 gpt 系列、claude 系列的条目)。当你接中转后,如果客户端里既有它内置的同名模型、又有你新加的同名模型,有些客户端会优先走内置那条逻辑——结果你以为请求发去了中转,实际它走的是客户端默认通道,表现就是 key 报错、或模型行为和你预期不符。
稳妥做法:在能区分的客户端里,把内置的官方服务商关掉或留空 key,只保留你自建的那个"OpenAI 兼容"服务商,模型也只在这个自建服务商下添加。这样请求路径唯一,排错时也不用猜到底走了哪条线。LobeChat、Cherry Studio、ChatBox 这类支持多服务商并存的客户端,最容易因为"两个服务商都有同名模型"而串台,记得检查。
这是仅次于 /v1 的高频翻车点。客户端发请求时,model 字段填的是什么,中转端就拿什么去匹配。名字差一个字符、大小写不对、横杠写成下划线,都会 404 或返回 model not found。 中转端支持的是 gpt-4o,你填成 gpt4o 或 GPT-4o,都不认。
怎么拿到准确的模型名?最可靠的方式是查中转端的 /v1/models 接口(Cline、NextChat 这类客户端会提示你用 /v1/models 返回的 ID),把里面的 id 原样复制过来用。注意一个容易被忽略的点:客户端能拉到模型列表 ≠ 它会自动选对。 Cherry Studio、ChatBox 在 OpenAI 兼容模式下经常不自动拉列表、需要你手动输模型 ID;这种手动输入时,粘贴比手打更不容易出错。如果你的中转端对模型名做了别名映射,以中转端文档/控制台公布的可用名为准,不要凭官方原名想当然。
填完别急着干活,先做一次最小验证,确认这条链路真的通。最简单的办法就是在客户端里新建对话、发一句"你好"或"say this is a test",看是否正常返回一段回复。 能正常回字,说明 Base URL、key、模型名三者全对。
如果客户端自带"验证 / Verify / 测试连接"按钮,可以先点它(Cursor、ChatBox 都有),但要留意一个细节:有些客户端的测试按钮打的是和实际聊天不一样的路径。比如个别 Anthropic 类客户端,聊天能通、但测试按钮去打了 /v1 根路径反而报错——这种情况下以"实际发一句话能不能回"为准,测试按钮的红叉不一定代表真的不通。
想要更干净的判定,也可以脱离客户端、直接发一个最小请求看 HTTP 返回:对 https://api.apipifa.com/v1/chat/completions 发一条带 model 和一句 messages 的请求,响应里出现 choices 数组、里面有 message.content,就说明端点、鉴权、模型名全部对得上。按返回里的报错对症下药会快很多:
把这套流程走一遍,你会发现各客户端的差异其实就集中在三件事:接口类型选哪个、Base 要不要带 /v1、模型名怎么填。 记住"OpenAI 兼容带 /v1、末尾不带斜杠(Cherry Studio 例外)、模型名严格一致、填完发一句话测",换任何新客户端都不用再从头踩坑。最后再提醒一次:上面所有客户端的具体界面字段会随版本变化,本文给的是不变的判断逻辑,实际操作以你当前版本的界面为准。能不能稳定跑、会不会偶发抖动,也和你的网络环境、中转端当下状态有关,多数情况下按本文填对就能正常用,但不存在"一次填对永远不出问题"的承诺。