在 Amazon Bedrock 上使用 Claude Code

了解如何通过 Amazon Bedrock 配置 Claude Code，包括初始设置、IAM 配置和故障排除。

前提条件

使用 Amazon Bedrock 配置 Claude Code 前，请确保具备：

• 已启用 Amazon Bedrock 访问权限的 AWS 账号
• 在 Amazon Bedrock 中访问所需 Claude 模型（例如 Claude Sonnet 4.6）的权限
• 已安装并配置 AWS CLI（可选，仅当没有其他凭据获取机制时才需要）
• 适当的 IAM 权限

要使用您自己的 Amazon Bedrock 凭据登录，请按下文的使用 Amazon Bedrock 登录操作。要在团队中部署 Claude Code，请完成手动设置步骤并固定模型版本，然后再推广部署。

使用 Bedrock 登录

如果您已有 AWS 凭据，并希望开始通过 Amazon Bedrock 使用 Claude Code，登录向导会引导您完成设置。每个账号只需完成一次 AWS 端的前提条件，其余 Claude Code 端的配置由向导处理。

登录后，可随时运行 /setup-bedrock 重新打开向导，更改凭据、区域或固定的模型版本。

手动设置

如果要通过环境变量而非向导配置 Amazon Bedrock，例如用于 CI 或脚本化的企业推广部署，请按以下步骤操作。

1. 提交使用场景详细信息

首次使用 Anthropic 模型的用户必须先提交使用场景详细信息，之后才能调用模型。每个 AWS 账号只需提交一次。

1. 确保拥有下文所述的正确 IAM 权限
2. 前往 Amazon Bedrock 控制台
3. 从 Model catalog 中选择一个 Anthropic 模型
4. 填写使用场景表单。提交后会立即获得访问权限。

如果使用 AWS Organizations，可以通过管理账号调用一次 PutUseCaseForModelAccess API 提交表单。此调用需要 bedrock:PutUseCaseForModelAccess IAM 权限。批准会自动扩展到子账号。

2. 配置 AWS 凭据

Claude Code 使用 AWS SDK 默认凭据链。请通过以下任一方式配置凭据：

选项 A：AWS CLI 配置

aws configure

选项 B：环境变量（访问密钥）

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

选项 C：环境变量（SSO 配置文件）

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

选项 D：AWS Management Console 凭据

aws login

参阅 aws login 的详细说明。

选项 E：Amazon Bedrock API 密钥

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Amazon Bedrock API 密钥提供了一种更简单的身份验证方式，无需完整的 AWS 凭据。请参阅 Amazon Bedrock API 密钥的详细说明。

高级凭据配置

Claude Code 支持自动刷新 AWS SSO 和企业身份提供商的凭据。将以下设置添加到 Claude Code 设置文件中（文件位置请参阅设置）。

这两项设置的触发条件不同：

• awsAuthRefresh：仅当 Claude Code 检测到 AWS 凭据已过期时运行。检测方式可以是根据本地时间戳判断，也可以是 API 返回凭据错误；刷新凭据后，Claude Code 会重试请求。
• awsCredentialExport：在会话开始以及每次重新加载凭据时运行，即使 AWS 默认凭据提供程序链中的凭据仍然有效也会运行。如果 Amazon Bedrock 账号需要与默认提供程序链解析结果不同的跨账号凭据，请使用此设置。

配置示例

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

配置项说明

awsAuthRefresh：适用于会修改 .aws 目录的命令，例如更新凭据、SSO 缓存或配置文件。命令输出会显示给用户，但不支持交互式输入。它非常适合基于浏览器的 SSO 流程：CLI 显示 URL 或代码，您在浏览器中完成身份验证。

awsCredentialExport：仅当无法修改 .aws、必须直接返回凭据时使用。每当需要刷新凭据时都会运行此命令，而不只是在凭据过期时。命令输出会被静默捕获，不会向用户显示。该命令必须输出以下格式的 JSON：

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value",
    "Expiration": "2026-01-01T00:00:00Z"
  }
}

从 Claude Code v2.1.181 开始，也可以使用 aws configure export-credentials --format process 输出的扁平结构，其中相同的键直接位于顶层，而不是嵌套在 Credentials 下。

Expiration 是可选项。从 Claude Code v2.1.176 开始，如果命令返回有效的 ISO 8601 Expiration，Claude Code 会缓存凭据，直到到期前五分钟。若不提供该值，或使用更早的版本，凭据会缓存一小时。

