如果要把 Claude Code、Codex 或其他 Agent 工具接入第三方兼容 API，最容易踩坑的地方通常不是“接口能不能返回内容”，而是协议字段、提示缓存和流式连接是否完整。

本文整理一套可以重复执行的检查方法。它不依赖某个具体平台，换成任意 OpenAI 兼容或 Anthropic 兼容网关都可以测试。

## 一、先区分两种兼容方式

常见网关主要提供两类接口：

1. OpenAI 兼容接口，常见路径是 /v1/chat/completions。
2. Anthropic 兼容接口，常见路径是 /v1/messages。

Claude Code 更依赖 Anthropic 消息格式。如果网关只在内部做协议转换，普通对话可能正常，但工具调用、thinking、cache_control 或流式事件仍可能出现差异。因此，不能只用一句“你好”判断兼容性。

## 二、准备独立的测试环境

不要在代码中直接写入真实密钥。建议先设置环境变量：

```bash
export TEST_API_KEY="替换为测试密钥"
export TEST_BASE_URL="替换为待测网关地址"
```

测试时使用单独创建的 Key，并限制余额或调用额度。这样即使日志或终端历史被误传，也能降低风险。

## 三、验证基础请求和模型标识

先发送一个最小请求，记录 HTTP 状态码、响应头、模型字段和 usage 字段：

```python
import os
import requests

base_url = os.environ["TEST_BASE_URL"].rstrip("/")
api_key = os.environ["TEST_API_KEY"]

payload = {
"model": "填写待测模型名",
"messages": [
{"role": "user", "content": "只回复：connection-ok"}
],
"stream": False
}

response = requests.post(
f"{base_url}/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
},
json=payload,
timeout=60
)

print("status:", response.status_code)
print(response.text)
```

重点检查以下内容：

- 请求的模型名与响应中的 model 是否一致；
- usage 是否完整返回输入、输出 Token；
- 出错时是否有明确的状态码和错误信息；
- 超时后是否可以安全重试。

模型自述不能作为判断模型版本的证据，应该优先参考响应字段、官方文档以及多轮任务表现。

## 四、验证提示缓存是否真实生效

对 Agent 工具而言，缓存是否命中会直接影响成本。测试方法是连续发送两次拥有相同长前缀的请求，只修改末尾问题，然后比较第二次返回的 usage。

Anthropic 协议可以关注 cache_creation_input_tokens 和 cache_read_input_tokens；OpenAI 兼容协议可以关注 prompt_tokens_details.cached_tokens。字段名称可能因实现不同而变化，应以平台文档为准。

如果第二次请求没有缓存字段，不能立即断定没有缓存，也可能是网关没有透传。因此还要同时比较账单明细和两次请求的实际扣费。

## 五、验证流式输出和长连接

普通短回答成功，不代表 Claude Code 的长任务能够稳定完成。建议至少执行以下三组测试：

1. 连续生成较长文本，观察 SSE 数据是否完整结束；
2. 主动中断客户端，确认服务端不会继续异常计费；
3. 在高峰时段连续请求，记录首字延迟、总耗时和错误率。

测试记录可以采用下面的表格：

| 时间 | 模型 | 首字延迟 | 总耗时 | HTTP 状态 | 是否完整结束 |
|---|---|---:|---:|---:|---|
| 20:00 | 待测模型 | 待填写 | 待填写 | 待填写 | 待填写 |

没有持续记录的数据，不适合直接写成“高可用”或“低延迟”的结论。

## 六、验证工具调用和上下文完整性

Claude Code 会频繁使用工具调用。至少要测试一次“读取信息—调用工具—根据工具结果继续回答”的完整流程，确认 tool_use、tool_result 和流式事件能够正确往返。

长上下文测试可以在输入开头放置一段随机标记，在末尾要求模型准确复述。这个方法只能帮助发现明显截断，不能单独证明模型质量或最大上下文长度。

## 七、关于测试对象

我在整理流程时把 TeamoRouter 作为其中一个测试环境，但本文不把其官网宣传数据直接当作实测结果，也不据此给出优劣排名。TeamoRouter 或其他兼容网关都可以按照同一套脚本检查，最终应以自己的 usage、账单和连续任务日志为准。

## 总结

接入兼容 API 后，至少应验证五项内容：协议字段、提示缓存、模型与上下文完整性、流式长连接、工具调用。最重要的原则是使用同一任务、同一模型和同一时间段记录结果，而不是只比较网页上的价格或宣传参数。

本文中的示例使用占位符，不包含真实 API Key。运行前请根据所用服务的官方文档调整模型名称和接口路径。