遇到 Claude API 鉴权失败，很多人第一反应就是：“是不是 Key 填错了？”
这当然有可能，但实际排查下来，问题往往没这么简单。除了 API Key 本身，请求头、权限、Billing、模型访问、Base URL、SDK 配置、Claude Code 的配置优先级，甚至第三方中转服务，都可能导致鉴权失败。

比较稳妥的做法，是按下面这个顺序来查：

• 先用官方 curl 发一个最小请求，确认 Key 到底能不能用；
• 然后检查 x-api-key、anthropic-version、content-type 这些请求头；
• 如果是 401 Unauthorized，优先看 Key、请求头和环境变量；
• 如果是 403 Forbidden，更多要看权限、Billing、组织、项目和模型；
• Claude Code 报错要单独处理，它不一定等同于 API Key 错；
• 如果用了第三方 API、中转站或者自定义 Base URL，先分清你用的是官方 Key，还是第三方平台的 Key。

下面这份清单，主要面向开发者，用来排查 Claude API key 无效、Claude API 权限配置错误，以及工具链里的鉴权失败问题。

---

一、先看清楚你遇到的是哪种鉴权失败

不同错误码背后的原因不一样。先看状态码和错误文案，通常比一上来就改环境变量更有效。

报错或状态码	更可能的原因	优先检查
401 Unauthorized	Key 无效、Key 没传进去、请求头写错	x-api-key、环境变量、Key 是否复制完整
invalid x-api-key	Key 格式不对，或者根本不是 Anthropic API Key	是否误用了 Claude 登录 Token、第三方 Key
Invalid API key	Key 被删了、被轮换了，或者程序读到的是旧 Key	Console 里的 Key 状态、配置优先级
403 Forbidden	权限不够、模型没权限、组织或项目受限	Billing、组织、Project、模型权限
Access denied	账号、组织、代理或第三方 endpoint 拒绝访问	Base URL、网关配置、账号权限
Please run /login	Claude Code 登录态或配置读取有问题	Claude Code 登录方式、配置文件
429	额度、速率限制、余额相关问题	Rate limit、用量限制、Billing
model not found / not authorized	模型名写错，或者当前账号无权调用	模型名称、模型访问权限

简单说：

• 401 更像是“身份没验过”，先查 Key、请求头、环境变量。
• 403 更像是“身份过了，但权限不够”，重点看账号权限、Billing、模型权限。
• 429 通常不是典型的鉴权失败，更多是额度、速率或者用量限制。
• Claude Code 报 Please run /login，不一定是 API Key 错了，也可能只是 CLI 登录态或配置文件没读对。

---

二、先用最小 curl 请求确认 Key 是否真的可用

排查 Claude API 鉴权失败时，建议第一步先绕开业务代码、SDK、Claude Code、IDE 插件和第三方网关，直接请求 Anthropic 官方 API。这样可以把问题范围缩小很多。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-haiku-latest",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "ping"}]
  }'

可以这样判断：

• 请求成功：Key 基本没问题，错误大概率出在业务代码、SDK 配置、Base URL、部署环境或工具链里。
• 返回 401：先检查 Key 是否真的传进去了，请求头有没有写错，程序是不是还在读旧 Key。
• 返回 403：优先看账号权限、Billing、组织、Project 以及模型访问权限。
• 返回 429：重点查额度、速率限制和用量限制，别急着把它当成 Key 错。
• 连接超时或 TLS 错误：这更像网络、代理、防火墙或 Base URL 的问题，不一定和鉴权有关。

如果你本地有多个 Key，最好先确认当前 Shell 里到底读到的是哪个：

echo $ANTHROPIC_API_KEY
env | grep ANTHROPIC

注意，真实 Key 不要直接贴到公开截图、日志、Issue 或聊天记录里。哪怕只是临时排查，也建议只看长度或前后几位。

---

三、检查 API Key 本身有没有问题

不少 “Claude API key 无效” 的问题，确实是 Key 本身导致的。但排查时不能只停留在“重新复制一遍”。

1. Key 是不是来自正确的位置

