Standard Compute

Claude Code API 返回 401 怎么解决？

更新于 2026-11-04 · standardcompute.cyou

简答：Claude Code API 返回 401，先不要急着更换模型：401 在 Claude API 中表示认证信息存在问题，常见核验项是实际生效的 API Key、ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN、Base URL，以及中转网关要求的认证头。先清理冲突变量，再用一个最小请求确认 Key 和入口是否有效；如果最小请求成功，再回到 Claude Code 检查配置继承和工具版本。本文按 2026-11-04 检索到的官方资料整理。

定义：Claude Code API 401 是服务端拒绝当前请求认证信息的 HTTP 状态，不能仅凭 401 判断模型不可用或服务故障。

适用范围与三行结论

本文面向在本机、容器、企业代理或兼容 Anthropic Messages API 的 API 网关中使用 Claude Code 的开发者。本文为第三方接入指南，不代表任何品牌官网；涉及具体服务的 Base URL、Key 入口、模型 ID、价格和权限时，应以对应服务商当前文档为准。

第一，401 优先查认证，不要先改模型。官方错误说明将 401 定义为 authentication_error，可能与 Key 格式错误、被撤销或过期有关；使用 AWS 平台时，也可能涉及 AWS 凭证或 SigV4 签名。Claude API 错误说明

第二，先确认“哪一个 Key 真正在生效”。Claude Code 的网关文档显示，ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 的优先级高于 apiKeyHelper；只修改 helper 而保留旧环境变量，可能仍然发送旧凭证。Claude Code LLM 网关配置

第三，用最小 HTTP 请求把 Claude Code 与服务端问题分开。最小请求仍然返回 401，说明应继续查 Key、认证头、入口或网关权限；最小请求成功而 Claude Code 仍失败，重点转向环境变量继承、配置文件和 Claude Code 本身。

先试这一步：三分钟自查表

现象或检查项优先动作判定方向
直接请求返回 401重新确认 Key 是否完整、有效、未撤销，并确认认证头格式认证信息或网关鉴权问题
直接请求成功，Claude Code 返回 401打印当前 shell 中相关变量的“是否存在”和长度，不输出完整 Key；再检查启动 Claude Code 的同一终端变量未继承、旧变量冲突或配置未加载
改了 API Key 仍返回 401检查是否同时设置了 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 和 apiKeyHelper实际生效凭证不是刚修改的那一个
返回 403不要按 401 继续换 Key，改查组织、工作区或模型权限认证可能已通过，但权限不足
返回 404核对 Base URL、路径和是否重复拼接 /v1入口或资源路径问题
返回 429查看限速、预算或工作区用量，不要把它当成 Key 无效频率、额度或工作区限制

上表中的 401、403、404 和 429 含义以官方错误文档为准；具体网关可能返回自定义错误文本，因此排查时应同时保留 HTTP 状态码、响应体中的错误类型和 request ID。官方 HTTP 错误说明

