Claude Code官方文档AWSBedrock云部署

Claude Code on Amazon Bedrock - AWS 配置与 IAM 完整指南

通过 Amazon Bedrock 配置 Claude Code，包括登录向导、IAM 配置、模型固定、Mantle 端点和故障排除。

发布于 2025年5月1日 · 阅读约 25 分钟

Amazon Bedrock 上的 Claude Code

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

跨组织部署 Claude Code？ 与销售人员讨论企业计划、SSO 和集中式计费。查看计划 | 联系销售

前置条件

在使用 Bedrock 配置 Claude Code 之前，请确保您拥有：

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

要使用您自己的 Bedrock 凭证登录，请按照下面的使用 Bedrock 登录进行操作。要在团队中部署 Claude Code，请使用手动设置步骤并在推出前固定您的模型版本。

使用 Bedrock 登录

如果您拥有 AWS 凭证并想开始通过 Bedrock 使用 Claude Code，登录向导会引导您完成整个过程。您每个账户完成一次 AWS 端的前置条件；向导处理 Claude Code 端。

步骤 1：在您的 AWS 账户中启用 Anthropic 模型

在 Amazon Bedrock 控制台中，打开模型目录，选择一个 Anthropic 模型，并提交用例表单。提交后立即授予访问权限。有关 AWS Organizations，请参阅提交用例详情，有关权限，请参阅 IAM 配置。

步骤 2：启动 Claude Code 并选择 Bedrock

运行 claude。在登录提示处，选择 3rd-party platform，然后选择 Amazon Bedrock。

步骤 3：按照向导提示操作

选择您如何向 AWS 进行身份验证：从您的 ~/.aws 目录检测到的 AWS 配置文件、Bedrock API 密钥、访问密钥和密钥，或已在您的环境中的凭证。向导会获取您的区域，验证您的账户可以调用哪些 Claude 模型，并让您固定它们。它将结果保存到您的用户设置文件的 env 块中，因此您无需自己导出环境变量。

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

手动设置

要通过环境变量而不是向导配置 Bedrock，例如在 CI 或脚本化企业推出中，请按照下面的步骤操作。

1. 提交用例详情

Anthropic 模型的首次用户需要在调用模型之前提交用例详情。这是每个 AWS 账户执行一次的操作。

确保您拥有下面描述的正确 IAM 权限
导航到 Amazon Bedrock 控制台
从模型目录中选择一个 Anthropic 模型
完成用例表单。提交后立即授予访问权限。

如果您使用 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 管理控制台凭证

aws login

了解更多关于 aws login。

选项 E：Bedrock API 密钥

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API 密钥提供了一种更简单的身份验证方法，无需完整的 AWS 凭证。了解更多关于 Bedrock API 密钥。

高级凭证配置

Claude Code 支持 AWS SSO 和企业身份提供商的自动凭证刷新。将这些设置添加到您的 Claude Code 设置文件（请参阅设置了解文件位置）。

当 Claude Code 检测到您的 AWS 凭证已过期（基于本地时间戳或当 Bedrock 返回凭证错误时），它将自动运行您配置的 awsAuthRefresh 和/或 awsCredentialExport 命令来获取新凭证，然后重试请求。

示例配置

{
  "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"
  }
}

3. 配置 Claude Code

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

# 启用 Bedrock 集成
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # 或您首选的区域

# 可选：覆盖小型/快速模型 (Haiku) 的区域。
# 也适用于 Bedrock Mantle。
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 启用 Bedrock 时，请记住以下几点：

AWS_REGION 是必需的环境变量。Claude Code 不会从 .aws 配置文件中读取此设置。
使用 Bedrock 时，/login 和 /logout 命令被禁用，因为身份验证通过 AWS 凭证处理。
您可以使用设置文件来处理环境变量，如 AWS_PROFILE，您不希望泄露给其他进程。请参阅设置了解更多信息。

4. 固定模型版本

⚠️ 警告：在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 sonnet 和 opus）会解析为最新版本，当 Anthropic 发布更新时，您的 Bedrock 账户中可能还没有该版本。Claude Code 在启动时会回退到上一个版本（如果最新版本不可用），但固定让您可以控制用户何时迁移到新模型。

将这些环境变量设置为特定的 Bedrock 模型 ID。

如果没有 ANTHROPIC_DEFAULT_OPUS_MODEL，Bedrock 上的 opus 别名会解析为 Opus 4.6。将其设置为 Opus 4.7 ID 以使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-7'
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. 前缀）。如果您使用不同的区域前缀或应用推理配置文件，请相应调整。有关当前和旧版模型 ID，请参阅模型概览。请参阅模型配置了解完整的环境变量列表。

当未设置固定变量时，Claude Code 使用这些默认模型：

模型类型	默认值
主模型	`us.anthropic.claude-sonnet-4-5-20250929-v1:0`
小型/快速模型	`us.anthropic.claude-haiku-4-5-20251001-v1:0`

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

# 使用推理配置文件 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 caching
export DISABLE_PROMPT_CACHING=1

# 可选：请求 1 小时 prompt cache TTL 而不是 5 分钟默认值
export ENABLE_PROMPT_CACHING_1H=1

