报错速查 · 截至 2026-11-20

Claude Code 自定义 API 地址报错 401:Invalid API key 与 AUTH_TOKEN 逐条排查

截至 2026-11-20,配了自定义地址后出现 401,原因基本落在四处:key 和地址不是同一家、ANTHROPIC_API_KEY 与 ANTHROPIC_AUTH_TOKEN 用反、设置文件 env 里留着旧值、地址多写了 /v1。先跑 /status 看当前生效的 Anthropic base URL 与 Auth token 两行,再按这两行只留一个凭据变量。

更新于 2026-11-20

一把 Key 调用 Claude、GPT 与主流国产模型,按 token 计费,几分钟上手。

#401 Invalid API key#ANTHROPIC_BASE_URL#AUTH_TOKEN 与 API_KEY#settings.json 旧值

四个先记住的值

401

凭据被拒,不是网络故障

官方在 API 错误码里把 401 定义为 authentication_error:key 本身有问题,比如格式不对、被撤销或已过期。地址指向网关时,401 后面那段文字是网关写的,不是 Anthropic 写的。

x-api-key

ANTHROPIC_API_KEY 走这个请求头

官方认证文档写明它按 X-Api-Key 头发送,用于直连 Anthropic API;同时存在订阅登录时,它一旦被批准就优先于登录生效,这正是「明明登录着却报凭据错」的来源。

Bearer

ANTHROPIC_AUTH_TOKEN 走这个请求头

它的值会被加上 Bearer 前缀放进 Authorization 头,给按 bearer token 认证的网关或代理用。官方建议:没被告知该用哪一个时,先用它。

/status

先看当前生效的地址与凭据

官方网关文档只在你设了网关地址时才显示 Anthropic base URL 行;看到 Auth token 或 API key 行才说明网关凭据生效,看到 Login method 行说明用的是登录态。

自定义地址下的 401 到底是什么

Claude Code 自定义 API 地址报错 401,问题不在网络,而是这次请求带的凭据不被对面接受。官方把 Invalid API key 解释为:ANTHROPIC_API_KEY 或 apiKeyHelper 脚本给出的 key 被 API 拒绝,或者 Claude Code 在发出去之前就把这个 key 拦下了。

另一条 API Error: 401 Invalid authentication credentials 更明确:API 认得出凭据的格式,但拒绝凭据背后的账号或组织,所以过期 token 并不是原因。再加上第三种情况——地址指到网关时,401 之后的文字是网关自己的报错,/login 改不了它,得换成网关要的那种凭据。三种情况的第一动作都一样:先看 /status 显示的是哪个地址、哪一种凭据。

截至 2026-11-20 与这条 401 相关的两个变化

  1. 1网关侧多了一个 401 来源:官方报错文档写明,如果网关已经拿到它要的凭据、请求仍然全部 401,要检查网关是否接受 tool search 字段;v2.1.304 之前,网关后面的 tool search 默认是关的,除非你打开 ENABLE_TOOL_SEARCH。
  2. 2apiKeyHelper 失败的表现换了:脚本拿不到 key 时,请求会带着占位凭据打到 API,被 401 拒掉;v2.1.208 之前,Claude Code 会把整个重试预算花在用这个占位凭据重发请求上,最后报的是一个通用的 401 authentication error,而不是脚本失败;v2.1.208 起,脚本出错、超时或什么都不输出时,三次尝试内就报 Your apiKeyHelper script is failing。

三个时间点:变量分工、设置文件写法、网关侧新增的 401

2026-07-05

社区排错讨论里常见的经验是:自定义端点用 ANTHROPIC_AUTH_TOKEN,直连 api.anthropic.com 用 ANTHROPIC_API_KEY。按这条分工,网关地址配 Anthropic 的 key、或直连地址配网关 key,请求头都对不上,对面只能回 401。

2026-11-11

社区排错讨论里常见的经验是:把地址和网关密钥写进 ~/.claude/settings.json 的 env,而不是只在终端里 export;反复出现的两条是地址只填到域名、不要带 /v1,以及两个变量同名时以设置文件里的值为准。

2026-11-20

网关已拿到正确凭据、请求却全部 401 时,要检查网关是否接受 tool search 字段,v2.1.304 之前该功能在网关后面默认关闭,需要 ENABLE_TOOL_SEARCH 打开;同时 /status 的 Anthropic base URL 行只在设置了网关地址时出现。

官方已核实的部分 vs 社区说法与官方未公布的部分

