Claude API 身份验证指南:Anthropic/AWS/Google/Azure
本文详解在 Linux 服务器上配置 Claude API 的四种身份验证方式,涵盖 Anthropic API 密钥、AWS Bedrock IAM、Google ADC 及 Microsoft Entra 凭据设置,助您安全管理生产环境访问权限。
Claude API 的身份验证路径
Claude API 身份验证归根结底取决于一个选择:客户端通过网络发送哪种凭据。Anthropic 列出了直接 Claude API 以及 5 个云平台:Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 上的 Claude Models(Google 托管)、Google Cloud 上的 Claude Models(Anthropic 托管)和 Microsoft Foundry。直接 Anthropic API 接受 API 密钥或短期令牌,这些凭据通过 Authorization: Bearer 标头发送;同时仍接受通过旧版 x-api-key 标头发送的 API 密钥。Amazon Bedrock 支持 AWS 请求签名和 Bedrock API 密钥,在此配置中任何位置都不需要 Anthropic 密钥。Google Cloud 发送短期 Google 访问令牌。Microsoft Foundry 接受 Azure 签发的密钥或 Microsoft Entra 令牌。下面 4 个部分介绍这些凭据配置,并分别说明 Anthropic 托管的 AWS 和 Google Cloud 服务及其对应的云平台。
本指南介绍如何将 SDK(软件开发工具包)接入运行在 Linux 服务器上的服务。如果您配置的是 Claude Code 命令行工具,变量和流程会有所不同,请参阅 将 Claude Code 指向 Bedrock 或 Vertex。注意,中文里的“身份验证”也常指另一件事:如果您是因为 Claude 要求上传证件照片和自拍而来到这里,那属于账户身份核验,与 API 凭据无关,请参阅 Claude 身份验证能否使用中国护照和居民身份证。如果服务尚不存在,请先按照 在 VPS 上构建第一个 Claude API 应用 完成构建,然后返回此处配置凭据。
以下内容已于 August 2026 根据 Anthropic 平台文档完成检查,并于 16 October 2026 根据各提供商的文档重新检查;Bedrock 模型访问详情已于 19 October 2026 根据 AWS 文档重新检查。Anthropic 关于这 4 条路径、API 密钥和 API 版本的页面已于 27 October 2026 重新检查。Anthropic 关于 Microsoft Foundry、两个 Bedrock 端点、Google 托管路径、AWS 上的 Claude Platform、身份验证、Workload Identity Federation 和 API 版本的页面已于 10 November 2026 重新检查,同时也检查了 Ruby SDK 的更新日志。模型标识符、价格、SDK 版本和端点形式都会变化,因此本指南链接到提供商页面,而不是直接列出容易过时的值。
路径 1:Anthropic API 密钥
这是直接访问路径,也是 Anthropic 签发密钥的唯一方式。请求发送至 Anthropic API 主机的 Messages 端点,且每个请求均需携带三个标头。
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": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'将 MODEL_ID 替换为 Anthropic 模型概览中的当前标识符。正常的响应是一个包含 content 数组和 usage 对象的 JSON。密钥错误或过期会返回 HTTP 401 错误及 authentication_error。缺少 anthropic-version 标头会导致另一种失败,因为该标头在每个请求中都是必需的;SDK 会自动为您设置。截至 2026 年 10 月,Anthropic 文档将 Authorization: Bearer 作为发送密钥的主要方式,并将 x-api-key 称为旧版,但两者均被接受,因此上述命令仍然有效。当前的 SDK 主版本也会将密钥作为 Authorization: Bearer 发送,因此读取 X-Api-Key 的代理或网关在升级时需要进行相应调整。命令中的 2023-06-01 版本仍被接受;Anthropic 最新的 API 版本是 2026-10-21,SDK 默认发送该版本,且该版本会拒绝某些旧的请求参数(如 temperature)。
客户端构建是这些设置中最简短的,因为无需构建任何内容。每个官方 SDK 都会自动从环境变量中读取 ANTHROPIC_API_KEY。
import os
from anthropic import Anthropic
client = Anthropic() # reads ANTHROPIC_API_KEY from the environment
message = client.messages.create(
model=os.environ["CLAUDE_MODEL"],
max_tokens=64,
messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)将模型标识符与密钥一同存放在环境变量中是值得推荐的做法。模型名称的变更不受您控制,通过重新部署代码来修改字符串是完全可以避免的工作。
密钥在控制台(Console)中创建,创建时需选择有效期:预设选项包括 3 小时、1 天、7 天或 30 天,也可自定义时长或选择“永不过期”(受限于您所在组织的最高有效期策略)。有效期在创建时固定,事后无法更改。 Anthropic 会在长期密钥过期前向创建者发送邮件提醒,但短期密钥过期时不会有任何预警邮件。过期的密钥会返回 401 错误且无法重新激活,因此唯一的解决方法是创建新密钥。
直接访问 API 时无需选择区域,费用直接计入您的 Anthropic 组织账单。工作区(Workspaces)可将密钥限制在单个项目内,这是查看单个服务开销最清晰的方式。创建服务器密钥时,请将其限定在对应的工作区内:未限定工作区的个人或服务账户密钥必须在每个请求中发送 anthropic-workspace-id 标头,否则 API 会返回 400 错误及 invalid_request_error。对于服务,请选择服务账户密钥,因为个人密钥会在创建者离开组织后失效。关于账单计算的详细说明,请参阅 按 Token 计费与订阅模式的对比。
此处还需提及另一个选项,因为它完全消除了静态密钥。工作负载身份联合(Workload Identity Federation)允许工作负载将来自您已信任的身份提供商的 OpenID Connect (OIDC) 令牌,在 POST /v1/oauth/token 处兑换为短期的 Anthropic 令牌,且 SDK 会在令牌过期前自动刷新。过程中不会生成或复制任何 sk-ant-api... 字符串。该方案适用于已具备平台身份的 Kubernetes、GitHub Actions 和云虚拟机。普通的 VPS 通常没有此类颁发者,因此在这些机器上,将 API 密钥存放在文件中是务实的做法,本指南的其余部分也将以此为前提。
路由 2:Amazon Bedrock 上的 AWS 凭证
在 Bedrock 上,您完全不需要 Anthropic 密钥。使用 AWS 凭证时,SDK 会使用 AWS Signature Version 4 (SigV4) 为每个 HTTP 请求签名,由 AWS 决定该调用方是否可以调用模型。
pip install -U "anthropic[bedrock]"
aws sts get-caller-identityaws sts get-caller-identity会输出您的凭证解析到的身份的账户编号和 ARN(Amazon Resource Name,Amazon 资源名称)。使用 SigV4 时,必须在执行其他操作前运行它。对于 SigV4,SDK 会解析构造函数凭证、环境凭证和标准 AWS 凭证链;区域选择则是独立的。在 Python 的 AnthropicBedrock 客户端中,如果您同时传入 aws_access_key、aws_secret_key、aws_session_token 或 aws_profile,通过 api_key 或 AWS_BEARER_TOKEN_BEDROCK 提供的 Bedrock API 密钥会触发 ValueError。如果不传入这些显式参数,该密钥会选择 bearer 身份验证,而不是 AWS 凭证链。TypeScript 客户端会优先使用 Bedrock API 密钥,而不是显式 AWS 凭证。STS 命令不会测试 bearer 身份验证。
客户端构造的变化在于类和一个参数。
from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")AnthropicBedrock负责驱动 Bedrock 的 InvokeModel 集成。截至 October 2026,Anthropic 还记录了 Amazon Bedrock 上的 Claude:对于 Claude Opus 4.7 及更高版本的模型,可通过 AnthropicBedrockMantle 客户端访问 https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages 处的 Messages API 端点,该客户端来自同一个软件包。它支持 AWS 凭证和 Bedrock bearer 令牌;两个端点的模型访问要求不同,详见下文。
注意 pip install -U 这一行的升级。截至 27 October 2026,最新 SDK 默认发送 API 版本 2026-10-21,包括通过 Bedrock 发送时。Anthropic 说明,它为 Claude Opus 4.6 及更早版本列出的 ARN 版本化模型 ID 在 Bedrock 上不支持该版本,并且可能返回 400 错误。如果某项服务调用这些模型,请保持 SDK 使用当前运行的版本并将其固定,或者先将该服务迁移到 Claude 4.7 或更高版本的模型。
在这里,区域不再只是装饰。Bedrock 端点按区域划分,各区域提供的 Claude 模型不同,而且区域属于 SigV4 签名的一部分,因此为一个区域计算的签名会被另一个区域拒绝。请在服务环境中显式设置 AWS_REGION,因为省略该设置时,各 SDK 的行为并不一致。根据 October 2026 的文档,Python AnthropicBedrock 客户端会读取 AWS_REGION 或 AWS_DEFAULT_REGION,然后读取 boto3 会话或 AWS 配置文件中的区域(包括 ~/.aws/config);如果都无法解析,则会引发 ValueError。TypeScript 客户端会读取 AWS_REGION;如果未设置,则回退到 us-east-1,并且不会读取 ~/.aws/config 来确定区域。因此,在同一台主机上,AWS CLI 可以成功列出 Claude 模型,而 Node 进程却调用错误的区域:CLI 读取了您的配置文件,但客户端没有读取。
在 EC2 实例上,您可以附加 IAM(身份和访问管理)角色,磁盘上不会保存任何密钥,因为实例元数据服务会向 SDK 提供临时凭证。AWS 之外的 VPS 既没有实例角色,也没有元数据服务。此时,您可以选择将 IAM 用户的长期访问密钥对保存在主机上;这类密钥与 Anthropic 密钥属于同一类机密。您也可以使用联合身份验证:向身份提供商进行身份验证,调用 AWS STS(安全令牌服务),并使用它返回的临时凭证。Bedrock 还接受 Bedrock API 密钥。这些密钥会通过 AWS_BEARER_TOKEN_BEDROCK 作为 bearer 令牌传递,AWS 记录了两种类型。短期密钥的有效期最长为 12 小时;如果生成该密钥的会话总时长更短,则有效期以该会话的总时长为限。它继承生成该密钥的 IAM 身份的权限,也是 AWS 为生产环境推荐的类型。长期密钥会持续到创建时选择的过期时间(例如使用 --credential-age-days 设置为 30 或 90 天);如果省略该 API 参数,则不会过期。控制台会在其后创建一个 IAM 用户,AWS 仅建议将这种密钥用于探索。长期密钥只能在生成它的区域使用;在其他区域使用时会返回 Credential should be scoped to a valid region。
账单会记在您的 AWS 账户,而不是 Anthropic 账户上。这通常正是选择此方案的主要原因。根据 October 2026 的文档,区域端点比全局端点贵 10%。AWS 上的 Claude Platform 是独立产品:由 Anthropic 运营,通过 AWS Marketplace 由 AWS 计费,并使用 SigV4 或 AWS 控制台中生成的 API 密钥进行身份验证(Claude 控制台生成的密钥在此处不可用)。它通过 AnthropicAWS 客户端提供,Anthropic 将该客户端标记为 beta。有一个 Bedrock 错误值得识别,因为它看起来像权限问题,但实际并不是:Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. 这是模型路由问题,修改凭证无法解决。
路由 3:Vertex AI 上的 Google 凭据
Anthropic 的文档现在将此路由称为 Google Cloud 上的 Claude 模型(Google 管理),这是 Google 作为其 Agent Platform(Google 对原 Vertex AI 演进产品的命名)的一部分来运行的。下文显示的 aiplatform.googleapis.com 主机、anthropic[vertex] 额外参数和 AnthropicVertex 类保持不变。
Google Cloud 使用应用默认凭据 (ADC),这是 Google 认证库在无需手动指定凭据时所遵循的固定搜索顺序。ADC 首先检查 GOOGLE_APPLICATION_CREDENTIALS,然后是 gcloud auth application-default login 写入的文件,最后是附加在元数据服务器上的服务账号。
pip install -U "anthropic[vertex]"
gcloud auth application-default login在工作站上,登录操作会写入 $HOME/.config/gcloud/application_default_credentials.json,配置即告完成。在服务器上,应避免存储个人用户的凭据;该命令也支持服务账号模拟。在 Google Cloud 外部,不存在 Google 元数据服务器,因此请使用 GOOGLE_APPLICATION_CREDENTIALS 将 ADC 指向工作负载身份联合 (Workload Identity Federation) 配置文件或服务账号密钥文件。服务账号密钥 JSON 文件属于长期有效的机密信息,必须严格按照本指南后续描述的方式进行处理。在 Google Cloud 内部,只需将服务账号附加到 VM,无需保护任何文件。无论 ADC 找到哪种身份,该身份都需要具备包含 aiplatform.endpoints.predict 权限的 IAM 角色,例如 Agent Platform User (roles/aiplatform.user)。
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")如果放弃 SDK 而直接使用原始 HTTP 请求,则有两个变化。模型标识符从请求体移至 URL 路径中,anthropic_version 从请求头移至请求体中。截至 2026 年 10 月 27 日,Anthropic 的文档同时接受 vertex-2023-10-16 或更新的 API 版本 2026-10-21。凭据为普通的 Google 访问令牌。在下方的命令中,gcloud auth print-access-token 使用 gcloud CLI 自身的登录信息而非 ADC,因此请先在测试机器上运行 gcloud auth login 或 gcloud init。
curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'区域是核心参数。global 可根据可用性动态路由,us 和 eu 是多区域标识符,而类似 us-east5 的名称则锁定单个区域。截至 2026 年 10 月,Anthropic 仅针对 Claude Sonnet 4.6 及更早版本记录了单区域端点;较新的模型使用全局或多区域端点。根据 2026 年 10 月的文档,多区域和区域端点的费用比全局端点高出 10%。计费通过 Google Cloud 项目进行,因此配额和账单均由 Google 管理。
截至 2026 年 10 月 27 日,Anthropic 还记录了另一种 Google Cloud 产品,其请求格式有所不同。在 Google Cloud 上的 Claude 模型(Anthropic 管理)中,Anthropic 在 claude.googleapis.com 自行运营 Claude API,并通过 AnthropicGoogleCloud 客户端访问。它仍然使用 Google Cloud 凭据(包括 ADC)进行身份验证,但请求格式与直接 API 相同:model 保留在请求体中,版本号位于 anthropic-version 请求头中。访问权限来自其自身的 IAM 角色(roles/claude.user 及相关角色),设置过程会为该项目创建一个新的 Anthropic 组织,使用费用通过 Google Cloud Marketplace 结算。如果您的请求 URL 包含 aiplatform 并以 :rawPredict 结尾,则您正在使用本节所述的 Google 管理路由。
路径 4:Microsoft Foundry 是 Azure 路径
如果您搜索的是 Azure 上的 Claude,那么需要查看的就是本节,并且确实存在受支持的路径。Claude 运行在 Microsoft Foundry(原 Azure AI Foundry)中,通过 Azure Marketplace 按 Claude Consumption Units 计费。您需要创建 Foundry 资源,在其中部署 Claude 模型,然后调用 Azure 托管的端点 https://{resource}.services.ai.azure.com/anthropic/v1/*。
有两种凭据可用。第一种是 Azure 签发的密钥,可在 Foundry 门户中部署的 Details 选项卡找到,并通过 api-key 或 x-api-key 标头发送。第二种是 Microsoft Entra 令牌。对于服务器,后者更合适,因为 Azure 基于角色的访问控制可以控制哪些主体能够调用该端点。
ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
-H "content-type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'model 字段携带的是部署名称,而不是模型标识符。默认情况下二者相同;但只要您自行命名部署,二者就会变得不同。这通常是请求本身正确但仍出现 Deployment not found 错误的原因。Python 和 TypeScript SDK 会从环境中读取 ANTHROPIC_FOUNDRY_API_KEY 和 ANTHROPIC_FOUNDRY_RESOURCE。截至 10 November 2026,Foundry 支持全部 7 个官方 SDK:C#、Go、Java、PHP、Python、Ruby 和 TypeScript。Go 使用专用的 foundry 软件包(go get github.com/anthropics/anthropic-sdk-go/v2/foundry);Ruby 的 gem 在 4 November 2026 发布的 2.5.0 版本中新增了专用的 Anthropic::FoundryClient。在该版本发布前,Ruby 代码必须将通用客户端指向 Foundry 基础 URL。
将通用客户端指向 Foundry 基础 URL 仍有一个容易出错的地方。无论是 2.5.0 之前编写的 Ruby 代码,还是 ant CLI,情况都一样;Anthropic 自己的 Foundry 示例也采用这种方式。如果您没有显式向通用客户端传递凭据,而环境中仍设置了 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN,客户端就会读取该变量,并将您的 Anthropic 凭据发送到 Microsoft 端点。请取消设置该变量,或显式向客户端传递 Foundry 密钥或令牌。在 Ruby 中,改用 Anthropic::FoundryClient 是更简洁的修复方式;它接受 Foundry 密钥或 Entra 令牌提供程序。Entra 访问令牌的默认有效期为随机的 60 到 90 分钟,因此长时间运行的进程必须刷新令牌,不能在启动时只获取一次。
服务器上的凭据可以使用多长时间?
此图表背后的数据
[
{
"label": "Anthropic key, 30-day preset",
"max_lifetime_hours": 720
},
{
"label": "Anthropic key, 7-day preset",
"max_lifetime_hours": 168
},
{
"label": "AWS STS assumed role",
"max_lifetime_hours": 12
},
{
"label": "Bedrock short-term API key",
"max_lifetime_hours": 12
},
{
"label": "Entra ID access token, default upper bound",
"max_lifetime_hours": 1.5
},
{
"label": "Federated Anthropic token, default",
"max_lifetime_hours": 1
}
]这些时长上限和默认值由各提供商发布,并于 2026 年 10 月读取,不是实测数据。它们之所以重要,是因为它们说明:凭据泄露后,在您发现泄露之前,攻击者还能使用该凭据多长时间。图表底部的联合 Anthropic 令牌默认最长可用 1 小时,同时还受身份提供商令牌剩余有效期两倍的限制。Microsoft Entra 访问令牌没有单一的默认时长:Microsoft 会为每个令牌随机分配 60 到 90 分钟的有效期(平均 75 分钟),图表以其 1.5 小时的上限显示;此外,默认时长还会因客户端、资源以及租户是否启用 Conditional Access 而变化。当客户端和资源都支持 Continuous Access Evaluation 时,Entra 可能将有效期延长到 24 到 28 小时,并在账户被禁用等事件发生时近乎实时地撤销令牌。租户令牌生命周期策略可将有效期设置为 10 分钟到 23:59:59 之间的任意值。SDK 会自动刷新联合 Anthropic 令牌;在 Foundry 上,应配置 Entra 令牌提供程序来刷新令牌,而不是传递固定的令牌字符串。联合规则可以将令牌有效期设置为 1 分钟到 24 小时之间的任意值,而 Console 的 Connect 工作负载向导会预填 10 分钟,因此应读取规则,不要假设默认值。AssumeRole 获得的角色凭据和 Bedrock 短期 API 密钥的有效期都为 12 小时。Bedrock 长期 API 密钥不在图表中,因为它没有固定的有效期上限:它会持续到创建时指定的过期时间;如果 API 调用中省略了 CredentialAgeDays,则不会过期。因此,AWS 只建议将其用于探索。使用 30 天预设创建的密钥会保持有效 720 小时,这就是会在服务器文件中存放一个月的凭据。
凭据在 VPS 上的存放位置
将密钥存放在仅 root 可读的文件中,并由 systemd 将其传递给进程。此方案不受 SDK 版本更迭影响,因此值得一次性正确配置。
sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env该文件包含纯文本的 KEY=value 行。不要使用 export、引号或 shell 语法,因为 systemd 会自行解析文件,而不会通过 shell 运行。
ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME[Unit]
Description=Claude API service
After=network-online.target
[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure
[Install]
WantedBy=multi-user.targetsystemd 以 root 身份读取 EnvironmentFile=,随后才会降权至 User=claudeapp,因此服务账户无需该文件的读取权限。将文件权限设为 600 并归属 root 即可,这也是上述 install 命令执行此操作的原因。使用 sudo systemctl enable --now claude-app 启动服务,然后通过 systemctl status claude-app 确认单元已达到 active (running) 状态,而非陷入重启循环。
请避免以下四种做法,每种做法都有其原因:
- 不要将密钥直接写入
Environment=单元文件中。位于/etc/systemd/system下的单元文件对所有用户可读,因此systemctl cat claude-app会将密钥泄露给任何本地用户。 - 不要将其提交到版本控制系统。
.gitignore仅能防止新文件被提交,对已提交的文件无效,因为 git 历史记录会保留所有历史版本。 - 不要将其打包进容器镜像。
ENV的值会持久化在镜像配置中,且构建参数在镜像历史或来源元数据中可见。在后续层中删除该文件并不能将其从之前的层中移除。请通过--env-file或挂载文件的方式在运行时传递密钥。 - 不要认为进程环境变量对 root 是私密的。
sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n'会将密钥打印出来。读取文件的命令本身需要sudo;shell 输入重定向会在sudo之前执行,并使用你当前账户的权限。此设计的目的是防止除 root 以外的其他账户获取密钥,而 root 无论如何都能读取文件。
最后一点界定了该方案的保护范围。仅限 root 读取的文件保护了存储的密钥,但任何以服务账户运行的代码都可以读取进程环境,且子进程会继承该环境。如果进程运行了非你编写的代码,该方案则不适用,因为进程执行的任何内容都能读取其自身环境。防止 AI 代理获取密钥 涵盖了这种情况,这是一个需要不同方案解决的独立问题。
如何实现密钥轮换且不造成停机?
向前轮换,最后撤销。下文所述的单服务重启会造成短暂的服务中断;若需保持不间断可用性,则需在重启期间由另一个实例处理请求。
- 在控制台中,于旧密钥所在的同一工作区内创建新密钥。
- 使用
sudoedit将其写入/etc/claude-app/env。 - 运行
sudo systemctl restart claude-app。 - 确认服务正在响应请求,然后在控制台中撤销旧密钥。
EnvironmentFile 在单元启动时被读取,因此正在运行的进程会保留其启动时获取的值。systemctl daemon-reload 会重新读取单元文件,但不会触及运行中进程的环境变量,因此只有重启才能加载新密钥。若在第 1 步而非第 4 步执行撤销,会导致服务中断,中断持续时间直至第 3 步完成。
云路由在提供商侧进行轮换。IAM 用户支持同时存在两个活跃的访问密钥,因此请先创建第二个并部署,然后再删除第一个。Google 服务账号密钥的轮换方式相同。Foundry 资源携带两个密钥,重新生成其中一个会立即导致其旧值失效,因此在重新生成服务当前使用的密钥前,请先将服务切换至另一个密钥。Entra 令牌和联合 Anthropic 令牌无需手动轮换,这也是在可行情况下优先使用它们的最有力理由。
在控制台操作时,请为工作区设置消费限额。密钥泄露带来的首要后果就是高额费用,限制 VPS 上代理的消费额度 一文详细介绍了相关控制措施。
为什么我的客户端返回 401 或 403?
直接调用 API 时返回 401 和 authentication_error。 密钥错误、已被撤销或已过期。过期是人们常忽略的原因之一,因为代码未变且请求昨天还能正常工作。请检查控制台中密钥的过期时间列,或从 Admin API 读取 expires_at,对于无过期时间的密钥,该值为 null。个人密钥在所有者离开组织时也会失效。
SDK 忽略了您的联合身份验证设置并使用了密钥。 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 在凭证优先级顺序中高于联合身份验证,因此其中任何一个都会覆盖它。具体表现为:导出为空字符串的变量仍会占用其位置,因此 ANTHROPIC_API_KEY="" 会导致 SDK 使用空密钥进行身份验证,而不是向下回退。请使用 unset ANTHROPIC_API_KEY。
联合身份验证返回 401 和纯文本消息 Authentication failed。 该消息对所有可能的原因均保持一致,以防止调用者通过读取错误文本探测您的规则配置。真正的原因记录在控制台的身份验证历史页面上。请从那里开始排查,不要盲目猜测 JWT 的问题。
Foundry 返回 403。 令牌已通过身份验证,但您的 Azure 账户缺少允许该调用的角色。请为发起请求的身份分配 Azure RBAC 角色,例如 Foundry User(原 Azure AI User)或 Cognitive Services User。
Bedrock 出现任何问题。 对于 SigV4 身份验证,请先以服务用户身份运行 aws sts get-caller-identity。它能确认当前环境是否具备可用的 AWS 凭证,从而区分凭证问题与模型访问问题或区域不匹配问题。截至 2026 年 10 月 29 日,AWS 允许在商业区域首次使用时访问许多模型(需具备必要的 AWS Marketplace 权限),但部分模型需要单独的账户级访问权限。通过 InvokeModel 路由调用的 Anthropic 模型需要每个账户(或整个 AWS 组织,尽管选择加入的区域需要再次申请)先提交一次用例表单,在表单审核通过前,调用将返回 AccessDeniedException。AWS 文档说明该表单不适用于 bedrock-mantle 端点。账户内对模型的首次调用还会触发 Bedrock 在后台启动 AWS Marketplace 订阅,该订阅需要身份持有 aws-marketplace:Subscribe、aws-marketplace:Unsubscribe 和 aws-marketplace:ViewSubscriptions 权限。缺少权限不一定会导致首次调用失败:AWS 文档指出,在订阅设置期间调用可能会成功长达 15 分钟,一旦订阅失败,后续调用将返回相同的 AccessDeniedException。如果服务在运行最初几分钟后开始报错,应排查此项而非凭证。授予权限后,AWS 最多需要 2 分钟完成订阅。如果调用的区域不提供该模型,无论凭证是否正确,调用都会失败。
FAQ
我在 Bedrock 或 Vertex 上使用 Claude 需要 Anthropic API 密钥吗?
不需要。在 Amazon Bedrock 上,SDK 会使用 SigV4 通过 AWS 凭证对请求进行签名,或发送 Bedrock API 密钥;在 Google Cloud 上,SDK 则发送通过 Application Default Credentials 获取的 Google 访问令牌。这两种设置中均不存在 Anthropic 签发的密钥,且使用费用由云账户结算,而非 Anthropic。这也是为什么在这些主机上将 Anthropic 密钥留在 ANTHROPIC_API_KEY 中存在风险:指向云端点的通用客户端会将其发送至该处。
Claude 在 Azure 上可用吗?
可用,通过 Microsoft Foundry(原 Azure AI Foundry)提供。你需要创建一个 Foundry 资源,将 Claude 模型部署到其中,并使用 Azure 签发的密钥(置于 api-key 标头中)或 Microsoft Entra 持有者令牌调用 https://{resource}.services.ai.azure.com/anthropic/v1/messages。使用费用通过 Azure Marketplace 以 Claude 消费单元结算。请求正文中的 model 字段必须包含你的部署名称;仅当你创建部署时保留了默认名称,该名称才与模型标识符一致;部署名称创建后无法更改。
我应该将 Claude API 密钥存储在 Linux 服务器的什么位置?
存储在由 root 用户拥有且权限为 600 的文件中,并通过 systemd 单元中的 EnvironmentFile= 加载。systemd 会在切换到单元的 User= 之前以 root 身份读取该文件,因此服务账户无需访问权限。请勿将其放入代码仓库、单元文件本身(该文件可被所有人读取,且会被 systemctl cat 打印出来),也不要放入容器镜像配置、层或构建元数据中。
为什么我的 Claude API 请求在没有任何变动的情况下开始返回 401?
密钥达到创建时设定的有效期后会返回 401。有效期在创建时设定,事后无法编辑,且短效密钥过期时不会发送警告邮件。过期的密钥无法重新激活,因此请创建一个新密钥,将其写入环境文件,重启服务,随后撤销旧密钥。如果确认密钥仍在有效期内,请检查是否存在过时的凭证覆盖了当前设置:ANTHROPIC_API_KEY 若被设置为空字符串,其优先级仍高于下方的联合身份验证和配置文件来源。