Claude Platform on AWS

前提

• 通过 AWS Marketplace 的有效 Claude Platform on AWS 订阅
• 你与 AWS 关联的 Anthropic 组织里的一个工作区，以及它的工作区 ID
• 有权调用 Anthropic 服务的 IAM 主体，或限定到该工作区的 API Key
• 想用 SigV4 认证时，环境里、~/.aws/credentials 里或附加的 IAM 角色提供的 AWS 凭据（AWS CLI 只在 SSO 登录流程需要）

设置

1. 配置 AWS 凭据

Claude Code 支持两种认证方式。

选项 A：AWS 凭据 + SigV4：Claude Code 用标准 AWS 凭据链（环境变量、~/.aws/credentials、IAM 角色、AWS SSO 会话等 AWS SDK 支持的来源）对请求做 SigV4 签名。本地使用时先用 AWS CLI 登录：

aws sso login --profile my-profile
export AWS_PROFILE=my-profile

CI 和自动化里给运行器一个有权调用 Anthropic 服务的 IAM 角色并设置 AWS_REGION，凭据链会自动拾取。SSO 凭据在会话中途过期时，配置 awsAuthRefresh，让 Claude Code 重新运行你的登录命令并重试而不是失败（在 Claude Platform on AWS 上的自动刷新需要 v2.1.198 或更高版本）：

{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}

Claude Code 在无法验证现有 AWS 凭据时启动也会运行该命令，并在 Authentication 面板里显示命令输出直到登录完成。配置了 awsAuthRefresh 后，运行 /login，选 3rd-party platform，再选 Claude Platform on AWS · refresh credentials，Claude Code 运行配置的命令并重新读取 AWS 凭据而无需重启。

选项 B：工作区 API Key：工作区 API Key 是长期有效的密钥，适合不想管理联合 AWS 凭据时。在 AWS 控制台的 Claude Platform on AWS → API keys 里生成，并设为 ANTHROPIC_AWS_API_KEY：

export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx

Key 作为 x-api-key 发送，优先于 SigV4，所以环境里的任何 AWS 凭据都被忽略；来自独立 Claude Console 组织的 API Key 在这里无效。像对待其他生产凭据那样对待它，用户设置文件的 env 块是把 Key 限定在你机器上、而不全局导出的方便办法。/login 和 /logout 不会让你登录 claude.ai 订阅，认证走你的 AWS 凭据或工作区 API Key。

2. 配置 Claude Code

设置环境变量，让 Claude Code 经 Claude Platform on AWS 而不是默认的 Anthropic API 路由：

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1

ANTHROPIC_AWS_WORKSPACE_ID 必填，Claude Code 在每个请求上把它作为 anthropic-workspace-id 头发送，把示例值换成你自己的工作区 ID。Claude Code 根据 AWS 区域计算基础 URL https://aws-external-anthropic.{region}.api.aws（区域的解析优先级与 Amazon Bedrock 相同），要直接覆盖 URL 设置 ANTHROPIC_AWS_BASE_URL。即使环境里有 AWS 凭据，Claude Platform on AWS 也是需要主动选择的；提供商路由里 Amazon Bedrock 和 Microsoft Foundry 优先，所以如果设置了 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_FOUNDRY 要取消设置。

3. 固定模型版本

Claude Platform on AWS 使用与直连 Claude API 相同的模型 ID。默认别名（fable、opus、sonnet、haiku）解析为 Claude Code 内置的默认值，可能落后于最新发布。给团队部署时显式固定模型 ID，避免新版本让所有人同时迁移：

export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

（示例里的模型 ID 取自官方页面，具体可用模型以官方模型总览为准。）提示缓存自动启用；要请求 1 小时缓存 TTL 而不是默认的 5 分钟，设置 ENABLE_PROMPT_CACHING_1H=1，API 对 1 小时缓存写入按更高费率计费。

4. 启动并验证

运行 claude，提供商生效时启动横幅显示 Claude Platform on AWS。运行 /status 检查细节：API provider 一行为 Claude Platform on AWS，并包含你的 Workspace ID、AWS region，设置了覆盖时还有 Claude Platform on AWS base URL。

用 Agent SDK

Agent SDK 读取与 CLI 相同的环境变量，所以任何派生 Claude Code 子进程的程序，只要在调用前导出 CLAUDE_CODE_USE_ANTHROPIC_AWS、ANTHROPIC_AWS_WORKSPACE_ID 以及 ANTHROPIC_AWS_API_KEY 或 AWS 凭据，就能以 Claude Platform on AWS 为目标：

import { query } from "@anthropic-ai/claude-agent-sdk";

process.env.CLAUDE_CODE_USE_ANTHROPIC_AWS = "1";
process.env.ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN";
process.env.AWS_REGION = "us-east-1";

for await (const msg of query({ prompt: "What's in this repo?" })) {
  console.log(msg);
}

经企业代理路由

要经代理或 LLM 网关路由，把 ANTHROPIC_AWS_BASE_URL 设为代理地址，Claude Code 用相同的工作区和认证头向该 URL 发请求，所以任何原样转发它们的网关都行。如果网关自己签名请求，设置 CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1，让 Claude Code 发送未签名的请求，由网关在转发到 AWS 前加 SigV4 头；网关需要自己的令牌时，设在 ANTHROPIC_AUTH_TOKEN。

排障

先运行 /status 查看解析出的提供商以及显式配置的工作区 ID、区域、基础 URL 覆盖和跳过认证设置。

• 每个请求都 403 Forbidden 或 AccessDenied：Claude Code 解析出的 IAM 主体可能缺少在你工作区调用 Anthropic 服务的权限，检查附加到 AWS profile 或启动 Claude Code 的运行器上的角色，确认有 IAM 操作参考里记录的 aws-external-anthropic 操作。设置了 ANTHROPIC_AWS_API_KEY 时 Key 优先于 SigV4，过期的 Key 会产生同样的错误：在控制台重新生成，或取消设置该变量回退到 AWS 凭据
• 请求因缺少工作区而失败：ANTHROPIC_AWS_WORKSPACE_ID 可能没设置或为空；每个请求都必须包含工作区 ID，它不会由你的 AWS 凭据隐含
• 请求仍然发往 api.anthropic.com：CLAUDE_CODE_USE_ANTHROPIC_AWS 可能没设置或值不被解析为真，设为 1 并用 /status 确认；如果同时设置了 CLAUDE_CODE_USE_BEDROCK 或 CLAUDE_CODE_USE_FOUNDRY，它们优先