最短主流程：从实际生效配置查起

  1. 确认 Claude Code 使用的认证路径。官方入门文档说明，Claude Code 默认使用 Anthropic API，也支持通过企业平台等方式接入。若你使用的是自建或第三方 API 网关，不要把网关 Key 当成 Anthropic Console Key，也不要把 OAuth 登录状态当成 API Key。Claude Code 入门文档
  2. 在启动 Claude Code 的同一个终端检查变量。Linux、macOS 或 WSL 可执行：printf 'API_KEY=%s\n' "${ANTHROPIC_API_KEY:+set}"; printf 'AUTH_TOKEN=%s\n' "${ANTHROPIC_AUTH_TOKEN:+set}"; printf 'BASE_URL=%s\n' "${ANTHROPIC_BASE_URL:-not-set}"。这个检查只输出变量是否存在和 Base URL，不会输出完整密钥。Windows PowerShell 可用：if ($env:ANTHROPIC_API_KEY) {'API_KEY=set'} else {'API_KEY=not-set'}; if ($env:ANTHROPIC_AUTH_TOKEN) {'AUTH_TOKEN=set'} else {'AUTH_TOKEN=not-set'}; $env:ANTHROPIC_BASE_URL。
  3. 暂时只保留一种认证方式。为了排除冲突，可在当前终端临时取消不使用的变量：unset ANTHROPIC_AUTH_TOKEN 或 unset ANTHROPIC_API_KEY。不要直接修改生产环境配置；先在临时 shell 中验证。若使用 apiKeyHelper，还要检查 helper 是否能执行、输出是否只有预期的 token，以及是否被更高优先级变量覆盖。官方网关文档明确说明 helper 的优先级低于这两个环境变量。认证优先级说明
  4. 核对 Base URL 的职责。对官方 Anthropic API，入口和路径应按官方 API 文档使用；对兼容网关，Base URL 必须按网关提供方的 Anthropic 兼容接口说明填写。不要因为某个 OpenAI 兼容示例带有 /v1，就把它机械追加到 Anthropic 兼容地址。本文无法核实你所用网关的实际路径，因此不提供未经确认的专属地址。
  5. 重新启动 Claude Code。环境变量通常由启动进程继承。修改变量后退出当前 Claude Code 进程，再在同一终端重新运行 claude；如需查看诊断信息，可使用官方 CLI 文档列出的 claude --verbose，但应先确认日志不会暴露密钥。Claude Code CLI 参考

最小示例：用 curl 验证认证，而不是直接反复改 Claude Code

下面是一个占位模板。它适用于服务端确实提供 Anthropic Messages API 兼容入口的情况；BASE_URL、MODEL_ID 和认证方式必须替换为你已从服务商资料核实的值。无法核实的网关不要直接照抄。

export BASE_URL="${ANTHROPIC_BASE_URL:-https://api.anthropic.com}"
export MODEL_ID="your-verified-model-id"
curl -i "$BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
--data '{"model":"'"$MODEL_ID"'","max_tokens":16,"messages":[{"role":"user","content":"Reply with OK"}]}'

这个模板只适合使用 ANTHROPIC_API_KEY 和 x-api-key 的路径。若你的网关文档明确要求 Authorization: Bearer，应改用服务商规定的认证头，不要同时发送两套互相冲突的认证信息。Anthropic 的网关示例明确展示了 ANTHROPIC_AUTH_TOKEN 可用于发送 Authorization 认证；这不是所有网关都通用的规则。官方网关认证示例

成功标准：HTTP 状态不是 401，且响应体能够被解析为正常的消息响应，或至少返回了明确的模型、请求参数或权限错误。失败标准：仍为 401，且错误类型明确指向 authentication；此时不要先调整提示词、上下文长度或模型参数。

错误分流：401、403、404 和“看似 401”的情况

1. 401 authentication_error

优先核对 Key 是否复制完整、是否被撤销或过期、是否带了多余空格和换行、认证头是否符合入口要求。若使用网关，确认 Key 是网关签发的凭证，还是上游平台凭证；两者的用途可能不同。若你使用 AWS 相关接入，官方错误说明还提示 401 可能来自 AWS 凭证或 SigV4 签名，因此不能只替换 API Key。401 错误定义

2. 403 permission_error

403 与 401 的排查方向不同。官方文档将 403 定义为 Key 没有访问指定资源的权限，应该检查组织、工作区或模型访问配置，而不是反复生成 Key。若第三方网关有单独的项目、团队或路由权限，也要在该网关的管理页面核实。

3. 404 not_found_error

404 通常应先检查请求路径、Base URL 和模型或资源 ID。尤其要确认代码是否把已经包含 /v1 的地址再次拼成 /v1/v1。如果网关文档只给出一个根地址，就不要自行添加路径；如果文档给出完整 Messages API 路径，则按其要求配置。

4. 401 只在 Claude Code 出现

