目录

Claude Code 是否突然弹出过这样的消息，要求你登录？

Not logged in · Please run /login
Invalid API key · Fix external API key
OAuth token has expired · Please run /login
API Error: 400 ... This organization has been disabled.

这些都属于「认证（你是谁）确认失败」类的错误，多数会以 401/403 的形式出现。麻烦之处在于，它们往往以一种令人费解的方式出现——「我明明在付费，却被拒之门外」「昨天还能用，今天突然要求登录」。不过大部分原因都很典型，只要弄清排查的顺序，就能在很短时间内修好。

先说最重要的几点。（1）认证问题中最常见的，是环境变量 ANTHROPIC_API_KEY 在「悄悄覆盖」你的订阅（Pro/Max）登录——这往往就是意外的按量计费、「organization disabled」、「Invalid API key」的真正元凶。（2）一切的起点都是先用 /status 查看「现在是用哪个凭据在运行」。（3）拿不准时，就「unset 掉多余的密钥 → /logout → /login」，干净地重新登入。

CLAUDE CODE · AUTH PRECEDENCE

凭据是有「优先级」的

— 排在上面的胜出，所以环境变量里的 API 密钥会覆盖订阅

1 Cloud（Bedrock/Vertex/Foundry）
2 ANTHROPIC_AUTH_TOKEN（网关用）
3 ANTHROPIC_API_KEY ← 环境变量 这个胜出＝转为按量计费
4 apiKeyHelper / 5. CLAUDE_CODE_OAUTH_TOKEN
6 订阅 OAuth（/login） 这才是你真正想用的

只要 ANTHROPIC_API_KEY 还残留在环境中，它就会优先于订阅。
先用 /status 确认 → 不需要就 unset ANTHROPIC_API_KEY。

1. 这个错误到底在说什么

认证（authentication）就是「证明你是谁」。Claude Code 会用订阅的 OAuth 登录、API 密钥或云凭据之一来证明「你」的身份。当这个证明失败时，就会以 401（authentication_error）或 403（forbidden）的形式被拒绝。具有代表性的文案及其含义如下。

消息含义
Not logged in · Please run /login没有有效凭据 → /login
Invalid API key · Fix external API key（旧版本也会显示「· Please run /login」）来自环境变量或 apiKeyHelper 的密钥被 API 拒绝
This organization has been disabled某个已停用组织的旧 API 密钥在覆盖你
OAuth token revoked / has expired · Please run /login在别处登出／管理员撤销／自动刷新失败
API Error: 403 ... forbidden ... Request not allowed订阅失效、缺少 Console 角色，或代理干扰

关键的习惯是：在责怪自己之前，先用 /status 查看「现在是用哪个凭据在运行」。大多数认证错误，都源自选中了意料之外的凭据——而其中头号嫌疑就是下一节的「API 密钥覆盖」。

2. 最大的陷阱——API 密钥会覆盖订阅

官方文档明确指出，Claude Code 会按「优先级」从多个凭据中选出一个（参见开头的图示）。问题在于，环境变量 ANTHROPIC_API_KEY 排在订阅（Pro/Max）登录之上。换句话说——

官方说明（要旨）

「即使有有效的订阅，只要环境中存在 ANTHROPIC_API_KEY，（在被批准后）也会优先使用它。如果该密钥属于一个已停用或已过期的组织，认证就会失败。请运行 unset ANTHROPIC_API_KEY 回退到订阅，并用 /status 确认当前生效的是哪一个。」

这种覆盖会引发三种「令人费解」的症状。（1）意外的按量计费——本应是订阅的固定费用，却经 API 密钥按 token 计费（已有出现高额账单的报告）。（2）This organization has been disabled——残留的密钥属于一个已停用的旧组织。（3）Invalid API key——密钥已失效或有误。这些都不是「你登录本身的问题」，而是「多余的密钥赖在你的环境里不走的问题」。