已核实(Claude Code 官方报错、认证、环境变量、网关与设置文档,Anthropic API 错误码文档)

  1. 1两条报错的原文与含义:Invalid API key · Fix external API key 表示 ANTHROPIC_API_KEY 或 apiKeyHelper 给出的 key 被拒,或 Claude Code 在发送前就拦下了它;API Error: 401 Invalid authentication credentials 表示格式认得、账号或组织被拒,过期 token 不是原因。
  2. 2请求头分工:AUTH_TOKEN 加 Bearer 前缀进 Authorization 头,API_KEY 走 X-Api-Key 头。
  3. 3优先级:AUTH_TOKEN 排在 API_KEY 之前,两者都在时登录态排在更后面;命令行交互模式下 API_KEY 需要你批准一次,-p 模式下有 key 就用。
  4. 4网关场景:地址指向网关时,401 后面的文字是网关的消息,/login 不改变它;凭据要按网关要求放在 AUTH_TOKEN、API_KEY 或 apiKeyHelper 之一。
  5. 5设置文件:env 块让配置在所有运行 Claude Code 的地方生效,用户级 ~/.claude/settings.json 管所有项目,.claude/settings.local.json 只管一个项目,项目里的 .claude/settings.json 会被提交、不能放凭据。
  6. 6对照:403 是权限不足,429 是速率或花费上限,529 是服务过载,都不是凭据问题。

社区说法与官方未公布的事项

  1. 1「地址后面加 /v1 更保险」:社区讨论里说的是地址末尾不要带 /v1,/v1/messages 由 Claude Code 自己拼;官方验证请求也写成 $ANTHROPIC_BASE_URL/v1/messages,可见 /v1 不在变量里。QCode 的值就是 https://api.qcode.cc/api,末尾再多写一段 /v1 一样会拼成 /v1/v1/messages。
  2. 2「终端 export 一定生效」:官方提醒 direnv、dotenv 插件和 IDE 终端会从项目 .env 里载入旧 key;社区还反映同名变量以设置文件为准,所以先看 /status 再改终端。
  3. 3「重新 /login 就能盖掉 API key」:不成立,官方写明已批准的 API key 优先于登录,/login 不会替换它,要 unset 或换 key。

两条路:API_KEY 直连 vs AUTH_TOKEN 走网关

ANTHROPIC_API_KEY:直连 Anthropic API 的 Console key

它按 X-Api-Key 头发送,来源是 Claude Console。交互模式下第一次使用会让你批准,之后记住;-p 非交互模式下只要有这个变量就会用。它优先于订阅登录,所以「订阅还在、却一直 401」要先查的就是它:去 Console 轮换 key,或者 unset 后回到订阅。

ANTHROPIC_AUTH_TOKEN:网关或中转要的 bearer 凭据

它的值会被加上 Bearer 前缀放进 Authorization 头,给按 bearer token 认证的网关用。接 QCode 时地址是 https://api.qcode.cc/api(不带 /v1),凭据填 cr_ 开头的 key;同时 unset ANTHROPIC_API_KEY,别让两套凭据并存。官方建议:网关没说明用哪一种时,先用 AUTH_TOKEN,再用验证请求确认。

照做的六步:从报错原句查到重启验证

  1. 1读报错原句分三种:Invalid API key · Fix external API key 是 key 被拒或在发送前被拦;API Error: 401 Invalid authentication credentials 是格式对、账号或组织被拒;地址指向网关时,401 后的文字是网关的话,先按网关要求换凭据,别急着 /login。
  2. 2跑 /status,看 Anthropic base URL 行在不在、是哪个地址,再看 Auth token 或 API key 行,确认当前生效的是哪一种凭据。
  3. 3打开 ~/.claude/settings.json,检查 env 块里有没有旧的 ANTHROPIC_BASE_URL 或旧 key;同一个变量在设置文件里也写了一份时,终端里改的值不一定生效。项目里的 .claude/settings.json 会提交,凭据不要放那里。
  4. 4只留一个凭据变量:网关用 ANTHROPIC_AUTH_TOKEN,然后 unset ANTHROPIC_API_KEY;直连 Anthropic 反过来,用 ANTHROPIC_API_KEY 并清掉 AUTH_TOKEN。
  5. 5核对地址:QCode 的 Claude Code 地址是 https://api.qcode.cc/api,不带 /v1;Codex 走 https://api.qcode.cc/openai,两套不要混用。
  6. 6重启 claude,用 curl 发一次最小请求:POST $ANTHROPIC_BASE_URL/v1/messages,带 Authorization: Bearer $ANTHROPIC_AUTH_TOKEN 与 anthropic-version: 2023-06-01;返回 401 就换另一个变量重试,返回 JSON 就说明地址与凭据都对了。

QCode 侧的接法:一个地址、一个变量

QCode 是独立的 API 接入服务,与 Anthropic、OpenAI 等厂商无隶属关系。Claude 系型号只走 Anthropic Messages 端点:ANTHROPIC_BASE_URL 填 https://api.qcode.cc/api(不带 /v1),ANTHROPIC_AUTH_TOKEN 填 cr_ 开头的 key,同时 unset ANTHROPIC_API_KEY,避免两套凭据并存。

把它们写进 ~/.claude/settings.json 的 env 后重启 claude,再用 /status 看这两行是否生效。Codex 是另一套地址 https://api.qcode.cc/openai,别和 Claude Code 混用。按 token 计费,各模型单价见 /models。不想包月?按量包 ¥26 起买一笔额度,7 天内用完为止;已有个人套餐的用户额度不够时买加油包。

常见问题

为什么终端里 export 了 ANTHROPIC_AUTH_TOKEN,Claude Code 还是 401?

