Claude API 401 Unauthorized 排查教程：Anthropic API Key、环境变量、Header 与代理网关配置

在接入 Claude / Anthropic API 时，很多开发者会遇到：

{
  "type": "authentication_error",
  "message": "invalid x-api-key"
}

或者只看到一个简单的：

401 Unauthorized

直觉上很容易判断为“API Key 填错了”。但在实际项目里，Claude API 返回 401 并不一定代表 Key 本身无效，也可能是：

• 环境变量没有生效；
• .env 没有被加载；
• Docker 容器里没有拿到 Key；
• Header 写成了 OpenAI 风格；
• Base URL 和 Key 类型不匹配；
• 代理、网关、中转服务转发时丢了 Header；
• Claude Code / 插件使用的 OAuth token 过期。

更合理的排查方式是：先用最小 curl 请求验证 Key，再沿着 SDK、环境变量、Docker、代理网关逐层排查。

说明：本文中的 “Claude API” 主要指 Anthropic 官方 API 以及部分兼容调用场景。如果你使用的是 ClaudeAPI 等第三方 Claude API 兼容接入服务平台，需要以对应平台的 Base URL、Key 类型和文档为准。第三方平台不是 Anthropic 官方服务。

1. 先明确：Claude API 401 代表什么？

HTTP 401 Unauthorized 的含义是：服务端没有识别到有效的认证凭据。

它不等价于“Key 一定填错了”。

常见原因可以分成几类：

所以排查 Claude API 401 的核心不是马上换 Key，而是确认：

当前请求到底发到了哪个 Endpoint？带了什么认证 Header？由谁来校验这个凭据？

2. 常见 401 报错文案与排查方向

不同工具返回的 401 文案不完全一样，可以先通过错误信息判断大致方向。

如果错误明确是：

OAuth token has expired

通常不是换 Anthropic API Key 能解决的，而是应该重新登录 Claude Code 或刷新 OAuth token。

如果错误是：

invalid x-api-key

则更应该检查 Anthropic API Key、Header 和请求链路。

3. 第一步：用 curl 直连 Anthropic 官方 API

在排查 SDK、框架、代理或部署平台之前，建议先用最小请求直接验证 Key 是否可用。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

这里有三个关键 Header：

x-api-key: YOUR_ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

测试结果可以这样判断：

注意：不要把完整 API Key 打印到日志、群聊、Issue、截图或网页里。排查时最多保留前几位和后几位，例如：

sk-ant-****abcd

4. 如果 curl 直连也 401，先检查 API Key 本身

如果直接请求 Anthropic 官方 API 也返回 401，尤其是提示：

invalid x-api-key

那就可以优先检查 Key 本身。

4.1 检查 Key 是否复制完整

常见问题包括：

• 开头或结尾少复制字符；
• 前后多了空格；
• .env 中多了引号、换行或不可见字符；
• 从网页或文档复制时混入特殊字符；
• 实际运行环境还在使用旧 Key。

可以检查环境变量是否存在，但不要打印完整 Key：

printenv | grep ANTHROPIC

如果只想确认变量长度，可以使用：

echo "$ANTHROPIC_API_KEY" | wc -c

日志中建议只输出脱敏结果，例如：

ANTHROPIC_API_KEY=sk-ant-****abcd

不要输出完整值。

4.2 确认 Key 类型没有拿错

不同认证信息不能混用。

例如：

• 把第三方代理 Key 发到 https://api.anthropic.com；
• 把 Anthropic 官方 Key 填进只接受平台代理 Key 的服务；
• 把 Claude.ai 登录状态当成 API Key 使用；

这些都可能导致 401。

4.3 什么时候需要重新生成 Key？

以下情况可以考虑新建或轮换 Key：

• curl 直连官方 API 仍然提示 invalid x-api-key；
• 怀疑 Key 已泄露；
• Console 中找不到该 Key；
• Key 已被撤销；
• 多个环境共用旧 Key，配置混乱；
• 生产环境需要做凭据轮换。

但下面这些场景，不建议第一时间换 Key：

• curl 直连官方 API 成功；
• 只有某个 Docker 容器失败；
• 只有某个代理、Router 或中转平台失败；
• 只有 Claude Code 或插件失败；
• 错误明确提示 OAuth token 过期。

5. 如果 curl 成功，但项目仍然 401，重点查环境变量

这是实际项目中最常见的情况：

直连 API 可以成功，但应用一运行就报 401。

这种情况下，Key 本身通常没问题，问题更可能出在应用没有读取到正确的 Key，或者 SDK 没有按预期发送 Header。

6. Node.js 项目接入 Anthropic SDK 示例

Node.js 中可以这样初始化 Anthropic 客户端：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 32,
  messages: [
    {
      role: "user",
      content: "ping",
    },
  ],
});

console.log(message.content);

重点检查：

process.env.ANTHROPIC_API_KEY