先确认 API Key 是从 Anthropic Console 创建的，而不是 Claude 网页聊天页面、浏览器 Cookie、登录 Token，或者其他工具生成的 Token。

Claude 网页版能正常聊天，并不代表 API 一定可用。网页版权益、API 访问、Billing、模型权限，通常是几套不同的配置链路。

2. Key 有没有复制完整

这些小细节很容易被忽略：

• Key 前后是不是多了空格；
• 中间有没有换行；
• 是否带了多余的引号；
• .env 文件格式是不是写错了；
• Shell 里有没有转义失败；
• CI/CD Secrets 里是不是还保存着旧值。

可以临时打印一下长度，或者只打印前后几位来确认，但不要把完整 Key 打到日志里。

3. 是否还在用旧 Key，或者被轮换过的 Key

如果某个 Key 曾经泄露、被删除、被轮换，那么继续使用它就可能触发 Invalid API key 或 401。

建议重点看这些地方：

• 本地 .env；
• Shell 环境变量；
• Docker 环境变量；
• GitHub Actions / GitLab CI Secrets；
• Vercel、云函数、服务器进程管理器里的环境变量；
• IDE 插件自己的配置项。

4. 程序是不是还读着旧环境变量

很常见的一种情况是：你明明已经换了新 Key，但程序仍然报同样的旧错误。

原因可能是：

• 终端没有重启；
• 改了 .zshrc、.bashrc，但没有 source；
• Node、Python 服务进程没有重启；
• IDE 没有继承当前 Shell 的环境变量；
• Docker 容器启动时没有传入新的变量；
• PM2、systemd、Supervisor 这类后台进程还在用旧环境。

macOS/Linux 可以先执行：

source ~/.zshrc
# 或
source ~/.bashrc

然后再重启终端、IDE 或服务进程。很多时候，这一步就能解决问题。

---

四、检查请求头和接口配置

Key 没问题，不代表请求一定能过。请求头写错，同样会导致 Claude API 鉴权失败。

1. 官方 Anthropic API 使用的是 x-api-key

调用官方 API 时，通常需要这样的请求头：

x-api-key: your_api_key
anthropic-version: 2023-06-01
content-type: application/json

不要直接照搬 OpenAI API 的写法：

Authorization: Bearer your_api_key

对 Anthropic 官方 API 来说，手写 HTTP 请求时应优先按官方文档使用 x-api-key。如果你用的是官方 SDK，很多 Header 会由 SDK 自动处理，一般不需要自己重复加。

2. 不要漏掉 anthropic-version

anthropic-version 是 Anthropic API 请求里比较关键的 Header。漏掉它，或者版本值和当前接口要求不匹配，都可能导致请求失败或兼容性问题。

示例里的 2023-06-01 是比较常见的写法，但实际项目中还是建议以官方文档当前推荐值为准。

3. Base URL 有没有配错

官方 Base URL 通常是：

https://api.anthropic.com

请求路径是：

/v1/messages

常见错误包括：

• Base URL 写成了第三方网关地址；
• SDK 会自动拼接 /v1，但你又手动加了一次，最后路径重复；
• Base URL 少了 https://；
• 公司代理或网关改写了请求头；
• 配了 ANTHROPIC_BASE_URL，但它指向了错误服务。

如果一时不确定，最简单的方法是先删除自定义 Base URL，直接用官方地址验证 Key。这样能快速判断问题到底在 Key，还是在网关和配置上。

---

五、检查权限、Billing 和模型访问

说到 Claude API 权限配置，重点其实就在这里。很多 403 并不是 Key 错，而是账号、组织、项目或模型权限没有配好。

1. API 权限和 Claude 网页版权限不是一回事

Claude 网页版能用，只能说明网页聊天功能可用，并不等于：

• 已经开通 API 访问；
• 已完成 Billing 配置；
• 当前组织具备 API 权限；
• 当前 Key 属于正确的 Project；
• 当前账号可以调用你指定的模型。

所以遇到 403 时，不要反复折腾 Header。更应该回到 Console 里，检查账户、组织和项目配置。

2. Billing、余额和额度

