文档索引

在以下地址获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

Claude Code 在 Amazon Bedrock 上

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

前提条件

在通过 Bedrock 配置 Claude Code 之前，请确保您具备以下条件：

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

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

使用 Bedrock 登录

如果您拥有 AWS 凭证并希望通过 Bedrock 开始使用 Claude Code，登录向导将引导您完成设置。您需要为每个 AWS 账户完成一次 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 账户只需执行一次。

1. 确保您拥有下述的正确 IAM 权限
2. 导航到 Amazon Bedrock 控制台
3. 从模型目录中选择一个 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 管理控制台凭证

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 设置文件中（有关文件位置，请参阅设置）。

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

• awsAuthRefresh：仅在 Claude Code 检测到您的 AWS 凭证已过期时运行（基于本地时间戳或 Bedrock 返回凭证错误），然后使用刷新后的凭证重试请求。
• awsCredentialExport：在会话开始时和每次凭证重新加载时运行，即使 AWS 默认凭证提供者链中的凭证仍然有效。当您的 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"
  }
}

3. 配置 Claude Code

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

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

# 可选：覆盖小型/快速模型的 AWS 区域（Bedrock 和 Mantle）。
# 在 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 启用 Bedrock 时，请注意以下事项：

• AWS_REGION 是必需的环境变量。Claude Code 不会从 .aws 配置文件中读取此设置。
• 使用 Bedrock 时，/logout 命令不可用，因为认证通过 AWS 凭证处理。
• 您可以使用设置文件来存储不想泄露给其他进程的环境变量，如 AWS_PROFILE。有关更多信息，请参阅设置。

4. 固定模型版本

将以下环境变量设置为特定的 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 使用以下默认模型：

会话标题生成等后台任务使用小型/快速模型，通常是 Haiku 级模型。在 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'

# 可选：根据需要禁用提示缓存
export DISABLE_PROMPT_CACHING=1

# 可选：请求 1 小时提示缓存 TTL 代替 5 分钟默认值
export ENABLE_PROMPT_CACHING_1H=1

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

启动时模型检查

当 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"
        }
      }
    }
  ]
}

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

bedrock:GetInferenceProfile 允许 Claude Code 将应用程序推理配置文件 ARN 解析为其支持的基础模型，用于为该模型选择正确的请求格式。

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

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

100 万令牌上下文窗口

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

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

在已配置 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

同时运行 Mantle 和 Invoke API

您在 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

如果您的组织通过在服务器端注入 AWS 凭证的集中式 LLM 网关路由模型流量，请禁用客户端认证，以便 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 使用 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 将每个请求路由到模型可用的端点。

其他资源

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