返回指南
故障排查·2026年8月30日·更新于 2026年10月22日·阅读约 6 分钟

ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY——Claude Code 实际读取哪个

它们不是别名。一个会变成 `x-api-key`,另一个会变成 `Authorization: Bearer`;当两者同时设置时,你本来不想使用的那个可能会生效。针对自定义 Base URL 的“我的密钥没错但身份验证失败”报告,大多数都是这个原因。

最后审核于 。

它们不是别名。一个会变成 `x-api-key`,另一个会变成 `Authorization: Bearer`;当两者同时设置时,你本来不想使用的那个可能会生效。针对自定义 Base URL 的“我的密钥没错但身份验证失败”报告,大多数都是这个原因。

错误

两个变量
# Sent as:  x-api-key: <value>
export ANTHROPIC_API_KEY="sk-ant-..."

# Sent as:  Authorization: Bearer <value>
export ANTHROPIC_AUTH_TOKEN="sk-kn-..."

# Where those headers go:
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

原因和解决方法一览

原因解决方法
网关需要 bearer token;你却设置了 API key 变量大多数 OpenAI 兼容网关通过 `Authorization: Bearer` 进行身份验证。将网关密钥放入 ANTHROPIC_AUTH_TOKEN。
两个变量均已设置,且来自不同供应商shell 配置文件中残留的 ANTHROPIC_API_KEY 可能会与 token 一起发送。取消设置你不用的那个。
已设置 Base URL,但没有更改凭据指向新主机不会让旧供应商的密钥在那里变得有效。凭据必须随主机一起更换。
变量设置在与运行工具不同的 shell 中交互式 shell 中的导出变量不会传递给通过 GUI 启动的进程。请在同一环境中验证。

查看环境中实际保存了什么

在启动工具的 shell 中检查两者,然后再进行任何更改。相当多的此类会话实际上同时设置了两者——通常一个来自几个月前的配置文件修改,已经没人记得。

inspect-env.sh
for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s %s\n' "$v" "$(printenv "$v" | cut -c1-12)"
done

# Prefixes tell you the provider at a glance:
#   sk-ant-  Anthropic direct
#   sk-kn-   Kunavo

设置与主机匹配的一对,并取消设置另一个

将主机和凭据视为一个整体。对于第三方 Base URL,通常应使用 bearer token 加 Base URL,并明确取消设置直接 API key,使其不会被拾取。

third-party.sh
unset ANTHROPIC_API_KEY

export ANTHROPIC_AUTH_TOKEN="sk-kn-..."
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

# On Kunavo, pin served models too: Claude Code's default and its opus and
# sonnet aliases follow Anthropic's newest models, and the sonnet alias asks
# for Sonnet 5.5, which Kunavo does not serve — unpinned, that request 404s.
export ANTHROPIC_MODEL="claude-sonnet-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"

claude

在网络层确认,而不是凭想当然

如果身份验证仍然失败,就把环境因素排除掉:使用你认为正在发送的请求头,手动发出请求。如果这里返回 200,而工具中失败,说明工具没有读取你设置的变量——最常见的情况是使用了不同的 shell,或配置文件覆盖了它。

verify.sh
curl -s -o /dev/null -w '%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

2026 年 10 月 21 日起的 Anthropic SDK:API 密钥放在 Authorization: Bearer 里

从 API 版本 2026-10-21 起,Anthropic 的 SDK 改用 Authorization: Bearer 而不是 x-api-key 发送 API 密钥:Python SDK 从 2.0.0 起,TypeScript SDK 从 1.0.0 起,其他新的大版本也一样,无论密钥来自 api_key 参数还是 ANTHROPIC_API_KEY。只读取 x-api-key 的代理或网关现在会找不到密钥,并返回 401。Anthropic 的迁移指南要求修改任何读取或设置 X-Api-Key 的代理或网关,并说明 Claude API 本身两种请求头都接受(https://platform.claude.com/docs/en/api/migration-2026-10-21, 2026 年 10 月 22 日读取)。Kunavo 两种都接受:在我们 2026 年 10 月 22 日的测试中,Python SDK 2.0.0 和 2.1.0、TypeScript SDK 1.0.0 和 1.1.0 以 bearer token 形式发送密钥,较旧的版本发送 x-api-key,Kunavo 接受了每一个请求。新版 SDK 每个客户端也只持有一种凭据:代码里没有传入密钥、而 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 都已设置时,会使用 API 密钥。一个请求同时带有两种请求头时,Kunavo 使用 Authorization 那个并忽略 x-api-key,所以不要把另一个服务的 token 放进 Authorization、再把 Kunavo 密钥放进 x-api-key。Claude Code 读取变量的方式如上文所述。

sdk2_kunavo.py
import anthropic

# Python SDK 2.x sends this key as "Authorization: Bearer sk-kn-...";
# Kunavo accepts it there, and as x-api-key from older versions.
client = anthropic.Anthropic(base_url="https://api.kunavo.com", api_key="sk-kn-...")

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=32,
    messages=[{"role": "user", "content": "ping"}],
)
print(msg.content[0].text)

如果你通过 Kunavo 调用

Kunavo 从 `Authorization: Bearer` 或 `x-api-key` 中任一位置读取密钥,因此请求头不是决定因素。对于 Claude Code,有效的组合仍然是 ANTHROPIC_AUTH_TOKEN 加 ANTHROPIC_BASE_URL——token 无需 ANTHROPIC_API_KEY 所需的一次性批准即可生效——并且应取消设置 ANTHROPIC_API_KEY,而不是将其遗留,因为过期值是导致会话看似已配置却仍然拒绝请求的最常见原因。同一个 `sk-kn-` 密钥也可以作为 OpenAI 风格的 bearer token,不变地用于 /v1/chat/completions,因此一份凭据即可覆盖两种调用形式。包括应使用的模型名称在内的完整设置,见我们的 Claude Code 401 指南。

常见问题

如果两者都设置了,哪个会生效?

不要依赖这个答案——这是一个在不同版本之间发生过变化、且在不同 SDK 中也有所不同的优先级规则。只设置一个并取消设置另一个;这是唯一能在所有地方保持一致的配置。

可以将 ANTHROPIC_AUTH_TOKEN 用于 Anthropic 官方服务吗?

对 Claude Code 来说,直接调用 Anthropic 的密钥应放入 ANTHROPIC_API_KEY;token 变量用于需要 bearer 凭据的主机。Claude API 本身两种请求头里的 API 密钥都接受,所以 Anthropic 的 SDK 才能在 2026 年 10 月 21 日把密钥改到 Authorization: Bearer 里发送。

SDK 使用相同的变量吗?

Python 和 TypeScript SDK 会读取 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN。从 Python 2.0.0 和 TypeScript 1.0.0 起,它们以 Authorization: Bearer 发送 API 密钥;更早的版本以 x-api-key 发送。如果将 SDK 指向网关,请显式传入凭据,不要依赖环境变量。

相关指南

更多错误语义请参阅 错误参考;通过 注册 和 身份验证指南 获取密钥只需一分钟。