3. 配置 Claude Code

设置以下环境变量以启用 Amazon Bedrock：

# 启用 Bedrock 集成
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # 如果您的 AWS 配置文件已设置区域，则可省略

# 可选：覆盖小型/快速模型（Bedrock 和 Mantle）使用的 AWS 区域。
# 在 Bedrock 上，如果未设置 ANTHROPIC_DEFAULT_HAIKU_MODEL
# 或已弃用的 ANTHROPIC_SMALL_FAST_MODEL，此设置不会生效。
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# 可选：覆盖 Bedrock 端点 URL，以使用自定义端点或网关
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

为 Claude Code 启用 Amazon Bedrock 时，请注意以下事项：

• 从 v2.1.172 开始，仅在要覆盖 AWS 配置文件中的区域，或配置文件未设置区域时，才需要设置 AWS_REGION。Claude Code 按以下顺序解析区域：

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • 当前 AWS 配置文件中设置的 region；按照 AWS SDK 的优先级，先从 AWS 共享凭据文件读取，再从共享配置文件读取
  • us-east-1

  如果设置了 AWS_PROFILE，它就是当前配置文件；否则当前配置文件为 default。可设置 AWS_SHARED_CREDENTIALS_FILE 或 AWS_CONFIG_FILE，使其指向非默认文件路径。运行 /status 可查看解析后的区域。如果区域来自 AWS 配置文件或默认回退值，/status 还会注明来源。在 v2.1.171 及更早版本中，Claude Code 不读取 AWS 配置文件，因此需要显式设置 AWS_REGION。

• 使用 Amazon Bedrock 时，身份验证由 AWS 凭据处理，因此 /logout 命令不可用。

• Amazon Bedrock 不提供 WebSearch 工具。请参阅 WebSearch 工具行为。

• 对于 AWS_PROFILE 等不希望泄露给其他进程的环境变量，可以使用设置文件。有关详细信息，请参阅设置。

4. 固定模型版本

将以下环境变量设为具体的 Amazon Bedrock 模型 ID。

如果未设置 ANTHROPIC_DEFAULT_OPUS_MODEL，Amazon Bedrock 上的 opus 别名会解析为 Opus 4.6。将其设为 Opus 4.8 ID 即可使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

这些变量使用跨区域推理配置文件 ID（带 us. 前缀）。如果使用其他区域前缀或应用程序推理配置文件，请相应调整。在 AWS GovCloud 区域中，请使用 us-gov. 前缀。有关当前和旧版模型 ID，请参阅模型概览。有关环境变量的完整列表，请参阅模型配置。

未设置模型固定变量时，Claude Code 使用以下默认模型：

会话标题生成等后台任务使用小型/快速模型，通常是 Haiku 级别的模型。在 Amazon Bedrock 上，Claude Code 默认对这些任务使用主模型，因为并非每个账号或区域都启用了 Haiku。要让后台任务使用 Haiku，请将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设为您账号中可用的模型 ID。

要进一步自定义模型，可以使用以下任一方法：

# 使用推理配置文件 ID
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# 使用应用程序推理配置文件 ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# 可选：按需禁用 Prompt 缓存
export DISABLE_PROMPT_CACHING=1

# 可选：请求使用 1 小时的 Prompt 缓存 TTL，而非默认的 5 分钟
export ENABLE_PROMPT_CACHING_1H=1

一小时缓存 TTL 的计费标准高于默认的五分钟缓存。请参阅缓存生命周期。

将各模型版本映射到推理配置文件

ANTHROPIC_DEFAULT_*_MODEL 环境变量为每个模型系列配置一个推理配置文件。如果组织需要在 /model 选择器中提供同一系列的多个版本，并将各版本分别路由到自己的应用程序推理配置文件 ARN，请改用设置文件中的 modelOverrides 设置。

以下示例将四个 Opus 版本映射到不同的 ARN，使用户无需绕过组织的推理配置文件即可在版本之间切换：

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"
  }
}

用户在 /model 中选择其中一个版本时，Claude Code 会使用映射后的 ARN 调用 Amazon Bedrock。通过 --model 或 ANTHROPIC_MODEL 直接传入 Anthropic 模型 ID 时，同一映射也会生效。没有覆盖项的版本会回退到内置 Amazon Bedrock 模型 ID，或启动时发现的任何匹配推理配置文件。v2.1.200 之前，--model 和 ANTHROPIC_MODEL 的值不会经过覆盖映射，而是原样传递到 Amazon Bedrock。有关覆盖项如何与 availableModels 及其他模型设置配合使用，请参阅按版本覆盖模型 ID。