密钥从哪里来：~/.zshrc、~/.bashrc、~/.profile 里的 export ANTHROPIC_API_KEY=...；被 direnv、dotenv 或你的 IDE 终端读取的 .env；来自前一份工作或别的项目的残留；CI 环境。在 Windows 上则是 PowerShell 配置文件（$PROFILE）或用户环境变量。用 /status 和 env | grep ANTHROPIC 检测；修复方法：

# 临时取消并启动
unset ANTHROPIC_API_KEY
claude

# 永久修复：从 shell 配置或 .env 中删除 export 行，然后用 /status 确认

注意：在交互模式下，会询问你一次是否使用该密钥，并记住你的选择（之后可通过 /config 中的「Use custom API key」开关更改）。除非你有意要使用 API 密钥，否则请用 /status 确认订阅处于生效状态。

3. 其他原因

除覆盖之外的认证问题，原因通常也比较固定。

OTHER CAUSES

覆盖之外的认证绊脚石

令牌被撤销／过期
在别处登出／管理员撤销／刷新失败。用 /logout → /login 重新登入。
系统时钟偏差
令牌校验依赖准确的时间。如果每次启动都要求登录，就校准时钟。
macOS 钥匙串
钥匙串被锁定／密码不一致会导致无法保存凭据。用 claude doctor 检查。
缺少 Console 角色（403）
使用 API 密钥时，请在 Console 中确认拥有 「Claude Code」/「Developer」角色且订阅有效。
WSL/SSH/容器中的 OAuth
浏览器的重定向无法返回本地。粘贴显示出来的代码，按 c 复制 URL，或设置 BROWSER。
组织策略
「停用订阅访问／API 密钥认证」属于服务端设置，本地无法覆盖。需管理员处理。

「每次都要求登录」→ 先怀疑时钟偏差或钥匙串。
「被 403 拒绝」→ 先怀疑订阅失效、Console 角色或代理。

了解凭据存放在哪里，也能加快恢复速度。macOS：钥匙串；Linux：~/.claude/.credentials.json（权限 0600）；Windows：%USERPROFILE%\.claude\.credentials.json。通常由 /login 和 /logout 管理这些，但若存储损坏，也可以删除此文件来进行干净的重新认证（进阶用法）。

4. 排查流程

认证卡住时，请自上而下依次排查。大多数情况在第 3 步就能解决。

DIAGNOSE

自上而下逐项排查

1
用 /status 确认现在哪个凭据生效（订阅、API 密钥还是云）。
2
用 env | grep ANTHROPIC（Windows 为 $PROFILE／用户环境变量）找出多余的密钥。
3
unset ANTHROPIC_API_KEY → 重新启动。从 shell 配置或 .env 中删除 export 行使其永久生效。
4
仍然失败？/logout → 关闭 Claude Code → /login 进行干净的重新认证。
5
校准时钟／在 macOS 上用 claude doctor 检查钥匙串／组织账号则确认Console 角色。

铁律：「先 /status，再搜寻多余的密钥」。
大多数情况，只要移除那个一直在覆盖你的密钥即可修好。

5. 与相似错误的区分

「被拒绝／被中断」也可能由非认证的原因引起。按 HTTP 状态码来区分是最可靠的办法。

症状真正是什么主要对策
401 / 403 · Invalid API key · Not logged in本文＝认证（凭据问题）/status → 移除多余的密钥 → /login
usage limit reached套餐额度用尽（认证正常）等待重置；对策
429 Request rejected速率限制（被低档密钥覆盖也可能导致 429）放慢请求；并用 /status 检查是否混入了密钥
529 / 500服务端过载／内部错误等待后重试；对策
Credit balance is too lowConsole 预付余额用尽（充值或切换到订阅）充值额度，或用 /login 切换到订阅

记忆方法：401/403 是「你是谁」的问题＝认证。usage limit 和 Credit balance 是「用量／余额」的问题。429 是速率，529/500 是服务端。尤其需要注意，多余的 API 密钥不仅会引发「认证失败」，还会带来「意外计费」和「低档下的 429」——这正是遇到困惑时永远先 /status 的原因。其他常见错误，可参见错误汇总。

