【Bug已解决】Invalid API Key / Not logged in — Claude Code 认证失败解决方案1. 问题描述在启动 Claude Code 或使用过程中终端突然弹出以下报错信息所有 API 请求被拒绝Invalid API key. Please check your API key and try again.或者Not logged in. Run claude login to authenticate.完整的 API 返回错误可能包含以下字段{ type: error, error: { type: authentication_error, message: invalid x-api-key } }有时报错表现为 OAuth 令牌过期OAuth token revoked. Please re-authenticate. Error: Token has expired or been revoked这个问题在以下场景中特别常见首次安装 Claude Code 后未完成认证API Key 过期、被撤销或输入错误使用 CC Switch 等工具切换 Key 后配置残留Anthropic 账户被暂停或限制环境变量 ANTHROPIC_API_KEY 与登录态冲突使用第三方 API 路由但 Key 不兼容许多开发者反映明明昨天还在正常使用今天突然报认证失败。更令人困惑的是有时/status显示已登录但 API 请求仍然报 401。# 典型复现过程 $ claude 帮我分析这段代码 Invalid API key. Please check your API key and try again. # 检查环境变量 $ echo $ANTHROPIC_API_KEY sk-ant-api03-xxxxx # Key 看起来没问题但就是报错 $ claude /status Status: Not logged in2. 原因分析核心原理拆解Claude Code 发送 API 请求 → 携带认证凭据 ↓ Anthropic API 验证凭据有效性 ↓ 凭据无效/过期/不匹配 ↓ 返回 401 authentication_error ↓ Claude Code 显示 Invalid API key 或 Not logged in原因分类表原因分类具体表现占比API Key 无效或过期Key 被撤销、输入错误或已过期约 35%未完成登录流程首次使用未执行 claude login约 25%环境变量与登录态冲突ANTHROPIC_API_KEY 覆盖了 OAuth 登录约 15%OAuth 令牌过期长时间未使用刷新令牌过期约 10%第三方 API 路由 Key 不兼容非 Anthropic 原生 Key 格式约 10%账户被暂停Anthropic 账户因违规被限制约 5%深入说明Claude Code 支持两种认证方式方式一OAuth 登录Pro/Max 订阅用户通过claude login命令进行浏览器 OAuth 认证登录后凭据缓存在~/.claude/credentials.json。这种方式使用的是 Anthropic 账户的订阅配额不需要单独的 API Key。OAuth 令牌有有效期需要定期刷新。如果长时间不使用刷新令牌可能过期需要重新登录。方式二API Key 认证按量计费用户通过环境变量ANTHROPIC_API_KEY或配置文件设置 API Key。API Key 格式为sk-ant-api03-xxxxx在 Anthropic Console 中生成。Key 不会过期但可以被手动撤销。冲突场景如果同时设置了 OAuth 登录和环境变量 API KeyClaude Code 的行为取决于版本较新版本优先使用环境变量 API Key较旧版本优先使用 OAuth 登录如果两者都指向不同的账户/路由可能导致认证混乱第三方 API 路由问题使用ANTHROPIC_BASE_URL指向第三方 API 路由时第三方路由的 Key 格式可能与 Anthropic 原生 Key 不同。如果 Key 格式不匹配或第三方路由需要不同的认证头就会报认证失败。3. 解决方案方案一重新执行 claude login最推荐如果使用 Pro/Max 订阅重新登录是最直接的解决方案。# 步骤 1退出当前会话 # 按 CtrlC 或输入 /exit # 步骤 2重新登录 claude login # 步骤 3浏览器会打开 Anthropic 登录页面 # 输入账号密码完成认证 # 授权 Claude Code 访问 # 步骤 4验证登录状态 claude /status # 应该显示 Logged in as: your-emailexample.com # 步骤 5启动 Claude Code claude方案二检查并重新设置 API Key如果使用 API Key 认证确认 Key 有效并正确配置。# 步骤 1检查当前环境变量 echo $ANTHROPIC_API_KEY # 确认 Key 格式正确: sk-ant-api03-xxxxx # 步骤 2检查 Key 是否有效 # 在 Anthropic Console 中查看: https://console.anthropic.com/settings/keys # 确认 Key 未被撤销或删除 # 步骤 3重新设置 API Key # 临时生效当前终端 export ANTHROPIC_API_KEYsk-ant-api03-你的新key # 永久生效写入 shell 配置 echo export ANTHROPIC_API_KEYsk-ant-api03-你的新key ~/.zshrc source ~/.zshrc # 步骤 4确保没有设置冲突的 BASE_URL echo $ANTHROPIC_BASE_URL # 如果使用官方 API确保此变量为空 unset ANTHROPIC_BASE_URL # 步骤 5验证 claude方案三清除旧的认证缓存后重新登录如果旧凭据残留导致冲突清除缓存后重新认证。# 步骤 1清除凭据文件 rm -f ~/.claude/credentials.json rm -f ~/.claude/.credentials # 步骤 2清除环境变量 unset ANTHROPIC_API_KEY unset ANTHROPIC_AUTH_TOKEN unset ANTHROPIC_BASE_URL # 步骤 3清除 Shell 配置中的旧设置 # 检查并编辑 ~/.zshrc 或 ~/.bashrc # 注释掉或删除旧的 ANTHROPIC_* 环境变量 # 步骤 4重新加载 Shell 配置 source ~/.zshrc # 步骤 5重新认证 claude login # 或 export ANTHROPIC_API_KEYsk-ant-api03-你的新key # 步骤 6验证 claude /status方案四检查 CC Switch 等工具的配置如果使用 CC Switch 等工具管理多个 Key检查是否有配置残留。# 步骤 1检查 CC Switch 配置 cat ~/.claude/settings.json # 查看是否有 CC Switch 写入的配置 # 步骤 2检查是否有多个配置源冲突 ls -la ~/.claude/ # 检查所有配置文件 # 步骤 3如果 CC Switch 导致问题重置配置 # 备份后重置 cp ~/.claude/settings.json ~/.claude/settings.json.bak echo {} ~/.claude/settings.json # 步骤 4手动配置 claude login # 或 export ANTHROPIC_API_KEYsk-ant-api03-你的key方案五第三方 API 路由的认证配置如果使用第三方 API 路由确保认证配置正确。# 步骤 1设置第三方路由的 URL 和 Key export ANTHROPIC_BASE_URLhttps://your-proxy.com export ANTHROPIC_API_KEYsk-你的第三方key # 注意: 第三方 Key 格式可能与 Anthropic 原生不同 # 步骤 2如果第三方路由使用不同的认证头 # 某些路由使用 ANTHROPIC_AUTH_TOKEN 而非 ANTHROPIC_API_KEY export ANTHROPIC_AUTH_TOKENBearer your-token unset ANTHROPIC_API_KEY # 步骤 3测试连通性 curl -H x-api-key: $ANTHROPIC_API_KEY \ -H content-type: application/json \ -H anthropic-version: 2023-06-01 \ $ANTHROPIC_BASE_URL/v1/messages \ -d {model:claude-sonnet-4-20250514,max_tokens:10,messages:[{role:user,content:hi}]} # 步骤 4如果 curl 测试成功启动 Claude Code claude方案六检查账户状态如果 Key 和登录都正确但仍报认证失败可能是账户被暂停。# 步骤 1登录 Anthropic Console # https://console.anthropic.com # 步骤 2检查账户状态 # 在 Settings → Account 中查看账户是否正常 # 在 Settings → Billing 中查看是否有欠费 # 步骤 3检查 API Key 状态 # 在 Settings → API Keys 中查看 Key 是否有效 # 如果 Key 显示 Revoked需要重新生成 # 步骤 4检查使用策略 # 在 Settings → Usage Policies 中查看是否有限制 # 步骤 5如果账户被暂停 # 联系 Anthropic 支持: https://support.anthropic.com4. 各方案对比总结方案适用场景推荐指数难度方案一重新 claude loginPro/Max 订阅用户⭐⭐⭐⭐⭐低方案二重设 API KeyAPI Key 认证⭐⭐⭐⭐⭐低方案三清除缓存重登凭据冲突/残留⭐⭐⭐⭐低方案四检查 CC Switch多 Key 管理工具⭐⭐⭐中方案五第三方路由配置使用第三方 API⭐⭐⭐⭐中方案六检查账户状态账户可能被暂停⭐⭐⭐低5. 常见问题 FAQ5.1 /status 显示已登录但 API 请求报 401可能是 OAuth 令牌过期但 /status 未及时更新。尝试claude logout然后重新claude login检查是否有环境变量覆盖了登录态echo $ANTHROPIC_API_KEY清除凭据缓存后重新登录5.2 API Key 在 Console 中显示有效但 Claude Code 报无效检查以下几点Key 是否有前导/尾部空格echo $ANTHROPIC_API_KEY | wc -cKey 是否被 Shell 转义使用单引号export ANTHROPIC_API_KEYsk-ant-...是否设置了错误的ANTHROPIC_BASE_URL指向不兼容的服务Key 是否有足够的权限某些 Key 受限于特定模型5.3 切换 API Key 后仍然使用旧 Key可能是 Shell 配置文件中的旧 Key 覆盖了新设置。检查# 检查所有 Shell 配置文件 grep ANTHROPIC ~/.zshrc ~/.bashrc ~/.profile ~/.zprofile 2/dev/null # 删除或注释掉旧的 Key 设置 # 确保只有一处设置 ANTHROPIC_API_KEY5.4 使用 OAuth 登录但报 org not allowed组织策略可能限制了 Claude Code 的使用。联系组织管理员在 Anthropic Console 中授权 Claude Code。或者使用个人账户的 API Key 代替组织 OAuth 登录。5.5 Docker 容器中无法执行 claude loginDocker 容器没有浏览器无法完成 OAuth 登录。使用 API Key 认证代替docker run -e ANTHROPIC_API_KEYsk-ant-api03-xxx node:22 claude或者将宿主机的凭据文件挂载到容器中docker run -v ~/.claude:/root/.claude node:22 claude5.6 CI/CD 环境中的认证CI/CD 环境无法进行交互式登录。使用 API Key# GitHub Actions 示例 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | npm install -g anthropic-ai/claude-code claude --print 分析代码并生成报告5.7 多人共享服务器上的认证问题每个用户应使用独立的认证不要共享同一个 API Key。每个用户在各自的~/.claude/目录中配置独立的凭据。如果必须共享 Key注意速率限制会叠加。5.8 报 500 no available claude accounts这通常意味着账户配额耗尽或账户被限制。检查Anthropic Console 中的使用量和配额账户是否有欠费是否触发了使用策略限制联系 Anthropic 支持确认账户状态5.9 使用 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别ANTHROPIC_API_KEY标准认证方式使用x-api-keyHTTP 头ANTHROPIC_AUTH_TOKEN某些第三方路由使用的认证方式使用Authorization: Bearer头不要同时设置两者只设置一个5.10 排查清单速查表□ 1. 运行 claude /status 查看当前认证状态 □ 2. 检查 echo $ANTHROPIC_API_KEY 是否设置正确 □ 3. 检查 echo $ANTHROPIC_BASE_URL 是否指向正确的端点 □ 4. 在 Anthropic Console 中确认 Key 未被撤销 □ 5. 清除 ~/.claude/credentials.json 后重新 claude login □ 6. 检查 ~/.zshrc 中是否有多个 ANTHROPIC_* 设置冲突 □ 7. 确认没有同时设置 API_KEY 和 AUTH_TOKEN □ 8. 使用 curl 测试 API 连通性 □ 9. 检查 CC Switch 等工具是否覆盖了配置 □ 10. 确认账户未被暂停或限制6. 总结根本原因认证失败最常见原因是 API Key 无效/过期35%和未完成登录流程25%其次是环境变量与 OAuth 登录态冲突最佳实践Pro/Max 订阅用户使用claude loginOAuth 认证按量计费用户使用ANTHROPIC_API_KEY环境变量不要混用两种方式快速恢复清除~/.claude/credentials.json和所有ANTHROPIC_*环境变量后重新认证可解决 90% 的认证冲突问题第三方路由使用第三方 API 路由时确保ANTHROPIC_BASE_URL和 Key 格式与路由要求匹配使用curl先测试连通性最佳实践建议将 API Key 存储在环境变量或 secrets 管理工具中不要硬编码在脚本或配置文件中定期在 Anthropic Console 中检查 Key 状态和使用量故障排查流程图flowchart TD A[出现 Invalid API Key / Not logged in] -- B{认证方式?} B --|OAuth 登录| C[执行 claude logout claude login] B --|API Key| D[检查 ANTHROPIC_API_KEY 环境变量] B --|第三方路由| E[检查 BASE_URL Key 格式] C -- F{登录成功?} F --|是| G[✅ 问题解决] F --|否| H[清除 ~/.claude/credentials.json] D -- I{Key 是否正确?} I --|是| J[检查 ANTHROPIC_BASE_URL] I --|否| K[在 Console 重新生成 Key] E -- L[curl 测试 API 连通性] H -- C J -- M{BASE_URL 是否正确?} M --|是| N[检查账户是否被暂停] M --|否| O[unset 或修正 BASE_URL] K -- P[重新设置 API Key] L -- Q{curl 测试成功?} Q --|是| G Q --|否| R[检查第三方路由文档] N -- S{账户正常?} S --|是| T[清除所有缓存重试] S --|否| U[联系 Anthropic 支持] O -- G P -- G R -- G T -- G U -- G
