Claude Code 401 authentication_error 修复

Claude Code 提示认证失败（401 authentication_error）时，说明 ModelGate 网关拒绝了你的 API Key。按本文步骤逐项排查，一般几分钟内可以解决。

错误表现

启动 Claude Code 或发起请求时提示认证失败，例如：

Error: authentication_error
401: invalid x-api-key

错误含义

HTTP 401 authentication_error 表示认证信息无效：网关收到了请求，但无法通过 Key 验证你的身份。

最常见原因

API Key 填写错误、过期，或在后台已被停用
Key 中有多余的空格、换行或引号
ANTHROPIC_AUTH_TOKEN 环境变量未生效或名称写错
使用的 Key 不是 Claude 专用 Key（分组不对）

macOS / Linux 修复步骤

回到 ModelGate 后台 → 令牌管理，重新复制 Claude 专用 Key。
打开 ~/.claude/settings.json，确认 ANTHROPIC_AUTH_TOKEN 的值没有多余空格或换行：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://modelgate.app/"
  }
}

确认变量名是 ANTHROPIC_AUTH_TOKEN，不要写成 ANTHROPIC_API_KEY 等其他名称。
保存后重启 Claude Code，重新加载配置。

Windows 修复步骤

在 ModelGate 后台 令牌管理 重新复制 Claude 专用 Key。
打开 C:\Users\{用户名}\.claude\settings.json，确认配置与上方 macOS 示例一致。
若使用临时变量方式，PowerShell 中重新设置：

$env:ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxxxxxx"
$env:ANTHROPIC_BASE_URL="https://modelgate.app/"

关闭并重新打开终端（PowerShell），使环境变量生效。

curl 验证

在终端直接请求 ModelGate 接口，判断是网关问题还是客户端配置问题：

# macOS / Linux
curl https://modelgate.app/v1/messages \
  -H "x-api-key: 你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Windows PowerShell
curl.exe https://modelgate.app/v1/messages `
  -H "x-api-key: 你的Key" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

返回正常响应 → 网关没问题，问题在 Claude Code 本地配置，回到上面步骤重查。
仍返回 401 → Key 本身有问题，在后台重新创建 Key，并确认分组为 Claude 分组。

ModelGate 示例

以下请求使用 ModelGate 网关地址与 Claude 原生 Messages 协议：

curl https://modelgate.app/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"你好"}]}'

检查清单

Key 在后台存在且未停用，分组为 Claude 分组
ANTHROPIC_AUTH_TOKEN 名称与值完全正确，无多余空格
ANTHROPIC_BASE_URL 为 https://modelgate.app/（不要加 /v1）
curl 直接请求网关成功（排除了本地配置问题）
修改配置后已重启 Claude Code