几乎所有 401 都有四种原因，其中只有一种是“密钥错误”。另外三种情况下，密钥本身完全有效——因此重新创建密钥通常是在浪费精力。
错误
响应（HTTP 401）
{
"type": "error",
"error": { "type": "authentication_error",
"message": "invalid x-api-key" }
}原因和解决方法一览
| 原因 | 解决方法 |
|---|---|
| 针对该主机使用了错误的请求头 | Anthropic 读取 x-api-key；大多数兼容 OpenAI 的网关读取 Authorization: Bearer。同一个值放在错误的请求头中时，会被视为缺失。 |
| 残留的旧环境变量 | Shell 配置文件中遗忘的 ANTHROPIC_API_KEY 可能会覆盖你刚刚 export 的值。 |
| 更换基础 URL 却没有更换凭据 | 指向另一个主机不会让原供应商的密钥在那里变得有效。主机和凭据必须一起更换。 |
| 键中包含空格、换行或引号 | 从 PDF 或聊天中复制内容通常会带入不可见字符。请检查字符串长度。 |
检查环境中实际包含的内容
在更改任何内容之前，请在运行应用程序的同一个 shell 中查看变量。令人意外的是，许多情况都是同时设置了来自不同提供商的两组凭证。
conferir.sh
for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
printf '%-22s [%s] tamanho=%s\n' \
"$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done在应用程序之外测试凭证
直接请求可以区分“主机拒绝密钥”和“应用程序没有发送密钥”。如果 curl 能正常工作而代码不行，问题就不在凭证。
testar.sh
curl -s -o /dev/null -w 'status=%{http_code}\n' \
"$ANTHROPIC_BASE_URL/v1/models" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host区分 401、403 和 402
401 是“我不知道你是谁”：凭证未被接受。403 是“我知道你是谁，但你无权操作”：已完成身份验证，但没有权限。402 是“我知道你是谁，但余额不足”。只有 401 需要通过修改凭证来解决。
如果你通过 Kunavo 调用
Kunavo 同时支持在 Authorization: Bearer 和 x-api-key 中读取 sk-kn- 密钥，base URL 则是网站源地址，后面不能带任何路径。使用 Claude Code 时，请使用 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL，因为该令牌不依赖 ANTHROPIC_API_KEY 所要求的一次性批准，并明确移除 ANTHROPIC_API_KEY——该变量中的旧值是会话看似已配置却仍被拒绝的最常见原因。 身份验证步骤详见 身份验证文档.
常见问题
重新创建密钥能解决问题吗？
只有在密钥确实被撤销时才可以。其他三个最常见的原因——错误的请求头、旧变量、被替换的 base URL——即使换了新密钥，结果也会完全一样。
401 可能是余额不足吗？
不会。余额不足对应 402，并且消息会提到额度。401 始终与身份有关。
curl 能正常工作，但我的代码失败了。为什么？
几乎总是因为代码读取了另一个环境变量，或者运行在 export 未传入的另一个 shell/container 中。请在进程内部打印经过掩码处理的凭证进行确认。