如果账号没有可用 Billing、余额不足，或者触发了用量限制，也可能出现和权限、额度相关的报错。

这里可以简单区分一下：

• 401：身份校验失败，优先查 Key 和请求头；
• 403：身份可能是有效的，但权限不够；
• 429：通常是速率限制、额度或用量限制。

不同账号、组织和项目的限制可能不一样，最终还是要以官方控制台和文档为准。

3. 模型名和模型权限

model not found、not authorized 或 403，也可能是模型相关问题。

重点检查：

• 模型名有没有拼错；
• 是否用了已经变更或不再推荐的模型名；
• 当前账号是否有该模型的访问权限；
• 第三方网关是否支持这个模型；
• SDK 是否太旧，导致模型列表或接口兼容有问题。

建议直接从官方文档复制当前可用模型名，不要凭记忆手填。模型名一旦差一个字符，就可能排查半天。

---

六、Claude Code 报 Invalid API key 或 Please run /login 怎么处理

Claude API 调用失败，和 Claude Code 登录失败，不完全是一类问题。Claude Code 还会涉及 CLI 登录态、配置文件、项目配置以及 IDE 集成。

1. 先确认 Claude Code 版本

claude --version

Claude Code 的配置方式和读取优先级可能会随着版本变化。涉及具体配置路径、字段名时，最好还是以当前官方文档为准。

2. 检查环境变量

echo $ANTHROPIC_API_KEY
env | grep ANTHROPIC

如果终端里能读到 Key，但 Claude Code 仍然报错，就继续看配置文件和 IDE 环境。

3. 检查 Claude Code 配置文件

常见位置包括：

~/.claude/settings.json
~/.claude/config.json
项目目录/.claude/settings.local.json

需要重点确认这些地方：

• 有没有写着旧 Key；
• 是否配置了错误的 Base URL；
• 全局配置和项目配置是否互相覆盖；
• IDE 插件里是否还有独立配置；
• 修改后有没有重启 Claude Code、终端和 IDE。

Please run /login 更偏向 Claude Code 的登录态问题，不一定是 Anthropic API Key 本身错了。看到这个提示时，应该优先按 Claude Code 的登录和配置机制来查，而不是只盯着 API Key。

---

七、用了第三方 API、中转站或自定义 Base URL 时怎么查

如果你用的是第三方 Claude API 兼容服务、代理网关或自定义 endpoint，那鉴权规则可能和 Anthropic 官方 API 不完全一样。

比如 ClaudeAPI 这类平台，本质上属于第三方 Claude API 兼容接入服务，并不是 Anthropic 官方。它可能会提供兼容接入、多线路选择、中文支持、企业充值、开票、基础技术协助等能力。不过，具体怎么鉴权、支持哪些模型、额度怎么算，都应该以它官网的最新说明为准。

排查第三方 endpoint 时，尤其要注意：

• 官方 Key 不一定能用于第三方网关；
• 第三方 Key 也不一定能用于 Anthropic 官方 API；
• Header 可能要求 Authorization: Bearer，也可能是别的字段；
• ANTHROPIC_BASE_URL 必须指向正确服务；
• 网关返回的 401/403，不一定是 Anthropic 官方返回的；
• 网关可能并不支持你填写的模型名；
• Claude Code 或 SDK 更新后，第三方 endpoint 的配置读取方式也可能变化。

比较推荐的排查顺序是：

先用官方 API 直连验证 Anthropic Key
再按第三方文档验证第三方 Key
最后再排查 SDK、Claude Code 或 IDE 插件

不要把官方 API 的 Header 和第三方网关的 Header 混着用。这个问题非常常见，而且很容易误判。

---

八、不同运行环境里的配置检查

很多时候不是 Key 错了，而是当前运行环境根本没读到 Key。

1. 本地终端可以，IDE 不行

这通常是因为 IDE 没有继承 Shell 环境变量。可以重启 IDE，或者在 IDE 插件设置里单独配置 API Key 和 Base URL。

2. 本地可以，Docker 不行

先进入容器里看一下：

docker exec -it <container_id> sh
echo $ANTHROPIC_API_KEY