是否真的有值。

常见问题：

• .env 文件没有被加载；
• 服务启动前没有设置环境变量；
• 修改 .env 后没有重启服务；
• .env.local 覆盖了 .env；
• .env.production 覆盖了本地配置；
• 系统环境变量优先级更高；
• 本来要用 Anthropic SDK，却套用了 OpenAI SDK 的配置方式。

如果你使用 dotenv，需要确保启动入口里加载了配置：

import "dotenv/config";

或者：

import dotenv from "dotenv";

dotenv.config();

然后再读取：

console.log(Boolean(process.env.ANTHROPIC_API_KEY));

不要直接输出完整 Key。

7. Python 项目接入 Anthropic SDK 示例

Python 中可以这样写：

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=32,
    messages=[
        {
            "role": "user",
            "content": "ping"
        }
    ],
)

print(message.content)

如果下面这行返回 None 或空字符串：

os.environ.get("ANTHROPIC_API_KEY")

那么 SDK 实际拿到的就是无效凭据，最终报 401 是正常的。

可以先做一个简单检查：

import os

key = os.environ.get("ANTHROPIC_API_KEY")
print(key is not None, len(key) if key else 0)

仍然不要打印完整 Key。

8. Docker / Docker Compose 中的环境变量排查

很多时候，宿主机有环境变量，不代表容器里也有。

先在宿主机检查：

echo "$ANTHROPIC_API_KEY"

再进入容器检查：

docker compose exec app printenv | grep ANTHROPIC

查看应用日志：

docker compose logs app --tail=100

如果你修改了 .env 或 docker-compose.yml，可能需要重新创建容器：

docker compose up -d --force-recreate

一个常见的 docker-compose.yml 写法如下：

services:
  app:
    image: your-app:latest
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

或者：

services:
  app:
    image: your-app:latest
    env_file:
      - .env

需要注意：

• .env 文件是否在 docker compose 命令执行目录下；
• 变量名是否拼写一致；
• 容器是否重新创建；
• 镜像内是否还有旧配置；
• 应用是否在启动时读取环境变量，而不是运行中动态读取。

9. CI/CD 和云部署平台中的 Secret 生效问题

在 Vercel、Railway、Render、Cloudflare Worker、GitHub Actions 等环境中，也经常出现：

控制台里已经改了 Secret，但线上应用仍然报 401。

排查方向：

• Secret 名称是否为 ANTHROPIC_API_KEY；
• 当前环境是 Preview、Production 还是 Development；
• 修改 Secret 后是否重新部署；
• 构建时变量和运行时变量是否区分；
• 是否存在多个同名变量互相覆盖；
• 应用实例是否仍在使用旧版本。

如果 curl 本地直连成功，而线上失败，通常优先检查部署平台环境变量，而不是先换 Key。

10. Anthropic 官方 API Header 写法：不要直接套 OpenAI 格式

Anthropic 官方 API 常见 Header 是：

x-api-key: YOUR_ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

而不是：

Authorization: Bearer sk-xxx

很多开发者从 OpenAI SDK 或 OpenAI-compatible API 迁移过来，会习惯性使用：

Authorization: Bearer YOUR_KEY

但对 Anthropic 官方 API 来说，通常应该使用 x-api-key。

当然，如果你调用的是某些 OpenAI 兼容代理、中转平台或第三方 Claude API 兼容服务，它们可能要求：

Authorization: Bearer YOUR_PROXY_KEY

这属于代理平台自己的规则，不能直接套到 Anthropic 官方 API 上。

因此要先确认：

另外，anthropic-version 虽然不是 API Key，但调用 Anthropic API 时通常需要带上。它缺失或错误时不一定表现为 401，但会增加排查复杂度。

11. Base URL 和 Key 类型必须匹配

排查 Claude API 401 时，必须确认 Endpoint 和 Key 是否属于同一套体系。

错误示例：

Anthropic 官方 Key + 第三方代理 Base URL

或者：

第三方代理 Key + https://api.anthropic.com

这两种都可能导致 401。

如果你使用的是兼容 Claude API 的第三方服务，需要同时确认：

• Base URL；
• Header 名称；
• Key 类型；
• 模型名；
• 请求路径；
• 是否兼容 Anthropic Messages API；
• 是否要求 OpenAI-compatible 格式。

具体以对应平台最新文档为准。

12. 代理、Router、Nginx、Worker 导致 Header 丢失

如果请求链路中经过了以下组件，也可能出现 401：

• Nginx；
• Cloudflare Worker；
• API Gateway；
• 自建网关；
• LiteLLM；
• LibreChat；
• Claude Code Router；
• OpenAI-compatible proxy；
• 其他中转服务。

这种情况下，可能不是 Key 错，而是 Header 没有被正确转发。

需要重点检查：

