常见问题

出现401报错 / 鉴权失败？

先核对协议与 Header 的对应关系：Anthropic 用 x-api-key，OpenAI / Gemini 用 Authorization: Bearer，Gemini 原生端点也接受 x-goog-api-key。再确认 Key 复制完整（sk- 开头、无多余空格）且未在控制台删除；另外注意 base_url 写法：OpenAI SDK 需要带 /v1，Anthropic SDK 不带。

用 OpenAI 格式调 Claude 报错 / 变贵 / 效果差？

Claude 模型请务必使用 Anthropic 原生协议（/v1/messages）调用，Claude Code 等 Agent 工具必须按 Anthropic 协议配置。用 OpenAI 兼容格式调用 Claude 可能导致 prompt cache、thinking 等能力丢失（成本更高、能力降级），仅适合简单对话场景；/v1/responses 不支持 Claude / Gemini（会返回 400）。

模型不可用？

请先用 GET /v1/models 拉取实时列表，核对模型 ID 拼写（全小写，留意 - 与 . 的区别）。同时确认端点与模型的对应关系。

超时 / 首字慢？

Opus / Fable 这类大模型在思考阶段首字延迟数秒到数十秒属正常，不代表请求失败。生产环境建议加 "stream": true 用流式提升体感，并把客户端读超时调大（服务端支持长达 600 秒的响应）。

Key 安全

放入环境变量或密钥管理服务，切勿硬编码、提交到 Git，或打包进前端 / 客户端对外分发。若怀疑 Key 已泄露，立即在控制台删除该 Key 并新建替换。