启动时的模型检查

当 Claude Code 在已配置 Amazon Bedrock 的情况下启动时，会验证要使用的模型能否通过您的账号访问。此检查要求 Claude Code v2.1.94 或更高版本。

如果固定的模型版本早于当前 Claude Code 默认版本，且账号可以调用较新的版本，Claude Code 会提示您更新固定版本。接受后，新的模型 ID 会写入用户设置文件，随后 Claude Code 会重启。选择拒绝后，在下次默认版本变更前不会再次提示。指向应用程序推理配置文件 ARN 的固定项会被跳过，因为这些项由管理员管理。

如果没有固定模型，而当前默认模型在账号中不可用，Claude Code 会在当前会话中回退到上一版本并显示通知。此回退不会持久保存。请在 Amazon Bedrock 账号中启用较新的模型，或固定版本，以永久使用所选版本。

IAM 配置

创建包含 Claude Code 所需权限的 IAM 策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
  ]
}

如需更严格的权限，可以将 Resource 限制为特定的推理配置文件 ARN。

bedrock:GetInferenceProfile 允许 Claude Code 将应用程序推理配置文件 ARN 解析为其底层基础模型，以便为该模型选择正确的请求结构。

如果 Token 缺少此权限，Claude Code 会自动改用另一种请求结构重试一次，因此请求仍可成功，但每使用一个新模型都会增加一次额外的网络往返。授予此权限可避免重试。这最常见于 AWS_BEARER_TOKEN_BEDROCK 部署，因为 Token 的策略通常比完整 IAM 角色更严格。

有关详细信息，请参阅 Amazon Bedrock IAM 文档。

100 万 Token 上下文窗口

Claude Sonnet 5、Opus 4.6 及更高版本和 Sonnet 4.6 在 Amazon Bedrock 上支持 100 万 Token 上下文窗口。Sonnet 5 通过 Mantle 端点提供，并始终使用 100 万 Token 窗口，无需选择 [1m] 变体。对于其他模型，当您选择 100 万 Token 模型变体时，Claude Code 会自动启用扩展上下文窗口。

设置向导在固定模型时会提供 100 万 Token 上下文选项。如果要为手动固定的模型启用该窗口，请在模型 ID 后附加 [1m]。有关详细信息，请参阅为第三方部署固定模型。

服务层级

Amazon Bedrock 服务层级允许您在成本和延迟之间进行权衡。将 ANTHROPIC_BEDROCK_SERVICE_TIER 设为 default、flex 或 priority：

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code 会在每个请求中以 X-Amzn-Bedrock-Service-Tier 标头发送此设置。层级的可用性因模型和区域而异。预留容量不使用此设置，而是将预置吞吐量 ARN 用作模型 ID。

AWS Guardrails

Amazon Bedrock Guardrails可用于为 Claude Code 实施内容过滤。请在 Amazon Bedrock 控制台中创建 Guardrail 并发布一个版本，然后将 Guardrail 标头添加到设置文件。如果使用跨区域推理配置文件，请为 Guardrail 启用 Cross-Region inference。

配置示例：

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

使用 Mantle 端点

Mantle 是 Amazon Bedrock 的一个端点，它以原生 Anthropic API 格式提供 Claude 模型，而不是使用 Amazon Bedrock Invoke API。它使用本页前文所述的同一套 AWS 凭据、IAM 权限和 awsAuthRefresh 配置。

启用 Mantle

配置好 AWS 凭据后，将 CLAUDE_CODE_USE_MANTLE 设为把请求路由到 Mantle 端点：

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code 根据 AWS 区域构造端点 URL。从 v2.1.172 开始，区域解析采用与上文 Amazon Bedrock相同的优先级；更早的版本仅使用 AWS_REGION。要为自定义端点或网关覆盖 URL，请设置 ANTHROPIC_BEDROCK_MANTLE_BASE_URL。

在 Claude Code 中运行 /status 进行确认。启用 Mantle 后，提供商一行会显示 Amazon Bedrock (Mantle)。

选择 Mantle 模型

Mantle 使用以 anthropic. 为前缀且不带版本后缀的模型 ID，例如 anthropic.claude-sonnet-5 或 anthropic.claude-haiku-4-5。账号可用的模型取决于组织获得的授权；AWS 提供的引导上手材料中列出了其他模型 ID。请联系您的 AWS 客户团队，申请访问允许列表中的模型。