• 请求是否发到了正确的 Base URL；
• 代理是否读取到了 x-api-key；
• 代理是否把 x-api-key 继续转发给上游；
• 网关是否过滤了自定义 Header；
• 代理要求的是 Authorization: Bearer，但你传了 x-api-key；
• 代理要求的是 x-api-key，但你传了 Authorization；
• 日志里读取到的是新 Key 还是旧环境变量；
• 前端页面填的 Key 和后端 .env 中的 Key 是否一致。

可以使用 curl -v 查看请求链路：

curl -v https://your-proxy.example.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 32,
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

如果代理层有日志，建议只记录：

• Header 是否存在；
• 脱敏后的 Key 前后几位；
• 请求的 Base URL；
• 上游返回状态码；
• 上游错误文案。

不要记录完整 Key。

13. Claude Code 报 401：可能不是 API Key 问题

如果你使用的是 Claude Code、VS Code 插件或桌面工具，401 可能来自 OAuth，而不是 Anthropic API Key。

典型错误：

{
  "type": "authentication_error",
  "message": "Invalid authentication credentials"
}

或者：

{
  "type": "authentication_error",
  "message": "OAuth token has expired. Please obtain a new token or refresh your existing token."
}

这类情况可以优先尝试：

• 重新登录 Claude Code；
• 刷新或重新获取 OAuth token；
• 更新 CLI 或插件版本；
• 清理本地过期认证状态；
• 确认工具使用的是 OAuth、订阅登录，还是 API Key。

需要注意：

Claude.ai 能正常登录，或者 Claude Pro / Max 订阅仍然有效，并不等于 Anthropic API Key 一定可用。

它们属于不同的认证体系，不能直接互相替代。

14. 401、403、429、400 不要混在一起排查

不是所有 Claude API 报错都应该归因到 Key。

例如：

• 模型名写错，更可能是 400；
• 请求 JSON 格式错误，更可能是 400；
• 权限或访问范围不满足，可能是 403；
• 请求太频繁，可能是 429；
• Header 缺失或 Key 无效，才优先看 401。

15. 推荐排查流程

遇到 Claude API 401，可以按下面顺序排查：

第一步：保存完整错误文案

先确认具体是：

invalid x-api-key

还是：

Invalid authentication credentials

或者：

OAuth token has expired

不同文案对应的方向不同。

第二步：确认调用目标

确认你调用的是：

• Anthropic 官方 API；
• 第三方 Claude API 兼容平台；
• OpenAI-compatible proxy；
• Claude Code；
• VS Code 插件；
• 自建 API 网关；
• Docker 内部服务。

第三步：curl 直连官方 API

使用最小 curl 请求验证 Key：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

如果这一步成功，Key 本身通常不是主要问题。

第四步：检查应用环境变量

重点检查：

printenv | grep ANTHROPIC

Node.js：

console.log(Boolean(process.env.ANTHROPIC_API_KEY));

Python：

import os
print(os.environ.get("ANTHROPIC_API_KEY") is not None)

不要打印完整 Key。

第五步：检查 Docker / 部署平台

Docker：

docker compose exec app printenv | grep ANTHROPIC
docker compose logs app --tail=100
docker compose up -d --force-recreate

部署平台：

• Secret 是否设置在正确环境；
• 修改后是否重新部署；
• 构建时变量和运行时变量是否一致；
• 是否有旧实例未重启。

第六步：检查 Header

Anthropic 官方 API 通常使用：

x-api-key: YOUR_ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

不要误用：

Authorization: Bearer YOUR_KEY

除非你调用的代理平台明确要求这种格式。

第七步：检查 Base URL 与 Key 类型

确认：

https://api.anthropic.com

对应的是 Anthropic Console API Key。

代理平台地址对应的是代理平台自己的 Key 或文档要求的认证方式。

不要混用官方 Key 和第三方 Key。

第八步：检查代理和网关转发

如果经过 Nginx、Worker、Gateway、Router 或中转平台，确认：

• Header 没被过滤；
• Key 没被替换；
• 上游地址正确；
• 日志中使用的是新配置；
• 前端和后端配置一致。

第九步：Claude Code 单独看 OAuth

如果是 Claude Code 报：

OAuth token has expired

优先重新认证，而不是替换 Anthropic API Key。

16. 总结

Claude API 返回 401，并不一定是 Key 填错。

更高效的定位思路是：

1. 先看错误文案；
2. 再确认调用目标；
3. 用 curl 直连 Anthropic 官方 API 建立基准；
4. curl 成功则查 SDK、环境变量、Docker、部署平台；
5. curl 失败再重点检查 Key 本身；
6. 经过代理时检查 Header、Base URL 和 Key 类型；
7. Claude Code 报错时注意区分 OAuth 和 API Key。

只要先用最小请求确认 Key，再沿请求链路逐层排查，大多数 Claude API 401、invalid x-api-key、环境变量不生效和代理鉴权失败问题都能较快定位。