Claude Code 深度学习手册

主题

Claude Code on Claude Platform on AWS ​

用 AWS 凭据/IAM 鉴权、走 AWS Marketplace 计费，让 Claude Code 直连 Anthropic API。

是什么 ​

Claude Platform on AWS 是由 Anthropic 运营的 Claude API，搭配 AWS 鉴权、IAM 访问控制和 AWS Marketplace 计费。请求直达 Anthropic 官方 API，因此你获得与直连 Claude API 完全相同的模型和功能、相同的发布节奏；区别只在于用 AWS 凭据或 workspace API key 鉴权，并通过 AWS Marketplace 付费。

通过 AWS Marketplace 订阅会创建一个与你 AWS 账号绑定的全新 Anthropic 组织，它与你已有的任何 Anthropic 组织相互独立，凭据不互通。必须使用这个 AWS 关联组织里的 workspace ID 和 API key，而不是已有 Claude Console 账号的凭据。

怎么工作 ​

  • 请求由 Claude Code 用 SigV4 签名后直达 Anthropic API；base URL 由 AWS_REGION 计算得出，格式为 https://aws-external-anthropic.{region}.api.aws
  • 鉴权有两种方式：方式 A 用标准 AWS 凭据链（环境变量、~/.aws/credentials、IAM role、AWS SSO 会话等）做 SigV4 签名；方式 B 用长期有效的 workspace API key
  • workspace ID 必填，每次请求都作为 anthropic-workspace-id header 发送；它不会由 AWS 凭据隐式推导
  • 即使环境中已有 AWS 凭据，Claude Platform on AWS 仍是显式 opt-in；provider 路由中 Bedrock 和 Foundry 优先级更高，需取消设置 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_FOUNDRY
  • 模型 ID 与直连 Claude API 完全一致；默认别名 opus/sonnet/haiku 解析为 workspace 中可用的最新版本
  • Agent SDK 读取与 CLI 相同的环境变量，任何 spawn Claude Code 子进程的程序设置好变量即可指向该平台
  • 可通过设置 ANTHROPIC_AWS_BASE_URL 把流量导向企业代理或 LLM gateway

怎么配置 / 用法 ​

鉴权方式 A（AWS 凭据 + SigV4，本地用 SSO 登录）：

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

SSO 凭据中途过期时，可在 settings.json 配置自动刷新：

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

鉴权方式 B（workspace API key，在 AWS Console 的 Claude Platform on AWS → API keys 生成）：

bash
export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx

API key 以 x-api-key 发送，优先级高于 SigV4，设置后环境里的 AWS 凭据被忽略。

路由到该平台（核心配置）：

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

固定模型版本（团队部署建议显式 pin）：

bash
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

企业代理 / LLM gateway 设 ANTHROPIC_AWS_BASE_URL；若 gateway 自行签名，用 CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 跳过 Claude Code 的签名；gateway 需要自己的 token 时设 ANTHROPIC_AUTH_TOKEN。1 小时缓存 TTL：export ENABLE_PROMPT_CACHING_1H=1。

什么时候用 ​

  • 已通过 AWS Marketplace 订阅 Claude Platform on AWS，想让 Claude Code 指向已开通的 workspace
  • 希望用 AWS 凭据/IAM 做访问控制、通过 AWS Marketplace 统一计费，而不是用 Claude.ai 订阅或直连 API key
  • CI / 自动化场景：给 runner 挂一个有权限调用 Anthropic 服务的 IAM role，凭据链自动识别
  • 需要把 Claude Code 流量经企业代理或 LLM gateway 转发

限制 / 坑 ​

  • /login 和 /logout 命令不影响 Claude Platform on AWS 的鉴权（鉴权走 AWS 凭据或 workspace API key）
  • 来自其它独立 Claude Console 组织的 API key 在此无效，凭据不跨组织互通
  • Bedrock 和 Foundry 在 provider 路由中优先级更高；若 CLAUDE_CODE_USE_BEDROCK 或 CLAUDE_CODE_USE_FOUNDRY 已设置，会覆盖本平台
  • AWS CLI 仅在 SSO 登录流程中需要
  • 1 小时缓存写入按更高费率计费

硬事实速查（12 条） ​

  • 核心开关 CLAUDE_CODE_USE_ANTHROPIC_AWS=1，否则请求仍发往 api.anthropic.com
  • ANTHROPIC_AWS_WORKSPACE_ID 必填，每次请求作为 anthropic-workspace-id header 发送
  • base URL 由 AWS_REGION 计算得出：https://aws-external-anthropic.{region}.api.aws，可用 ANTHROPIC_AWS_BASE_URL 直接覆盖
  • workspace API key 设为 ANTHROPIC_AWS_API_KEY，以 x-api-key 发送，优先级高于 SigV4
  • SigV4 走标准 AWS 凭据链：环境变量、~/.aws/credentials、IAM role、AWS SSO 会话等
  • awsAuthRefresh（settings.json）可在 SSO 凭据过期时自动重跑登录命令并重试
  • Prompt caching 默认开启；ENABLE_PROMPT_CACHING_1H=1 可改为 1 小时 TTL（默认 5 分钟）
  • 模型版本可 pin：ANTHROPIC_DEFAULT_OPUS_MODEL / SONNET / HAIKU
  • CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 让 Claude Code 发不带签名的请求，由 gateway 补 SigV4；gateway 自有 token 用 ANTHROPIC_AUTH_TOKEN
  • 用 /status 查看解析出的 provider、workspace ID、region、base URL 覆盖及 auth-skip 设置
  • 403 Forbidden / AccessDenied 通常是 IAM principal 缺少调用权限或 ANTHROPIC_AWS_API_KEY 已失效
  • 订阅会创建与 AWS 账号绑定的全新 Anthropic 组织，与已有组织独立、凭据不互通

官方出处：https://code.claude.com/docs/en/claude-platform-on-aws