用 curl 排查 OpenAI-compatible API 连接失败：401、403、404、usage 缺失怎么定位
最近接一些 OpenAI-compatible API 的时候，我发现一个问题挺常见：
配置看起来都填了，但客户端就是跑不起来。
比如 Cursor、Cline、Continue、Open WebUI 这类工具里，Base URL、API Key、Model ID 都填了，结果一请求就报错。
很多时候，问题不是模型本身，而是配置链路里某一段没通。
我现在一般按这个顺序排查：
Base URL → API Key → Model ID → 返回格式 → usage 字段 → 稳定性
1. 先确认 Base URL
很多 OpenAI-compatible API 会使用 /v1 路径：
https://xxx.com/v1
但实际平台给你的地址可能有几种：
https://xxx.com
https://xxx.com/v1
https://xxx.com/openai/v1
最容易出错的是重复 /v1：
https://xxx.com/v1/v1
所以第一步别急着进客户端，先用 curl 测一下：
curl https://xxx.com/v1/models \
-H "Authorization: Bearer sk-xxxx"
如果返回的是 JSON，说明地址和 Key 至少有一部分是通的。
如果返回的是 HTML、登录页、404 页面，先别查模型，先查 URL。
2. 区分 401 和 403
401 一般是 Key 问题。
常见原因：
Key 复制错了
Key 过期了
Authorization header 格式不对
用了别的平台的 Key
403 一般更像权限问题。
比如：
Key 存在，但没有当前模型权限
用户组没有分配模型
余额不足
IP 或区域限制
某些辅助接口不允许访问
这里有个坑：有些网关的核心 chat 请求能通，但是 /models 或其他辅助接口会 403。
这种情况不能直接判断整个 API 不可用，要看核心请求是否能成功。
3. 再测 chat/completions
模型列表能返回，不代表某个模型一定能调。
可以发一个最小请求：
curl https://xxx.com/v1/chat/completions \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "ping"}
],
"max_tokens": 8
}'
如果这里返回 404 或 model not found，通常是 Model ID 不存在或当前 Key 没权限。
这类错误在 API 网关里很常见。Key 是有效的，但模型没分配。
4. 检查返回格式
正常的 OpenAI-compatible chat 返回，大概会有这些字段：
{
"id": "...",
"object": "chat.completion",
"choices": [
{
"message": {
"role": "assistant",
"content": "pong"
}
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 2,
"total_tokens": 12
}
}
客户端一般会依赖这些字段：
choices
message
content
usage
如果接口返回的是 HTML，或者 JSON 结构差异很大，客户端就可能解析失败。
5. usage 字段最好不要忽略
很多人只看能不能返回内容，不看 usage。
但 usage 很重要，因为它关系到后面对账。
比较基础的字段是：
prompt_tokens
completion_tokens
total_tokens
如果这些都没有，接口也可能能用，但你很难核对这次请求到底消耗了多少。
有些接口还会返回缓存相关字段，比如：
prompt_tokens_details.cached_tokens
cache_read_input_tokens
cache_creation_input_tokens
这个只能说明接口返回了缓存信号，不能直接证明底层缓存策略完全可靠。
6. 稳定性要多测几次
一次请求成功不代表稳定。
我一般至少看 5 次轻量请求：
成功次数
平均延迟
最大延迟
中位数延迟
有没有长尾波动
大概可以这么看：
2 秒以内：体验较好
2 - 3.5 秒：正常
3.5 - 6 秒：有轻微延迟
6 秒以上：需要关注
如果 5 次都成功，但有一次特别慢，我不会直接判定不可用。
更合理的判断是：能用，但存在长尾延迟，高成本任务前最好再测。
7. 一个简单排查清单
如果 OpenAI-compatible API 接不进去，可以按这个顺序查：
1. Base URL 是否正确
2. 是否重复 /v1
3. API Key 是否有效
4. 当前 Key 是否有模型权限
5. Model ID 是否真实可调用
6. 返回是不是 JSON
7. choices/message/content 是否存在
8. usage 字段是否返回
9. 轻量请求是否稳定
10. 客户端配置是否和接口路径一致
8. 我后面做了一个小工具
手动 curl 可以解决问题，但每次都查这些字段比较麻烦。
所以我做了一个开源小工具，用来跑这些轻量检查：
AI API Doctor
它主要检查 Base URL、API Key、Model ID、返回格式、usage 字段、缓存信号、模型身份信号和稳定性采样。
它不是用来证明模型真假，也不是长期监控，只是第一次接入前的 preflight check。
开源仓库：
https://github.com/JustinXai/ai-api-doctor-site
如果只是自己排查，也可以不依赖工具，按上面的 curl 步骤一步步查。
总结
OpenAI-compatible API 连接失败时，别一上来就怀疑模型。
更常见的问题是：
Base URL 写错
/v1 重复
Key 没权限
Model ID 不存在
返回格式不标准
usage 字段缺失
延迟不稳定
先用最小请求把链路拆开测，比在客户端里反复改配置更快。
