【Bug已解决】API Key invalid after rotation / Old key cached — Claude Code API Key 轮换后失效解决方案1. 问题描述在 Anthropic Console 中轮换rotateAPI Key 后Claude Code 仍然使用旧 Key报认证错误$ claude 帮我分析代码 Error: Invalid API Key {type:error,error:{type:authentication_error,message:invalid x-api-key}} # 检查环境变量已经是新 Key $ echo $ANTHROPIC_API_KEY sk-ant-api03-NEWKEY # 但仍然报旧 Key 无效或者# settings.json 中更新了 Key 但不生效 $ cat ~/.claude/settings.json {apiKey: sk-ant-api03-NEWKEY} $ claude Error: Invalid API Key # 似乎还在使用旧 Key这个问题在以下场景中特别常见在 Anthropic Console 轮换 Key 后未更新本地配置多个配置来源环境变量 settings.json credentials.json冲突credentials.json 缓存了旧 KeyCI/CD 中使用旧 Key 的 secretClaude Code 登录态缓存了旧 Key2. 原因分析核心原理拆解API Key 轮换 → 旧 Key 被废弃 ↓ Claude Code 从某个缓存位置读取了旧 Key ↓ 使用旧 Key 发送请求 → 认证失败原因分类表原因分类具体表现占比credentials.json 缓存登录态保存了旧 Key约 35%多来源冲突环境变量和配置文件不一致约 25%CI/CD secret 未更新GitHub Actions 仍用旧 Key约 20%Shell 缓存当前 Shell 会话的环境变量约 10%CC Switch 旧配置切换工具保存了旧 Key约 10%3. 解决方案方案一清除所有缓存的 Key最推荐# 步骤 1清除 credentials.json rm -f ~/.claude/credentials.json # 步骤 2清除 settings.json 中的 apiKey cat ~/.claude/settings.json EOF { model: claude-sonnet-4-20250514 } EOF # 不在文件中保存 Key # 步骤 3使用环境变量设置新 Key export ANTHROPIC_API_KEYsk-ant-api03-NEWKEY # 步骤 4重启终端或 source 配置 source ~/.zshrc # 步骤 5启动 Claude Code claude方案二重新登录# 步骤 1退出当前登录 claude logout # 步骤 2清除凭据 rm -f ~/.claude/credentials.json # 步骤 3重新登录 claude login # 或直接使用 API Key export ANTHROPIC_API_KEYsk-ant-api03-NEWKEY claude方案三检查所有 Key 存储位置# 步骤 1检查环境变量 env | grep ANTHROPIC_API_KEY # 步骤 2检查 settings.json cat ~/.claude/settings.json | grep -i key # 步骤 3检查 credentials.json cat ~/.claude/credentials.json 2/dev/null # 步骤 4检查项目级配置 cat .claude/settings.json 2/dev/null | grep -i key # 步骤 5检查 CC Switch 配置 # CC Switch 的配置文件位置如果使用 # 步骤 6确保所有位置使用同一个新 Key # 或清除所有位置只用环境变量方案四修复 Shell 会话缓存# 步骤 1当前 Shell 可能缓存了旧环境变量 # 开启新终端 # 或手动更新 export ANTHROPIC_API_KEYsk-ant-api03-NEWKEY # 步骤 2确保 .zshrc 中是新 Key grep ANTHROPIC_API_KEY ~/.zshrc # 如果是旧 Key更新 # 步骤 3重新加载 source ~/.zshrc # 步骤 4验证 echo $ANTHROPIC_API_KEY # 确认是新 Key方案五更新 CI/CD 中的 Key# 步骤 1更新 GitHub Actions secret gh secret set ANTHROPIC_API_KEY --body sk-ant-api03-NEWKEY # 步骤 2更新 GitLab CI 变量 # GitLab → Settings → CI/CD → Variables # 步骤 3更新 Jenkins credentials # Jenkins → Manage → Credentials # 步骤 4验证 CI 使用新 Key # 在 CI 中添加步骤: - run: echo ${{ secrets.ANTHROPIC_API_KEY }} | head -c 20方案六使用 .env 文件统一管理# 步骤 1创建 .env 文件 cat ~/.claude/.env EOF ANTHROPIC_API_KEYsk-ant-api03-NEWKEY EOF # 步骤 2在 .zshrc 中加载 echo source ~/.claude/.env ~/.zshrc source ~/.zshrc # 步骤 3轮换 Key 时只需编辑 .env # vim ~/.claude/.env # 更新 Key 后 source ~/.zshrc4. 各方案对比总结方案适用场景推荐指数难度方案一清除缓存通用方案⭐⭐⭐⭐⭐低方案二重新登录登录态问题⭐⭐⭐⭐⭐低方案三检查所有位置深度排查⭐⭐⭐⭐⭐中方案四Shell 缓存环境变量⭐⭐⭐⭐低方案五CI/CD自动化⭐⭐⭐⭐⭐低方案六.env 文件长期管理⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 API Key 存储在哪些位置环境变量ANTHROPIC_API_KEY~/.claude/credentials.json登录态~/.claude/settings.json配置文件.claude/settings.json项目级配置CI/CD 的 secret/variableCC Switch 的配置文件5.2 哪个位置的 Key 优先级最高环境变量ANTHROPIC_API_KEY优先级最高覆盖配置文件和 credentials.json。5.3 轮换 Key 后旧 Key 还能用吗不能。Anthropic 轮换 Key 后旧 Key 立即失效。所有使用旧 Key 的地方都需要更新。5.4 credentials.json 是什么credentials.json存储 Claude Code 的登录凭据通过claude login获取。如果使用 API Key 方式不需要此文件。5.5 多台机器需要更新 Key每台机器上的所有 Key 存储位置都需要更新。建议使用配置管理工具如 Ansible批量更新。5.6 如何安全地共享新 Key不要通过聊天/邮件发送 Key。使用密码管理器1Password、BitwardenCI/CD 的 secret 管理加密的 .env 文件5.7 Claude Code 仍然使用旧 Key# 强制清除所有 Key 来源 rm -f ~/.claude/credentials.json unset ANTHROPIC_API_KEY # 重新设置 export ANTHROPIC_API_KEYsk-ant-api03-NEWKEY # 开新终端 claude5.8 Docker 中更新 Keydocker run -e ANTHROPIC_API_KEY$ANTHROPIC_API_KEY node:22 claude # 确保宿主机的环境变量是新 Key5.9 Key 轮换的频率建议每 90 天轮换一次 API Key。如果怀疑泄露立即轮换。5.10 排查清单速查表□ 1. rm ~/.claude/credentials.json 清除登录态 □ 2. 检查 ~/.claude/settings.json 中的 apiKey □ 3. env | grep ANTHROPIC_API_KEY 检查环境变量 □ 4. 检查 .claude/settings.json 项目级配置 □ 5. 检查 CC Switch 配置文件 □ 6. 开新终端避免 Shell 缓存 □ 7. 更新 CI/CD 中的 secret □ 8. 使用 .env 文件统一管理 Key □ 9. 所有位置使用同一个新 Key □ 10. 验证: echo $ANTHROPIC_API_KEY | head -c 206. 总结根本原因Key 轮换后失效最常见原因是credentials.json缓存了旧 Key35%和多配置来源冲突25%最佳实践轮换 Key 后执行rm ~/.claude/credentials.jsonexport ANTHROPIC_API_KEY新Key 开新终端统一管理使用~/.claude/.env文件统一管理 API Key轮换时只编辑一个文件避免多配置来源冲突CI/CD 更新轮换 Key 后立即更新所有 CI/CD 的 secretGitHub Actions、GitLab CI、Jenkins最佳实践建议不在settings.json中存储 API Key只通过环境变量传入——这样轮换 Key 时只需更新环境变量不会遗漏配置文件故障排查流程图flowchart TD A[API Key 轮换后失效] -- B[rm ~/.claude/credentials.json] B -- C[unset ANTHROPIC_API_KEY] C -- D[export ANTHROPIC_API_KEY新Key] D -- E[检查 settings.json 中是否存有旧 Key] E -- F{有旧 Key?} F --|是| G[从 settings.json 中移除 apiKey] F --|否| H[开新终端] G -- H H -- I[启动 claude] I -- J{认证成功?} J --|是| K[✅ 问题解决] J --|否| L[检查所有 Key 存储位置] L -- M[检查项目级 .claude/settings.json] M -- N{发现旧 Key?} N --|是| O[更新为新 Key] N --|否| P[使用 .env 文件统一管理] O -- Q[重新启动] P -- Q Q -- K