这通常说明直接请求使用的环境与 Claude Code 启动环境不同。逐项检查 shell、IDE 集成终端、容器、远程开发机和系统服务的环境变量是否一致。Claude Code 官方 CLI 文档提供了 --verbose 选项，可用于查看请求流程，但日志上传前必须脱敏 Key、Authorization、Cookie 和完整请求内容。CLI 调试选项

5. 实际是代理、证书或网络问题

如果没有收到标准 JSON 错误，而是连接失败、证书错误或超时，就不要归类为 401。官方代理文档说明 Claude Code 支持 HTTP_PROXY 和 HTTPS_PROXY，不支持 SOCKS 代理，并列出了需要允许访问的服务域名；企业网络应由管理员核对代理、证书和防火墙策略，不要绕过组织控制。企业代理配置

安全边界：排查 401 时不要泄露 API Key

高级内容：网关接入时如何避免把 401 归错类

Claude Code 的网关文档给出了统一 Anthropic 格式端点和 provider-specific pass-through 端点两类思路。两者的路径、认证方式和环境变量可能不同，不能把某一类示例的字段直接套到另一类服务上。若网关使用 Anthropic 格式，通常应围绕 ANTHROPIC_BASE_URL、认证变量和网关要求的模型名核验；若使用 AWS 或 Google Cloud 等平台路径，则应按对应平台的认证变量和区域要求核对。LLM 网关配置文档

建议建立一张“变量—实际值来源—启动进程—请求入口—返回状态”的小表：变量名记录是否存在，Key 只记录掩码；Base URL 记录完整路径；模型 ID 记录来源页面和核验日期；请求记录 HTTP 状态和 request ID。这样可以判断问题发生在本地配置、网关认证、上游权限还是模型路由，而不是凭经验反复改配置。

截至 2026-11-04，本文只依据本次检索到的 Anthropic 官方资料确认通用排查原则；具体第三方服务的 Key 规则、Base URL、模型 ID、价格、限速和并发仍需在其当前文档中核实。

常见问题

Claude Code API 返回 401，换一个模型能解决吗？

通常不能优先这样处理。官方将 401 定义为认证错误，先检查实际生效的 API Key、认证变量、认证头和 Base URL。只有在最小请求已经通过认证、随后出现模型或资源错误时，才需要核对模型 ID。

ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 同时设置会怎样？

不应假设两者会自动按你的预期合并。Claude Code 网关文档说明 apiKeyHelper 的优先级低于这两个环境变量，因此排查时应暂时只保留与当前网关要求匹配的一种认证方式，再重启 Claude Code 验证。

为什么 curl 成功，但 Claude Code 仍然返回 401？

最常见的排查方向是两个进程使用了不同环境：例如 curl 在当前 shell 中执行，而 Claude Code 从 IDE、容器或远程环境启动；也可能是 Claude Code 仍读取旧变量或配置。请在启动 Claude Code 的同一环境检查变量是否存在，并使用 claude --verbose 查看流程，同时脱敏日志。

Claude Code 的 401 和 403 有什么区别？

401 表示认证信息存在问题；403 表示认证可能已通过，但凭证没有访问指定资源的权限。前者重点查 Key、认证头和签名，后者重点查组织、工作区、模型或路由权限。具体错误仍应以响应状态、错误类型和 request ID 为准。

使用中转或兼容网关时，Base URL 应该怎么填？

不能凭 OpenAI 兼容接口的经验直接填写。先确认该网关是否提供 Anthropic Messages API 兼容入口，再按它的文档确定根地址、是否包含版本路径、认证头和模型 ID。本文没有核实任何特定服务的专属 Base URL，因此不提供未经确认的地址。

相关阅读

参考资料

  1. Anthropic：LLM gateway configuration
  2. Anthropic：Claude API errors
  3. Anthropic：Set up Claude Code
  4. Anthropic：CLI reference
  5. Anthropic：Corporate proxy configuration
  6. Anthropic：Claude Code SDK