【Claude】Invalid API key 无效密钥报错已解决

关键词：Claude Code、Invalid API key、无效密钥、ANTHROPIC_API_KEY、direnv、.env 文件、apiKeyHelper、Keychain

一、问题现象

Invalid API key · Fix external API key

特征：

• 明确指向 "external API key"（外部 API key）——意味着是 ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本提供的 key 被 API 拒绝了；
• 不是 OAuth 登录问题；
• 自动重试不会修复它（key 本身无效，重发多少次都一样）。

二、根因：key 本身被 API 拒绝

API 收到了你的 key，但拒绝接受它。常见原因：

2.1 key 已被撤销

在 Console（platform.claude.com）里把 key 删了、轮换了，但老 key 还留在环境变量里。

2.2 key 拼写错误 / 截断

复制粘贴时多了空格、少了字符，或者 base64 字符被 shell 解释（比如含有 $ 字符的 key 没有用单引号包裹）。

# 错误：双引号无法阻止 $ 被 shell 展开
export ANTHROPIC_API_KEY="sk-ant-api03-xxx$xxx"

# 正确：用单引号或转义
export ANTHROPIC_API_KEY='sk-ant-api03-xxx$xxx'

2.3 工具自动加载了过时的 .env 文件

这是最隐蔽的坑。 direnv、dotenv shell 插件、IDE（VS Code、Cursor、JetBrains）的终端会自动从项目目录的 .env 文件里加载环境变量。如果你的项目里有这样一个文件：

ANTHROPIC_API_KEY=sk-ant-api03-旧的被撤销的key

那么每次在那个目录下开终端，这个旧 key 都会被自动加载，覆盖你之后通过 /login 存储的订阅凭证。而且你很可能对此毫无察觉。

2.4 apiKeyHelper 脚本返回了无效 key

如果你在 settings.json 里配置了 apiKeyHelper，而那个脚本由于权限、路径、密钥轮换等原因返回了无效内容。

三、解决方案

方案一：检查所有 ANTHROPIC 相关环境变量

在启动 claude 的同一个 shell 里运行：

env | grep ANTHROPIC

查看是否有 ANTHROPIC_API_KEY，以及它的值看起来是否完整有效（以 sk-ant- 开头，没有截断、多余空格）。

如果存在且无效，立刻清除：

unset ANTHROPIC_API_KEY

方案二：检查并清理所有可能注入 key 的来源

按以下顺序逐一检查：

1. ~/.zshrc / ~/.bashrc / ~/.bash_profile：搜索 ANTHROPIC_API_KEY；
2. 项目目录的 .env 文件：cat .env | grep ANTHROPIC；
3. direnv 的 .envrc 文件：cat .envrc；
4. IDE 终端设置：VS Code settings.json 里的 terminal.integrated.env.*；
5. ~/.claude/settings.json 里的 apiKeyHelper 字段。

找到过时/无效的 key 来源，删除或更新。

方案三：直接运行 apiKeyHelper 脚本验证

如果你配了 apiKeyHelper，直接执行它：

/path/to/your/apiKeyHelper.sh

确认它在 stdout 的第一行打印了一个有效的 key，没有多余的前缀、后缀或换行。常见的脚本 bug：

• 多打印了一行"提示信息"导致第一行不是 key；
• key 过期了但脚本没有刷新逻辑；
• 脚本没有执行权限（chmod +x）。

方案四：切换到 /login 认证

如果你不需要用 API key 认证，彻底清掉相关变量和配置，改用 /login：

unset ANTHROPIC_API_KEY
# 从 settings.json 删除 apiKeyHelper 字段
/login

/status 确认活跃凭证已切为订阅。

方案五：到 Console 检查 key 状态

登录 platform.claude.com，进入 API Keys 管理页，确认：

• 该 key 是否还存在；
• 是否处于激活状态（没有被撤销或停用）；
• 所属工作区的信用余额是否足够。

如果 key 已撤销，创建一个新 key，更新到所有使用它的地方。

四、总结

Invalid API key = API 拒绝了你提供的 key。最高频的根因是老的/被撤销的 key 藏在某处自动加载的配置文件里，而你对此不知情。

标准排查路径：env | grep ANTHROPIC → 检查所有可能注入 key 的来源（.env、.envrc、shell 配置、IDE 设置、apiKeyHelper）→ 清除无效来源 → 用 /status 验证。

---

参考：Claude Code 官方《错误参考》"身份验证"章节、社区 Invalid API key 排查记录。