同一个 API Key，为什么 WorkBuddy 能用，Trae IDE 却报错？聊聊 LLM 客户端的兼容性玄学
摘要：现在通过 API Key 调用 LLM 算力的平台越来越多，但很多人会遇到一个奇怪现象：同一套 URL、API Key、模型 ID，在 WorkBuddy 里能用，在 Trae IDE 里却报错；或者反过来，怎么配都不行，换一个客户端突然就通了。问题不一定出在 API Key 本身，而可能出在"LLM 客户端"的兼容性上。本文结合个人踩坑经验，聊聊如何排查、如何换客户端，以及为什么 WorkBuddy、Trae IDE、Claude Code、Antigravity 这类工具值得同时保留。
现在以 API Key 方式提供 LLM 算力的平台已经很多了。除了国内一些比较经典的平台，还有很多聚合平台、中转平台、自建网关、企业代理，甚至个人开发者搭的 OpenAI 兼容接口。它们大多会给你三样东西：一个 Base URL、一个 API Key、一串模型 ID。看起来很简单，但真正接到客户端里，故事才刚刚开始。
一、自动导入很香，自定义配置很痛
如果你用过 WorkBuddy 或 Trae IDE，应该会有这种体验：添加大模型时，客户端会自动跳出来一些预定义好的 URL、鉴权方式、模型列表。你只需要填 API Key，下拉菜单选模型，点保存，基本就能用了。这种体验非常友好，尤其对不熟悉接口协议的人来说，几乎零门槛。
但问题在于，不是所有平台都能被自动识别。很多平台需要你选择"自定义"，然后手动填写 Base URL、API Key、Model ID，甚至还要配置高级设置：温度、Top P、Max Tokens、超时时间、代理、流式开关、请求头、接口路径等。只要其中一项和客户端预期不一致，就可能失败。
更让人迷惑的是：同样的配置，在 WorkBuddy 上能用，在 Trae IDE 上却不能用；有些平台则反过来，只有在 Trae IDE 上才行。 不同接口标准、不同 URL 长短、带不带 /v1、带不带 /chat/completions，我都试过。错误信息也五花八门：有时是 404，有时是 401，有时是 429，更多时候是"解析 JSON 失败""Unexpected token""Invalid response""Stream error"之类让人摸不着头脑的提示。
二、不一定是 API Key 的问题，可能是客户端的问题
一开始我也怀疑是 API Key 填错了、额度不够、平台挂了。但后来发现，很多情况下 API Key 本身没问题，平台也没挂，只是当前客户端和这个平台的接口"对不上"。
所以我现在更愿意把 WorkBuddy、Trae IDE 这类工具叫作 LLM 客户端。它们不是简单的"输入框 + 发送按钮"，而是负责把你的请求翻译成某个接口标准，再把返回结果解析成聊天内容。不同客户端的翻译方式、鉴权方式、流式解析方式、错误处理方式都不一样。只要有一环不兼容，就会报错。
换句话说，一个客户端上不行，不一定真的不行。除非返回的是 404、429 这类原因非常明确的错误，否则如果是 JSON 解析失败、响应格式异常、流式中断之类的模糊错误，很可能换一个客户端再试，就通了。
三、常见差异点：为什么同一套配置会"水土不服"
从我的经验看，LLM 客户端和 API 平台之间的差异主要集中在下面几个地方：
-
接口协议不同
有的平台是 OpenAI 兼容，有的是 Anthropic 风格，有的是 Gemini 原生，还有的是自定义协议。客户端如果只按 OpenAI 格式发请求，遇到 Anthropic 风格的接口就会失败。
-
URL 拼接方式不同
有的客户端要求填
https://api.xxx.com，它自己补/v1/chat/completions；有的要求你填完整路径；有的对末尾斜杠敏感；有的会把/v1重复拼接。结果就是同一个 URL，在 A 客户端能用，在 B 客户端 404。 -
鉴权头不同
OpenAI 常用
Authorization: Bearer xxx，Anthropic 常用x-api-key，有些平台用api-key，还有些要求自定义请求头。客户端如果写死了鉴权方式，就会 401 或 403。 -
模型 ID 映射不同
平台给的模型 ID 可能是
gpt-4o，也可能是openai/gpt-4o、gpt-4o-2024-08-06、ep-xxxx。客户端下拉菜单里如果没有，就需要手动填。填错一个字符都可能失败。 -
流式响应格式不同
很多客户端默认开启流式输出。如果平台返回的 SSE 格式和客户端预期不一致，就会在解析时崩掉，报 JSON 错误。关闭流式有时就能用。
-
高级参数不兼容
温度、Top P、Max Tokens、Presence Penalty 等字段，不同接口叫法不同。有的客户端会强行发送某些参数，平台不支持就报错。
-
网络与代理差异
有的客户端走系统代理，有的自带代理设置，有的直连。同一台电脑上，不同客户端可能走不同网络路径。
-
错误处理方式不同
平台返回一个 HTML 错误页，客户端却按 JSON 解析，于是报"Unexpected token <"。这其实不是 Key 的问题，而是客户端没有正确处理非 JSON 响应。
四、排查思路：先看错误码，再换客户端
遇到配置后不能用，我现在的排查顺序大概是：
| 错误现象 | 可能原因 | 优先动作 |
|---|---|---|
| 404 | URL 路径错、接口标准不对 | 检查 Base URL、补全路径、换接口标准 |
| 401/403 | API Key 错、鉴权头不对 | 检查 Key、换鉴权方式、看平台文档 |
| 429 | 限流、额度不足 | 等一会儿、换模型、换平台 |
| JSON 解析失败 | 返回了 HTML、SSE 格式不匹配、空响应 | 关闭流式、换客户端、用 curl 验证 |
| 流式中断 | SSE 不兼容、网络超时 | 关闭流式、调大超时 |
| 模型不存在 | 模型 ID 错 | 复制平台文档里的 ID |
最有效的一招是：先用 curl 或 Postman 直接请求接口。如果 curl 能通，说明 Key 和 URL 没问题，问题在客户端；如果 curl 也不通，再回头检查平台配置。
第二步就是换客户端。同一个 API Key，在 WorkBuddy 上报 JSON 解析错误，换到 Trae IDE 可能就正常；在 Trae IDE 上 404，换到 WorkBuddy 可能就通了。这不是玄学，而是不同客户端对接口的兼容策略不同。
五、我的"客户端矩阵"：WorkBuddy、Trae IDE、Claude Code、Antigravity
我已经碰到不少这种情况了：有的平台需要 WorkBuddy，有的平台需要 Trae IDE。所以，虽然这两个客户端目前的免费额度都不够用，但我都不打算删。它们已经产生了依赖，成了我排查和备用的一部分。
更进一步，Claude Code 似乎也要用起来，Antigravity 也类似，它们都支持外接 API Key。这意味着未来我可能会同时保留多个 LLM 客户端，形成一个"客户端矩阵"：
- WorkBuddy：适合某些自动导入的平台，配置简单；
- Trae IDE：对某些自定义接口兼容更好；
- Claude Code：适合命令行、Agent 场景；
- Antigravity：作为补充入口，支持外接 API Key；
- 再加上 curl / Postman 作为最终验证工具。
每个客户端都有自己的脾气，但也都有自己的用处。免费额度不够用没关系，关键是当某个平台在 A 客户端不行时，你还有 B 客户端可以试。多一个客户端，就多一种可能性。
六、总结
同样的 API Key、同样的 URL、同样的模型 ID，在不同 LLM 客户端上表现不同，这已经是很常见的现象。它不一定是 API Key 的问题，也不一定是平台的问题，而可能是客户端与接口之间的兼容性问题。
所以，当你配置完发现不能用时，先别急着删配置、换 Key、骂平台。先看错误码：404、429 这类明确错误优先解决；如果是 JSON 解析失败、流式异常、响应格式错误，不妨换一个客户端再试。WorkBuddy 不行就试 Trae IDE，Trae IDE 不行就试 Claude Code 或 Antigravity。说不定，换一个平台，它就通了。
在这个 LLM 工具爆发的阶段，多客户端并存不是折腾，而是一种务实策略。毕竟，能用的配置，才是好配置。
现在以api key 调用方式提供LLM算力的平台已经很多了，除了国内标准的一些经典的，
workbuddy, trae ide添加大模型的时候，会自动跳出来一些定义好了URL之类的，只等添加api key，下拉菜单选择模型，就能用了。
有些还是需要"自定义"，从URL，到api key， 到model ID和 高级设置的一系列参数。
但，有没有注意到，有一些自定义api key的平台，虽然设置固定，但同样的配置
有些 Workbuddy上能用（包括不同接口标准，不同URL长短都尝试），有些则各种配置都试了之后只能在Trae IDE上用。
出错的信息也五花八门。------这种情形就导致，有时候设置之后不能用，不一定是api key 自身的问题，可能跟所用的客户端有关系。------我觉得workbuddy 或 Trae IDE 这种叫作LLM的客户端似乎更合适一些。
所以，一个上面不行的时候，不一定是真的不行，除非返回的事404,429之类原因明确的，否则，如果是其它直接告诉是解析json之类的问题，也许就需要换一个平台再试试，说不定就行了。
我已经碰到不少这情形了：有的需要workbuddy，有的需要Trae IDE，所以，虽然这两个目前免费额度都不够用，但都不需要删，已经产生依赖了。Claude Code似乎也要用起来，Antigravity也类似，都支持外接api key的