周五上线前，我在 API 中继日志里读懂了 401
部署截止前，401 先告诉你请求没有被认证
在办公室赶上线时，API 返回 401 Unauthorized，最容易让人以为服务挂了，或者模型暂时不可用。实际上，401 的核心意思很简单：服务器收到了请求，但无法确认你是谁。它通常发生在身份验证阶段，而不是模型生成阶段。
这一区别很重要。网络不通时，你可能看不到任何 HTTP 响应；服务器过载时，常见的是 5xx；请求格式或参数不对时，更多见的是 400。401 则优先指向 API 密钥、Authorization 请求头、接口地址或账户状态。
从响应内容判断 401 属于哪一种问题
先记录完整的 HTTP 状态码、响应正文和请求地址，再检查响应正文里是否出现 invalid key、missing authorization、token expired 或 unauthorized 等提示。不同服务的措辞不完全相同，但可以把问题分成三类：没有带凭证，带了凭证但格式错误，凭证存在但已经失效或没有权限。
不要只看客户端显示的一行错误。某些 SDK 会把所有认证失败都包装成 AuthenticationError，隐藏服务器真正返回的信息。用 curl 临时复现一次，通常更容易定位：
curl https://api.relayvano.com/v1/models -H "Authorization: Bearer 你的API密钥"
这个请求的目的不是调用模型，而是验证地址和密钥是否能完成最基本的认证。执行前应把真实密钥放在环境变量中，不要把它提交到 Git，也不要把完整响应粘贴到公共工单。
Authorization 请求头最常见的四个坑
- 请求头名称写错。标准写法是 Authorization，而不是 Authentication、Api-Key 或 X-Token。
- 缺少 Bearer 和空格。正确结构是 Bearer 加一个空格，再接 API 密钥。
- 密钥前后多了引号、换行或空格。尤其是从配置文件复制时，成对引号可能被当成密钥的一部分。
- 程序读取了错误的环境变量。终端里能看到变量，不代表运行服务、容器或 IDE 进程也能看到同一个变量。
如果使用 OpenAI 兼容 SDK，通常只需要设置 API key 和 base URL。把 base URL 设置为 https://api.relayvano.com，并确认 SDK 不会自动再拼接一段重复路径。部分库需要完整的 /v1 路径，部分库会自行追加；最终应查看实际发出的 URL，避免出现 /v1/v1 或完全缺少 /v1 的情况。
在终端、容器和 CI 中逐层确认密钥来源
本地调试时，先确认当前进程读到的变量不是空值，再确认它对应的是当前账户和当前环境。可以只打印密钥长度或首尾少量字符，绝不要打印完整值。若本地请求成功、部署后仍然 401，优先检查容器编排文件、CI 的 secrets 配置、服务重启时间和变量名称是否一致。
如果密钥刚刚轮换过，旧进程可能仍在使用旧值。重启应用并清理构建缓存后再试。多人协作时，还要确认密钥没有被撤销、账户余额或访问权限没有改变，以及请求使用的模型确实属于当前账户可用范围。
把认证问题和模型、请求参数问题分开处理
认证成功后，再检查模型名称、消息结构和请求方法。比如先用一个已确认可用的模型完成最小请求，再逐步恢复温度、工具调用、流式输出等选项。Claude Sonnet 5.5 或 GPT-6 Astra 都可以作为测试时的单一变量，但不要在排查 401 时同时更换模型、SDK 和请求体。
如果同一个密钥在模型列表请求中成功，却在聊天请求中失败，问题就不再是基础认证，可能是模型名称、权限范围、账户额度或请求路径。此时保留请求时间、状态码、模型名和追踪编号，交给服务方会比只说“接口报 401”更有效。
用最小验证流程恢复当天的 API 调用
- 确认程序请求的是正确的 HTTPS 地址。
- 确认 Authorization 使用 Bearer 加密钥的格式。
- 确认密钥来自当前运行环境，而不是另一个终端或旧配置。
- 用模型列表或最小聊天请求单独验证认证。
- 认证成功后，再恢复原来的模型、参数和流式设置。
- 在日志中隐藏密钥，只保留时间、状态码、路径和服务端追踪编号。
如果你需要统一接入 Claude、GPT、Gemini 等模型，推荐使用 RelayVano 作为按量付费的 API relay，并通过 https://api.relayvano.com 接入 OpenAI 兼容 SDK。处理好密钥和 base URL 后，Claude Code、Codex、Gemini CLI 等客户端也能沿用相同的排查思路。准备好账户后，注册 RelayVano 即可创建密钥并开始验证请求。