“兼容 API”还需要验证什么

01不要只看营销标签

一个服务支持 OpenAI 风格接口，并不能直接证明它适用于 Claude Code。先确认当前接入方式需要的 API 格式、端点、模型标识与鉴权方式。

Claude Code 通过 Anthropic 格式入口连接时，需要网关正确处理 Messages 相关行为。实际兼容范围应对照官方网关协议参考和网关当前实现。

02最小兼容性测试矩阵

用一组固定的输入重复验证，确保接口不仅能返回文本，也能完整支撑代理工作流。

• 普通请求：短输入能返回结构正确的响应。
• 流式请求：事件顺序、增量文本与结束事件完整。
• 工具调用：参数、调用标识和工具结果能够往返。
• 多轮上下文：历史消息与工具结果能继续使用。
• 请求头：版本、beta 能力和认证按说明转发。
• 失败响应：限流、超时、鉴权失败能传递给客户端。

03流式链路每一跳都要检查

客户端、边缘代理、网关和上游任何一层发生缓冲或超时，都可能造成“接口能返回，但长任务中断”。测试时同时观察首个事件、事件间隔与完整结束。

连接断开后的自动重试需要考虑重复计费、重复工具调用和幂等性。仅用一次 curl 成功不能代表长会话已经稳定。

04维护一个小而稳定的回归集

升级 Claude Code、切换模型或修改网关后，重跑相同的一组文本、工具调用与错误场景。把实际版本与结果记录下来，兼容性结论才有可比较的依据。

05一个最小工具调用用例

准备只返回固定字符串的测试工具，例如读取一段测试配置。让模型调用它，再把结果回传给模型完成总结。整个过程应只访问测试数据。

检查第一段响应中工具标识与参数是否完整，第二段请求是否保留相同标识，最终响应是否正常结束。只返回普通文本的接口可能通过聊天测试，却在这里暴露协议问题。

• 无工具的短对话用于建立基线。
• 单个工具调用验证最小往返。
• 流式工具参数验证增量拼接。
• 取消请求验证连接与上游任务清理。
• 限流响应验证客户端能获得清楚的错误。