【Bug已解决】API Key invalid after rotation / Old key cached — Claude Code API Key 轮换后失效解决方案
【Bug已解决】API Key invalid after rotation / Old key cached — Claude Code API Key 轮换后失效解决方案
1. 问题描述
在 Anthropic Console 中轮换（rotate）API 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 缓存了旧 Key
- CI/CD 中使用旧 Key 的 secret
- Claude Code 登录态缓存了旧 Key
2. 原因分析
核心原理拆解
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_KEY=sk-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_KEY=sk-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_KEY=sk-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_KEY=sk-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. 常见问题 FAQ
5.1 API Key 存储在哪些位置
- 环境变量
ANTHROPIC_API_KEY ~/.claude/credentials.json（登录态）~/.claude/settings.json（配置文件）.claude/settings.json（项目级配置）- CI/CD 的 secret/variable
- CC 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、Bitwarden）
- CI/CD 的 secret 管理
- 加密的 .env 文件
5.7 Claude Code 仍然使用旧 Key
# 强制清除所有 Key 来源 rm -f ~/.claude/credentials.json unset ANTHROPIC_API_KEY # 重新设置 export ANTHROPIC_API_KEY=sk-ant-api03-NEWKEY # 开新终端 claude5.8 Docker 中更新 Key
docker 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缓存了旧 Key（35%）和多配置来源冲突（25%） - 最佳实践：轮换 Key 后执行
rm ~/.claude/credentials.json+export ANTHROPIC_API_KEY=新Key+ 开新终端 - 统一管理：使用
~/.claude/.env文件统一管理 API Key，轮换时只编辑一个文件，避免多配置来源冲突 - CI/CD 更新：轮换 Key 后立即更新所有 CI/CD 的 secret（GitHub 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