ℹ️ Prompt caching 可能在所有区域都不可用。具有 1 小时 TTL 的缓存写入的计费费率高于 5 分钟写入。

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

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 调用 Bedrock。没有覆盖的版本回退到内置的 Bedrock 模型 ID 或启动时发现的任何匹配推理配置文件。请参阅按版本覆盖模型 ID了解覆盖如何与 availableModels 和其他模型设置交互的详情。

启动模型检查

当 Claude Code 启动并配置了 Bedrock 时，它会验证它打算使用的模型在您的账户中是否可访问。此检查需要 Claude Code v2.1.94 或更高版本。

如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的账户可以调用较新版本，Claude Code 会提示您更新固定。接受会将新模型 ID 写入您的用户设置文件并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。指向应用推理配置文件 ARN 的固定会被跳过，因为这些由您的管理员管理。

如果您没有固定模型，并且当前默认值在您的账户中不可用，Claude Code 会在当前会话中回退到上一个版本并显示通知。回退不会被持久化。在您的 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"
        }
      }
    }
  ]
}

为了获得更严格的权限，您可以将资源限制为特定的推理配置文件 ARN。

bedrock:GetInferenceProfile 让 Claude Code 能够将应用推理配置文件 ARN 解析为其支持的基础模型，该模型用于为该模型选择正确的请求形状。

如果令牌缺少此权限，Claude Code 会通过使用备用形状重试一次来自动恢复，因此请求仍然会成功，但每个新模型都会增加一个额外的往返。授予该权限可以避免重试。这最常适用于 AWS_BEARER_TOKEN_BEDROCK 部署，其中令牌的策略通常比完整的 IAM 角色更窄。

有关详情，请参阅 Bedrock IAM 文档。

ℹ️ 为 Claude Code 创建一个专用的 AWS 账户，以简化成本跟踪和访问控制。

1M 令牌上下文窗口

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Amazon Bedrock 上支持 1M 令牌上下文窗口。当您选择 1M 模型变体时，Claude Code 会自动启用扩展上下文窗口。

设置向导在固定模型时提供 1M 上下文选项。要为手动固定的模型启用它，请在模型 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 上启用跨区域推理。

示例配置：

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

使用 Mantle 端点

Mantle 是一个 Amazon Bedrock 端点，通过原生 Anthropic API 形状而不是 Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 凭证、IAM 权限和本页面前面描述的 awsAuthRefresh 配置。

ℹ️ Mantle 需要 Claude Code v2.1.94 或更高版本。运行 claude --version 来检查。

启用 Mantle

配置了 AWS 凭证后，设置 CLAUDE_CODE_USE_MANTLE 以将请求路由到 Mantle 端点：

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

Claude Code 从 AWS_REGION 构造端点 URL。要为自定义端点或网关覆盖它，请设置 ANTHROPIC_BEDROCK_MANTLE_BASE_URL。

在 Claude Code 内运行 /status 来确认。当 Mantle 处于活动状态时，提供者行显示 Amazon Bedrock (Mantle)。

选择 Mantle 模型

Mantle 使用以 anthropic. 为前缀且没有版本后缀的模型 ID，例如 anthropic.claude-haiku-4-5。您的账户可用的模型取决于您的组织被授予的内容；其他模型 ID 列在您来自 AWS 的入职材料中。联系您的 AWS 账户团队以请求访问允许列表中的模型。

使用 --model 标志或在 Claude Code 内使用 /model 设置模型：

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

在 Invoke API 旁边运行 Mantle

您在 Mantle 上可用的模型可能不包括您今天使用的每个模型。设置 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_MANTLE 让 Claude Code 从同一会话调用两个端点。与 Mantle 格式匹配的模型 ID 被路由到 Mantle，所有其他模型 ID 转到 Bedrock Invoke API。

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

要在 /model 选择器中显示 Mantle 模型，请在您的设置文件中的 availableModels 中列出其 ID。此设置也将选择器限制为列出的条目，因此包括您想保持可用的每个别名：

{
  "availableModels": ["opus", "sonnet", "haiku", "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 端点。请参阅环境变量了解完整列表。

变量	目的
`CLAUDE_CODE_USE_MANTLE`	启用 Mantle 端点。设置为 `1` 或 `true`。
`ANTHROPIC_BEDROCK_MANTLE_BASE_URL`	覆盖默认 Mantle 端点 URL
`CLAUDE_CODE_SKIP_MANTLE_AUTH`	跳过客户端身份验证以用于代理设置
`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`	覆盖 Haiku 类模型的 AWS 区域（与 Bedrock 共享）

故障排除

使用 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
考虑使用推理配置文件进行跨区域访问

如果您收到错误”不支持按需吞吐量”：

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

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

Mantle 端点错误

如果在设置 CLAUDE_CODE_USE_MANTLE 后 /status 没有显示 Amazon Bedrock (Mantle)，则该变量没有到达进程。确认它在您启动 claude 的 shell 中被导出，或在您的设置文件的 env 块中设置它。

来自 Mantle 端点的 403（具有有效凭证）意味着您的 AWS 账户没有被授予访问您请求的模型的权限。联系您的 AWS 账户团队以请求访问。

命名模型 ID 的 400 意味着该模型不在 Mantle 上提供。Mantle 有其自己的模型阵容，与标准 Bedrock 目录分开，因此推理配置文件 ID（如 us.anthropic.claude-sonnet-4-6）将不起作用。使用 Mantle 格式的 ID，或启用两个端点，以便 Claude Code 将每个请求路由到模型可用的端点。

其他资源

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。