6. 防止再次发生的检查清单

一份让你不再反复卡在认证上的检查清单。

（1）如果你使用订阅，就不要在 shell 配置或 .env 中残留 ANTHROPIC_API_KEY（当心来自旧工作／旧项目的残留）。（2）养成在重要工作前用 /status 确认当前生效凭据的习惯。（3）在 CI 中，使用 claude setup-token 的 CLAUDE_CODE_OAUTH_TOKEN（或明确的 API 密钥）来代替交互式登录。（4）如果每次都要求登录，请检查系统时钟和 macOS 钥匙串。（5）对于组织账号，请确认 Console 角色和套餐状态。（6）在 WSL/SSH 中，记住粘贴代码的方法。

总结

Claude Code 的认证／登录错误（Not logged in／Invalid API key／organization disabled／OAuth token expired 等）大多是 401/403＝凭据问题。而最频繁出现的真正原因，是「环境变量 ANTHROPIC_API_KEY 悄悄覆盖了订阅登录」——它会引发意外的按量计费、organization disabled 和 Invalid API key。因此，起点永远是用 /status 查看「现在是哪个凭据」。

排查顺序为 （1）/status → （2）用 env | grep ANTHROPIC 搜寻多余密钥 → （3）unset 并从 shell 配置中删除 → （4）/logout → /login → （5）时钟／钥匙串／Console 角色。大多数情况，只要移除那个一直在覆盖你的密钥即可修好。按 401/403＝认证、usage limit／Credit＝用量余额、429＝速率、529/500＝服务端来区分，就能避免对症不准的处理。相关：用量上限、529/500 错误、Claude Code 错误汇总。

FAQ

Q. 我明明在付费，却出现「Invalid API key」或「organization has been disabled」。为什么？
A. 几乎可以肯定，是环境变量 ANTHROPIC_API_KEY 在覆盖你的订阅登录。如果该密钥属于一个已过期或已停用的组织，那么即使订阅有效，你也会被拒绝。用 env | grep ANTHROPIC 找到它，运行 unset ANTHROPIC_API_KEY，然后 /login 并用 /status 确认。同时也要从 shell 配置（如 .zshrc 等）或 .env 中删除 export 行。

Q. 我用的是订阅固定费用，却被按 token 计费了。
A. 这通常也是 ANTHROPIC_API_KEY 覆盖所致。当 API 密钥优先生效时，用量就会流向按 token 的 API 计费，而非你的订阅固定费用。请用 /status 确认「订阅处于生效状态」；若选中的是 API 密钥，就用 unset 加上清理配置将其移除。只有在你有意使用 API 密钥时才保留它。

Q. 每次启动都要求我登录。
A. 常见原因是（1）系统时钟偏差（令牌校验依赖准确的时间）和（2）macOS 钥匙串被锁定／密码不一致导致无法保存凭据。请把时钟设置为自动同步，在 macOS 上用 claude doctor 检查钥匙串。若仍未解决，就用 /logout → /login 干净地重新登入。

Q. /status 能告诉我什么？
A. 它会显示当前是用哪种认证方式／凭据在运行（订阅 OAuth、ANTHROPIC_API_KEY，还是云凭据）。由于大多数认证问题都是「选中了意料之外的凭据」，所以先 /status 是铁律。显示的细节会随版本而变，请在官方文档中确认当前行为。

Q. 通过 WSL 或 SSH 时，浏览器打不开导致登录失败。
A. 在远程环境中，浏览器的重定向无法返回本地的回调地址。可通过以下方法绕开：粘贴 Claude Code 显示的登录代码，按 c 复制 URL 后在本地浏览器中打开，或在 WSL2 上设置 BROWSER 环境变量。记住粘贴代码的方法，处理起来就很稳妥。