使用 --model 标志或 Claude Code 中的 /model 设置模型：

claude --model anthropic.claude-haiku-4-5

同时运行 Mantle 与 Invoke API

Mantle 上可用的模型可能不包含您目前使用的每个模型。同时设置 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_MANTLE 后，Claude Code 可以在同一会话中调用两个端点。符合 Mantle 格式的模型 ID 会路由到 Mantle，其他所有模型 ID 则路由到 Amazon Bedrock Invoke API。

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

要在 /model 选择器中显示 Mantle 模型，请将其 ID 列入设置文件的 availableModels。此设置还会将选择器限制为所列条目。列出 anthropic.claude-haiku-4-5 后，选择器中的裸 haiku 别名会被移除，因此还应列出希望继续可选的版本前缀或完整 ID。Mantle ID 与 haiku 别名解析到同一模型系列，因此合并后只保留更具体的条目。请参阅合并行为：

{
  "availableModels": ["opus", "sonnet", "claude-haiku-4-5", "anthropic.claude-haiku-4-5"]
}

带 anthropic. 前缀的条目会作为自定义选择项加入选择器，并路由到 Mantle。请将 anthropic.claude-haiku-4-5 替换为账号获准使用的模型 ID。有关 availableModels 如何与其他模型设置交互，请参阅限制模型选择。

同时启用两个提供商后，/status 会显示 Amazon Bedrock + Amazon Bedrock (Mantle)。

通过网关路由 Mantle

如果组织通过集中式 LLM 网关路由模型流量，并由网关在服务器端注入 AWS 凭据，请禁用客户端身份验证，使 Claude Code 发送的请求不包含 SigV4 签名或 x-api-key 标头：

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

Mantle 环境变量

以下变量专用于 Mantle 端点。完整列表请参阅环境变量。

故障排除

使用 SSO 和企业代理时反复进入身份验证

如果使用 AWS SSO 时浏览器标签页不断打开，请从设置文件中移除 awsAuthRefresh 设置。企业 VPN 或 TLS 检查代理中断 SSO 浏览器流程时，可能会出现此问题。Claude Code 会将中断的连接视为身份验证失败，再次运行 awsAuthRefresh，从而陷入无限循环。

如果网络环境会干扰基于浏览器的自动 SSO 流程，请在启动 Claude Code 前手动运行 aws sso login，而不要依赖 awsAuthRefresh。

区域问题

如果遇到区域问题：

• 检查模型可用性：aws bedrock list-inference-profiles --region your-region
• 切换到支持的区域：export AWS_REGION=us-east-1
• 考虑使用推理配置文件实现跨区域访问

如果收到“on-demand throughput isn't supported”错误：

• 将模型指定为推理配置文件 ID

Claude Code 使用 Amazon Bedrock Invoke API，不支持 Converse API。

/context 中的 Token 计数为零

/context 命令会将各工具组的工具 schema 发送到 Amazon Bedrock Token 计数 API，以统计其 Token 数。在 v2.1.196 之前的 Claude Code 版本中，Amazon Bedrock 会拒绝该请求，因为这些 schema 包含其 Token 计数 API 不接受的字段，所以每个工具组都显示 0 Token。明细中的其他行（例如消息和内存文件）不受影响。

请升级到 v2.1.196 或更高版本。

Mantle 端点错误

如果 /status 未显示 Amazon Bedrock (Mantle)，而您已经设置了 CLAUDE_CODE_USE_MANTLE，说明该变量没有传入进程。请确认变量已在启动 claude 的 shell 中导出，或在设置文件的 env 块中设置该变量。

凭据有效时，Mantle 端点返回 403 表示您的 AWS 账号尚未获得所请求模型的访问权限。请联系 AWS 客户团队申请访问权限。

错误中带有模型 ID 的 400 表示 Mantle 不提供该模型。Mantle 拥有独立于标准 Amazon Bedrock 目录的模型阵容，因此 us.anthropic.claude-sonnet-4-6 等推理配置文件 ID 无法使用。请改用 Mantle 格式的 ID，或同时启用两个端点，让 Claude Code 将每个请求路由到提供相应模型的端点。

其他资源

• Amazon Bedrock 文档
• Amazon Bedrock 定价
• Amazon Bedrock 推理配置文件
• Amazon Bedrock Token 消耗和配额
• Claude Code on Amazon Bedrock：快速设置指南
• Claude Code 监控实现 (Amazon Bedrock)