启动容器时，需要显式传入环境变量：

docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY your-image

否则你本机 Shell 里有 Key，不代表容器里也有。

3. 本地可以，CI/CD 不行

可以从这几个方面查：

• Secrets 名称是否和 workflow 里写的一致；
• workflow 里是否真的把变量注入到运行环境；
• 不同分支、环境、项目是否使用了不同 Secrets；
• 日志里变量是否为空，或者根本没有传入。

4. Windows 环境

PowerShell、CMD、Git Bash 设置环境变量的方式不一样。要确认你“设置变量的终端”和“运行程序的终端”是同一个环境。

PowerShell 临时设置示例：

$env:ANTHROPIC_API_KEY="your_api_key"

---

九、最终检查清单

如果还是没定位到 Claude API 鉴权失败的原因，可以按下面这份清单逐项过一遍：

• API Key 来自 Anthropic Console，而不是网页登录 Token；
• 已经用官方 curl 最小请求验证过；
• 请求头使用的是 x-api-key，没有误用 OpenAI 风格的 Authorization: Bearer；
• 已设置 anthropic-version；
• content-type 是 application/json；
• Base URL 是预期地址，没有重复或遗漏 /v1；
• 程序没有读到旧环境变量；
• .env、Shell、Docker、CI/CD、云平台里的 Key 保持一致；
• 修改配置后，已经重启终端、IDE 和服务进程；
• Billing、余额、额度状态正常；
• 当前组织、Project、Workspace 权限正确；
• 模型名正确，而且账号有调用权限；
• Claude Code 配置文件没有覆盖环境变量；
• 第三方 endpoint 的 Key、Header、模型和 Base URL 符合其文档；
• SDK 或 Claude Code 版本没有过旧，必要时参考官方文档更新。

---

FAQ

1. Claude API Key 无效，一定是 Key 填错了吗？

不一定。可能是 Key 本身错了，也可能是请求头写错、环境变量没读到、程序读了旧 Key，或者 Base URL 指向了第三方服务。

2. 401 和 403 有什么区别？

401 更偏身份校验失败，先查 Key 和请求头。403 更偏权限不足，优先看 Billing、组织、Project 和模型权限。

3. Claude 网页版能用，为什么 API 不能用？

网页版聊天权限不等于 API 权限。API 还涉及 Console、Billing、组织、项目、模型访问等配置。

4. ANTHROPIC_API_KEY 配了为什么不生效？

常见原因是终端没重启、进程没重启、IDE 没继承环境变量、Docker/CI/CD 没传入变量，或者 Claude Code 配置文件覆盖了 Shell 变量。

5. Claude Code 报 Please run /login 是 API Key 问题吗？

不一定。它更可能和 Claude Code 登录态、配置文件或版本行为有关。建议单独检查 Claude Code 的登录方式和配置优先级。

6. 第三方 API 可以直接用 Anthropic 官方 Key 吗？

不一定。第三方 Claude API 兼容服务通常有自己的鉴权规则。官方 Key、第三方 Key、Header 和 Base URL 不要混用，具体看对应服务文档。

7. 为什么换了新 Key 还是报旧错误？

通常是程序仍然在读取旧环境变量。重点检查 .env、Shell、IDE、Docker、CI/CD、服务器进程以及 Claude Code 配置文件。

8. ANTHROPIC_BASE_URL 应该怎么填？

如果直连官方 API，通常填写：

https://api.anthropic.com

如果使用第三方网关，就按第三方文档填写，并注意是否需要包含 /v1。

9. 需要设置 Authorization: Bearer 吗？

调用 Anthropic 官方 API 时，通常使用 x-api-key。Authorization: Bearer 更常见于 OpenAI 风格接口或部分第三方兼容网关，不要混用。

10. Docker / CI 中怎么检查 Key 是否传入？

在实际运行环境里执行：

echo $ANTHROPIC_API_KEY
env | grep ANTHROPIC

如果结果为空，说明 Key 没有注入到当前容器或 CI 任务中。这时就要回到部署配置、workflow 或 Secrets 配置里继续排查。