先跑 /status,看 Auth token 或 API key 行显示的到底是哪一份凭据、Anthropic base URL 行指着哪个地址——官方就是用它确认凭据来源的。三类原因:一是设置文件里还有旧值,写进 ~/.claude/settings.json 的 env 会让配置在所有运行 Claude Code 的地方生效,终端里的新值不一定压得住它;二是别处塞进来的旧 key,官方提醒 direnv、dotenv 插件和 IDE 终端会从项目 .env 里载入你没有显式设置过的 key,可以在同一个 shell 里跑 env | grep ANTHROPIC 看一眼;三是地址与 key 不同家,自定义端点配了 Anthropic 的 key,或者直连地址配了网关的 key。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 有什么区别?

区别在请求头和用途。ANTHROPIC_AUTH_TOKEN 的值会被加上 Bearer 前缀,作为 Authorization 头发出去,用于以 bearer token 认证的网关或代理;ANTHROPIC_API_KEY 走 X-Api-Key 头,用于直连 Anthropic API 的 Console key。官方给的优先级里 AUTH_TOKEN 在前、API_KEY 在后,两者同时存在时用 AUTH_TOKEN;所以接网关时保留前者、unset 后者,直连时反过来。拿不准网关要哪种时,官方建议先用 AUTH_TOKEN,再发一次验证请求确认。

ANTHROPIC_BASE_URL 要不要加 /v1?

不要。地址末尾不要再加 /v1,/v1/messages 这一段由 Claude Code 自己拼;官方验证请求写的就是 $ANTHROPIC_BASE_URL/v1/messages,说明 /v1 不在变量值里。末尾多写一段会拼成 /v1/v1/messages,网关找不到路径,可能回一个看着像凭据问题的 401。QCode 的值就是 https://api.qcode.cc/api,其中的 /api 属于地址本身,不是 /v1 那种重复段;同一条规则不适用于所有客户端,OpenAI 兼容的 SDK 与 Codex 用的是带 /openai 或 /openai/v1 的地址。

401 和 403 有什么区别?

401 是凭据本身有问题:官方 API 错误码把它定义为 authentication_error,指 key 格式不对、被撤销或过期。403 是 permission_error,key 本身有效,但没有权限访问指定资源,要去 Console 看组织与 workspace 的访问设置。还有一个例外值得记住:如果 401 的文字以 CORS requests are not allowed for this Organization 开头,那不是 key 的问题,而是请求从浏览器直接发出了 Origin 头,改后端发请求即可,换 key 没用。

429 和 529 是不是 key 的问题?

不是,这两个数字与凭据无关,换 key 解决不了。429 是 rate_limit_error:组织命中了速率限制、用量档的月度花费上限,或 Claude Code workspace 的花费上限;这种 429 可能一直失败到额度恢复,而且不带你熟悉的 retry-after 头。529 是 overloaded_error:API 临时过载,官方说明它可能在全体用户流量高时出现。官方 SDK 会自动重试这类瞬时失败,默认重试两次并遵守 retry-after。

apiKeyHelper 报错、或者一直 401 怎么办?

先把脚本单独跑一遍,确认它把有效的 key 打印到 stdout——这是官方给的第一条排查动作。脚本拿不到 key 时,请求会带着占位凭据打到 API,被 401 拒掉:v2.1.208 之前,Claude Code 会把整个重试预算花在用这个占位凭据重发请求上,最后报一个通用的 401 authentication error,而不是脚本失败;v2.1.208 起,脚本出错、超时或什么都不输出时,三次尝试内就报 Your apiKeyHelper script is failing。脚本超过 10 秒才返回 key 时,提示栏会出现一条带耗时的警告。如果脚本正常、请求还是 401,就看 /status 里生效的到底是不是这个脚本的输出,因为 AUTH_TOKEN 和 API_KEY 排在 apiKeyHelper 前面,环境里留着它们,脚本的 key 根本用不上。另外,Claude Desktop 与云端会话不调用 apiKeyHelper、也不读这些环境变量。

参考来源

Claude Code 官方报错文档 code.claude.com/docs/en/errors(核对于 2026-11-20);官方认证与优先级文档 code.claude.com/docs/en/authentication(核对于 2026-11-20);官方环境变量文档 code.claude.com/docs/en/env-vars(核对于 2026-11-20);官方 LLM 网关接入文档 code.claude.com/docs/en/llm-gateway-connect(核对于 2026-11-20);官方设置文件文档 code.claude.com/docs/en/settings(核对于 2026-11-20);Anthropic API 错误码文档 platform.claude.com/docs/en/api/errors(核对于 2026-11-20);社区说法来自公开讨论帖,正文已标注为社区反映。以上均核对于 2026-11-20。

把地址和凭据对齐,再用 /status 与一次请求验证

注册账号生成 cr_ key,在 Claude Code 里填 ANTHROPIC_BASE_URL=https://api.qcode.cc/api 与 ANTHROPIC_AUTH_TOKEN,按 token 计费,各模型单价见 /models。

不确定从哪开始?

先试一周

小包 ¥26($30 额度,7 天)

每天都用

体验版 ¥63/月,每天 $5 额度;每 $1 额度只要 ¥0.42,中包约 ¥0.79