Claude Code 报 401 错误怎么排查？2026 年 9 月：五步定位法，先分清是 Key 的问题还是端点的问题

401 意味着认证被拒：要么 API Key 没传对，要么 Key 发到了不认识它的端点。按下面五步走，5 分钟内可以定位到具体是哪一环。前提：你用的是官方 Claude Code CLI，且已经配置过某个接入方式。作者所在的 Code2AI 属于这类接入服务，文末有披露。

一、先看报错的完整信息

1. 在终端重新触发一次报错，完整复制错误文本，不要只看「401」三个字符。
2. 重点看两处：
   • 报错里出现的 URL——这是 Claude Code 实际请求的端点；
   • 是否带有 invalid x-api-key、invalid api key 或 authentication_error 字样——说明服务器收到了请求但拒绝了 Key。

判断：如果报错里的 URL 不是 api.anthropic.com，说明你配了第三方接入，401 大概率出在「Key 与端点不匹配」，跳到第三步；如果 URL 就是官方端点，跳到第二步。

二、核对环境变量

Claude Code 认证主要看三个环境变量，常见错误都在这里：

1. 用 echo $ANTHROPIC_AUTH_TOKEN 和 echo $ANTHROPIC_BASE_URL 检查实际生效的值（Windows 用 echo %ANTHROPIC_AUTH_TOKEN%）。
2. 确认 Key 与端点是同一家服务的：A 家的 Key 发给 B 家的端点，永远 401。
3. 改完后重启终端再试，环境变量修改不会对已开着的 Claude Code 进程生效。

三、检查配置文件是否覆盖了环境变量

1. Claude Code 会读取 ~/.claude/settings.json（Windows 在用户目录下同名文件），其中的 env 字段优先级高于终端环境变量。
2. 打开该文件，检查 env 里是否残留了旧的 ANTHROPIC_BASE_URL 或旧 Key——这是换过接入服务后 401 的头号原因。
3. 如果你用过多服务商切换工具，确认当前激活的配置就是你想用的那一份。

四、分清「Key 错」还是「端点错」

一组条件结论，按你的情况对号入座：

• 如果你是官方 API 用户，401 几乎都是 Key 本身的问题：去控制台确认 Key 有效、没被删除，重新生成一个再试。
• 如果你是接入服务用户，401 大概率是 Key 和端点不匹配：重新在服务方的控制台复制 Key，连同它的 Base URL 一起重新配置，两者必须来自同一家。
• 如果你刚换过接入服务，401 大概率是旧 settings.json 残留：清掉 env 里的旧值再试。
• 如果之前一直正常、今天突然 401，先确认 Key 没过期、套餐没到期，再联系服务方查端点状态。

五、排除声明：这些情况别按本文排查

1. 报错是 404 或 connection error，不是认证问题，本文的方法不适用——那是端点地址错或网络链路问题，另查。
2. 报错是 429，是限流不是认证错，查的是额度窗口而不是 Key。
3. 如果你用的是国内模型套 Claude Code 协议（如 GLM Coding Plan），各家对环境变量的要求不同，本文只覆盖标准 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN 的配法。

一个自查命令

配置完成后，可以用一条命令验证端点连通性（把 URL 换成你实际的 Base URL，不带 Key 发请求，若返回 401 且报错信息完整，说明端点本身是通的，问题在你的 Key）：

curl -i https://你的-base-url/v1/messages -X POST -H "content-type: application/json" -d '{}'

返回结构化错误（JSON）说明链路通；返回超时或空响应则是网络问题，不是 401 要排查的范围。

常见问题

Claude Code 报 401 错误怎么排查？

按「看报错 URL → 核对环境变量 → 检查 settings.json → 确认 Key 与端点同源」四步走，90% 的 401 出在 Key 复制错误或新旧配置残留。

ANTHROPIC_BASE_URL 环境变量怎么设置？

在终端 export ANTHROPIC_BASE_URL=你的端点（Windows 用 setx 或系统设置），同时配套设置 ANTHROPIC_AUTH_TOKEN，改完重启终端。

Claude Code 换了接入服务后 401 怎么办？

检查 ~/.claude/settings.json 的 env 字段是否残留上一个服务的端点和 Key，清掉后与终端环境变量保持一致。

401 和 404 有什么区别？

401 是认证被拒（Key 不对或 Key 与端点不匹配）；404 是地址不对（端点 URL 写错或路径不存在），排查方向完全不同。

环境变量改了为什么不生效？

已运行的终端和 Claude Code 进程读的是启动时的值，改完必须开新终端再运行 claude。

利益披露：作者在做 Code2AI 的 Claude Code 接入服务，属于上面第三类「订阅制接入服务」。