一、先记住：Base URL、Endpoint、Protocol 是三件事#

很多配置界面只给你三个输入框：

1
Base URL
2
API Key
3
Model

于是很容易产生一种错觉：只要服务商说“OpenAI Compatible”，把地址填进去就一定能工作。

实际上真正请求至少包含三层：

1
Base URL
2
  + Endpoint
3
  + Request / Response Schema

例如：

1
https://api.example.com
2
+ /v1/chat/completions
3
+ Chat Completions JSON

和：

1
https://api.example.com
2
+ /v1/responses
3
+ Responses API JSON

虽然都可能属于“OpenAI 风格 API”，但它们不是同一个接口。

二、Chat Completions 与 Responses 不是换一个路径就行#

OpenAI 当前官方 Quickstart 已经以 Responses API 为主要示例：

1
const response = await client.responses.create({
2
  model: "gpt-5",
3
  input: "Hello"
4
});

而传统 Chat Completions 通常是：

1
{
2
  "model": "...",
3
  "messages": [
4
    {"role": "user", "content": "Hello"}
5
  ]
6
}

关键区别不只是字段名。

Responses 体系还会涉及：

• input / output items；
• 工具调用事件；
• reasoning item；
• streaming event 类型；
• response state；
• background / tool 等能力。

所以一个只实现 /v1/chat/completions 的第三方网关，即使能让普通聊天客户端工作，也不代表它能完整承载依赖 Responses API 的 Agent 客户端。

这类问题特别容易出现在 Coding Agent 上，因为 Agent 不只是“问一句、答一句”，还需要：

1
模型输出
2
→ 工具调用
3
→ 工具结果
4
→ 再传回模型
5
→ 继续推理

只要代理层在其中一步丢字段，就可能失败。

三、Anthropic Messages 又是另一套协议#

Claude Code 生态经常使用 Anthropic Messages 风格接口。

这意味着有些中转层会做：

1
Anthropic Messages
2
        ↓
3
协议转换器
4
        ↓
5
OpenAI / DeepSeek / Qwen endpoint

问题就出在“协议转换”不是简单改字段名。

例如 reasoning / thinking 数据如果需要在后续轮次原样带回，而代理层没有保留，就可能出现社区里常见的：

1
The content[].thinking ... must be passed back

所以看到 400 时，不要第一反应就认为 Key 错了。

400 通常更像是：请求已经到服务端了，但请求体语义不符合它的预期。

四、我会怎么快速判断 401 / 404 / 400 / 429#

1
curl -i https://your-api.example/v1/models \
2
  -H "Authorization: Bearer $API_KEY"

1
/v1/chat/completions

1
https://example.com/v1/chat/completions

1
https://example.com/v1/chat/completions/v1/chat/completions

1
时间
2
模型
3
并发数
4
输入 token
5
输出 token
6
请求间隔
7
Response Headers

五、所谓 OpenAI-compatible，应该拆成兼容矩阵#

Qwen 官方文档会明确说明可以通过 vLLM / SGLang 暴露 OpenAI-compatible API，这种“兼容”非常有价值，但依然需要看具体框架版本与功能。

我更建议把兼容性理解成一个矩阵：

这样就不会再用一句“支持 OpenAI API”概括所有能力。

六、最小可复现请求，比“换十个客户端试”更有效#

遇到问题时，我建议按这个顺序测。

1
curl https://api.example.com/v1/models \
2
  -H "Authorization: Bearer $API_KEY"

1
curl https://api.example.com/v1/chat/completions \
2
  -H "Authorization: Bearer $API_KEY" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "model":"your-model",
6
    "messages":[{"role":"user","content":"reply ok"}],
7
    "stream":false
8
  }'

七、建议给自己的 API 配置做一张“能力卡”#

如果你经常切模型，我建议不要只记录：

1
地址 + Key + 模型名

而是记录：

1
provider: example
2
base_url: https://api.example.com/v1
3
protocol:
4
  chat_completions: true
5
  responses: false
6
  anthropic_messages: true
7
features:
8
  streaming: true
9
  tools: true
10
  reasoning: partial
11
  vision: false
12
limits:
13
  rpm: unknown
14
  context: 262144
15
verified_at: 2026-08-15

这张小卡片会比收藏几十张“配置成功截图”有用得多。

尤其是免费 API、中转站和社区渠道变化非常快，最后核验时间一定要写。

八、社区教程最有价值的不是“照抄配置”，而是暴露真实故障#

NodeLoc 那篇 AI 工具自定义 API 教程整理里提到 401、404、429、流式中断等常见问题；LINUX DO 的大量实战帖则会暴露一些文档里不容易碰到的组合问题，例如：

• Codex + 第三方代理；
• Claude Code + OpenAI 风格模型；
• DeepSeek reasoning；
• 路由器二次协议转换；
• CC Switch / CPA 多层代理。

我认为这些社区内容最适合拿来做问题样本库，而不是当永远正确的配置说明。

因为客户端版本、模型 API、代理层实现都在快速变化。

真正稳的做法应该是：

1
社区发现问题
2
   ↓
3
官方文档确认协议
4
   ↓
5
最小请求复现
6
   ↓
7
抓请求 / 响应
8
   ↓
9
定位是哪一层不兼容

这套方法比“换一个神秘 Base URL 再试试”可靠得多。

参考资料#

• NodeLoc：整理了一个 AI 工具自定义 API 中文教程仓库，已经补到 47 篇
  https://www.nodeloc.com/t/topic/99597
• LINUX DO：Codex / DeepSeek 接入与协议转换相关社区讨论
  https://linux.do/t/topic/2128715
• OpenAI API Quickstart（Responses API）
  https://platform.openai.com/docs/quickstart/make-your-first-api-request
• OpenAI API：Data controls / endpoint differences
  https://platform.openai.com/docs/models/default-usage-policies-by-endpoint
• Qwen 官方文档：OpenAI API Compatibility
  https://qwen.readthedocs.io/zh-cn/latest/getting_started/quickstart.html
• NodeLoc 帖子提到的教程仓库
  https://github.com/18534516725/llm-api-setup-guides

本文从社区常见故障中提炼问题模型，再结合官方接口文档重新组织，不是对任意单篇社区教程的复制或同义改写。