Claude Code 报 401 认证失败怎么解决？六条认证类报错的分流表
认证类报错是 Claude Code 里最容易「治错病」的一族。它们长得都差不多，都在说「你没通过」，但成因分散在完全不同的地方：环境变量、订阅登录、组织策略、系统钥匙串、云厂商凭证。
照着搜到的第一条办法试，试对了是运气。这篇按官方错误参考把这一族拆开，先给分流方法，再给每条的处理。
一、先跑 /status，这是分流的起点
认证问题的第一动作不是改配置，是先搞清楚当前这个会话到底在用哪套凭证。
官方在几乎每一条认证类报错的处理里都提到了 /status——它会显示活跃的凭证来源。这一步的价值在于：Claude Code 的凭证有好几个来源，它们之间有优先级，而你以为在用的那个，未必是它实际在用的那个。
最常见的错位是：你已经用订阅登录过了，但环境里还留着一个 ANTHROPIC_API_KEY，于是它走的是 API key 那条路——而那个 key 可能早就失效或被撤销了。
所以顺序是：
/status看当前用的是什么- 对照下面的表找到你的报错
- 按那一条处理
二、六条报错的分流表
| 报错原文 | 说的是什么 | 官方给的处理 |
|---|---|---|
API Error: 401 Invalid authentication credentials | API 拒绝了凭证 | /status 看活跃凭证；显示 API key 就去控制台轮换，或 unset ANTHROPIC_API_KEY；只显示登录就 /login；用网关的去修网关侧凭证 |
Invalid API key | key 本身被拒 | 查拼写、查是否被撤销；env | grep ANTHROPIC 确认；unset ANTHROPIC_API_KEY 后 /login；key 来自 apiKeyHelper 就直接跑那个脚本看输出 |
Not logged in · Please run /login | 压根没有可用凭证 | /login；或确认 ANTHROPIC_API_KEY 在启动 claude 的那个 shell 里确实导出了；CI 用 apiKeyHelper |
Login expired · Please run /login | OAuth 刷新令牌被拒 | /login；非交互模式先跑 claude 完成登录再重跑命令；自动化用 ANTHROPIC_API_KEY，或 claude setup-token 生成长期令牌 |
OAuth token revoked or expired | 保存的登录失效了 | /login；仍报就先 /logout 再 /login；反复提示要查系统时钟和 macOS 钥匙串 |
Could not resolve authentication method | 到 API 客户端时一个凭证都没有 | 升级到 v2.1.176 或更高；确认凭证在启动工作进程的环境里；/status 确认来源 |
三、几条最容易踩的细节
3.1 env | grep ANTHROPIC 要在同一个 shell 里跑
官方在 Invalid API key 的处理里特意写了这条命令：
env | grep ANTHROPIC
Windows PowerShell：
Get-ChildItem Env:ANTHROPIC*
关键是「同一个 shell」。你在 A 终端里 export 了，在 B 终端里启动 claude，那个变量根本不存在。同理，你在 .zshrc 里写了但没重开终端，当前会话也读不到。
这条能解释大量「我明明设了 key」的情况——设了，但不在启动 claude 的那个环境里。
3.2 环境变量会盖掉你的订阅登录
如果你既有订阅、又在环境里留了 ANTHROPIC_API_KEY，那么在多条报错的处理里，官方给的动作都是同一个：
unset ANTHROPIC_API_KEY
然后 /login。
这个动作在 API Error: 401、Invalid API key、This organization has been disabled 三条里都出现了。如果你是订阅用户却撞上认证问题，先看环境里有没有这个变量，是性价比最高的一次检查。
3.3 反复要你登录：查时钟
OAuth token revoked or expired 的处理里有一条很容易被忽略：如果反复提示登录，检查系统时钟和 macOS 钥匙串。
系统时钟不准会导致令牌的有效期校验出问题——这类问题的表现就是「刚登录完又说过期」。虚拟机、长期休眠的笔记本、手动改过时间的机器都可能撞上。
钥匙串那条在 issue #3243（已关闭）里有印证：那条 issue 的报错是
API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid OAuth token. The provided token was not found or is malformed."}}
而 issue 正文里附的错误详情显示，实际失败的是一条读取 macOS 钥匙串的命令（security find-generic-password）。也就是说，报出来的是 401，真因是本地凭证读不出来。
这是认证族里很典型的一种错位：报错发生在 API 侧，根因在本地。
3.4 自动化场景的两条路
Login expired 和 Not logged in 的处理里，官方对自动化给了明确的两条路：
- 用
ANTHROPIC_API_KEY - 或者
claude setup-token生成一个长期令牌
还有一条是 apiKeyHelper——配置一个脚本，让 Claude Code 在启动时调它拿 key。这条适合 key 需要动态获取（比如从密钥管理服务取）的场景。
apiKeyHelper 自己也会出问题，官方单列了一条 Your apiKeyHelper script is failing，成因是那个命令报错退出、超时、或者没往标准输出打东西。处理办法很直接：
- 直接在 shell 里跑那条命令，看能不能复现
- 如果它说会话过期了，去凭证提供方那边重新认证
- 修到它把 key 打到标准输出、并以退出码 0 结束
/status可以看到apiKeyHelper的错误输出
第 3 条是重点：它要的是 stdout + 退出码 0，两个条件缺一不可。脚本里多打一行日志到 stdout，也会把 key 污染掉。
四、组织策略类：不是你的问题
有几条报错说的是组织管理员的设置，你自己怎么改都没用，认出来能省很多时间：
| 报错 | 含义 | 处理 |
|---|---|---|
This organization has been disabled | 你用的 key 属于一个已停用的控制台组织 | unset ANTHROPIC_API_KEY → 重启 claude → /status 确认 |
Your organization has disabled API key authentication | 管理员关掉了 API key 认证 | 提到 ANTHROPIC_API_KEY 就 unset；提到 apiKeyHelper 就从 settings.json 里移除；然后 /login |
Your organization has disabled Claude subscription access | 组织不允许用订阅登录 | 让管理员开权限，或改用 API key 认证 |
注意前两条和第三条方向相反：前两条是「别用 key，去登录」，第三条是「别登录，去用 key」。看清楚报错说的是哪一种，再动手。
还有一条 does not meet scope requirement user:profile，成因是保存的令牌缺了新功能需要的权限范围。处理很简单：直接 /login 拿一个带当前范围的新令牌，不需要先登出。
五、云厂商凭证：另一套体系
如果你走的是 Amazon Bedrock 这条路，认证报错是另一族，官方要求 v2.1.198 或更高版本：
AWS credentials expired or invalid：跑报错消息里点名的那条awsAuthRefresh命令（例如aws sso login --profile myprofile）；或者/login选「Claude Platform on AWS · refresh credentials」；用aws sts get-caller-identity确认凭证在 Claude Code 之外是有效的AWS authentication failed：先跑awsAuthRefresh排除过期；凭证是新的就去查 IAM 权限和模型访问权限AWS default-chain credential resolve timed out：默认凭证链 60 秒没出凭证。用aws sts get-caller-identity诊断；启动前先完成登录步骤；确实需要更久就调高CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS
这三条的共同点是：先在 Claude Code 之外验证凭证。 aws sts get-caller-identity 是这条链路的分界线——它通了，问题在 Claude Code 侧；它不通，先去修 AWS 那边。
六、还有两条容易被归错类的
有两条报错看起来像认证问题，实际上跟凭证本身无关，值得单独认出来：
Remote Control requires the Anthropic API
成因不是你的凭证有问题，而是这个会话没有直接跟 Anthropic API 通信。官方处理：
unset ANTHROPIC_BASE_URL然后重启会话- 或者从一个直连 Anthropic API 的会话里启动远程控制
也就是说，你如果配了 LLM 网关（ANTHROPIC_BASE_URL），远程控制这个功能就用不了。这不是权限问题，是链路要求。
claude.ai rejected the session token
成因是 claude.ai 的连接器请求失败——claude.ai 那边拒绝了 Claude Code 的登录令牌。官方处理：
/login重新登录- 从
/mcp重新连接连接器，或者/mcp reconnect <server>
第二条是关键：这条报错跟 MCP 连接器有关，光重新登录可能不够，还要把连接器重连一次。
把这两条认出来的价值在于：它们不会因为你换凭证、清环境变量而好转。花时间在那上面是白费的。
七、一条排查路径
把上面压成一条能照着走的路：
/status—— 看它实际在用什么凭证env | grep ANTHROPIC（在启动 claude 的那个 shell 里）—— 看有没有意外的 key 在盖你的登录- 有就
unset ANTHROPIC_API_KEY然后/login - 还报 → 先
/logout再/login - 反复要登录 → 查系统时钟，macOS 再查钥匙串
- 报错提到组织 → 认清是「别用 key」还是「别登录」，方向别搞反
- 走 Bedrock → 先
aws sts get-caller-identity划清界限
前三步能解决掉大多数情况。核心就一句：先搞清楚它在用哪套凭证，再决定改什么。
本文所引官方内容来自 Claude Code 官方错误参考文档，issue 编号来自 anthropics/claude-code 仓库，核对日 2026-08-08。版本要求与产品行为会变化，具体以官方文档为准。