Claude Code on Amazon Bedrock：配置指南、IAM 权限与 Mantle 端点

在 Amazon Bedrock 上运行 Claude Code，可以用 /setup-bedrock 登录向导快速完成，也可以通过环境变量手动配置（适合 CI 和企业批量部署）。先要在 AWS 侧提交模型使用场景并配置好凭据，然后设置 CLAUDE_CODE_USE_BEDROCK=1 和 AWS_REGION。部署给多人使用时，务必通过 ANTHROPIC_DEFAULT_*_MODEL 环境变量固定模型版本，避免新版本上线导致调用失败。Mantle 端点是 Bedrock 的另一个入口，模型 ID 格式为 anthropic.claude-*，需要 Claude Code v2.1.94 或更高版本。运行 claude --version 确认版本。

向整个组织部署 Claude Code？联系销售团队了解企业计划、SSO 和集中计费。查看计划或联系销售。

前提条件

开始前确保：

一个已启用 Bedrock 访问权限的 AWS 账户
已在 Bedrock 中启用所需 Claude 模型（如 Claude Sonnet 4.6）的访问权限
已安装并配置 AWS CLI（可选，如果你有其它方式获取凭据则不需要）
适当的 IAM 权限

如果想用自己的 Bedrock 凭据登录，跳到用 Bedrock 登录。如果要在团队中部署，用手动设置的步骤并在发布前固定模型版本。

用 Bedrock 登录

如果你已有 AWS 凭据，登录向导会引导你完成整个配置。AWS 侧的前提条件每个账户只需完成一次；向导负责处理 Claude Code 侧配置。

在 Amazon Bedrock 控制台中，打开 Model catalog，选择一个 Anthropic 模型，然后提交使用场景表单。提交后立即获得访问权限。对于 AWS Organizations 账户，见提交使用场景说明；IAM 权限需求见 IAM 配置。
运行 claude。在登录提示中选择 3rd-party platform，然后选择 Amazon Bedrock。
选择认证方式：使用 ~/.aws 目录中检测到的 AWS 配置、Bedrock API key、访问密钥（access key + secret），或者环境中已有的凭据。向导会自动检测区域，验证你的账户可以调用哪些 Claude 模型，并允许你固定它们。结果保存在用户设置文件的 env 块中，无需手动导出环境变量。

登录后，随时运行 /setup-bedrock 重新打开向导，修改凭据、区域或模型固定设置。

手动设置

通过环境变量配置 Bedrock，适合 CI 环境或脚本化企业部署。按以下步骤操作。

1. 提交使用场景说明

首次使用 Anthropic 模型的用户必须先提交使用场景说明。每个 AWS 账户只需做一次。

确保你有下面描述的正确 IAM 权限
进入 Amazon Bedrock 控制台
在 Model catalog 中选择一个 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 Management Console 凭据

aws login

关于 aws login 的更多信息，参考 AWS 文档。

选项 E：Bedrock API Keys

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API keys 提供更简单的认证方式，无需完整的 AWS 凭据。更多信息参考 AWS 博客。

高级凭据配置（自动刷新）

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  # 或你偏好的区域

# 可选：覆盖小型/快速模型（Haiku）的 AWS 区域（Bedrock 和 Mantle 都适用）
# 不设置 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

启用 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 参见 Models overview。完整的环境变量列表参见模型配置。

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

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

后台任务（如会话标题生成）使用小型/快速模型，通常是 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 分钟。详情参见缓存生命周期。

提示缓存并非在所有 Bedrock 区域都可用。如果缓存 token 计数始终为零，请查看 Bedrock 文档中支持的模型、区域和限制。

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

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 v2.1.94 或更高版本在启动且配置了 Bedrock 时，会验证它打算使用的模型是否在你的账户中可访问。

如果你固定了一个比当前 Claude Code 默认版本更旧的模型版本，并且你的账户可以调用新版本，Claude Code 会提示你更新固定。接受后会写入新模型 ID 到用户设置文件并重启。拒绝会被记住，直到下一次默认版本变更。指向应用推理配置文件 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 解析为其背后的基础模型，用于为该模型选择正确的请求格式。

如果 token 缺少此权限，Claude Code 会自动恢复——用备用格式重试一次，请求仍然成功，但每个新模型会多一次往返。授予此权限可以避免重试。这种情况最常见于 AWS_BEARER_TOKEN_BEDROCK 部署，因为这类 token 的策略通常比完整 IAM 角色更窄。

详情参见 Bedrock IAM 文档。

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

1M token 上下文窗口

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 支持 Amazon Bedrock 上的 1M token 上下文窗口。选择 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 头部发送。层级的可用性因模型和区域而异。预留容量（Reserved capacity）使用预置吞吐量 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 形状（而非 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 确认。如果 provider 行显示 Amazon Bedrock (Mantle)，表示 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

要让 Mantle 模型出现在 /model 选择器中，在设置文件的 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
考虑使用推理配置文件实现跨区域访问

如果收到 “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 块中设置。

403 错误且凭据有效，意味着你的 AWS 账户未被授予访问所请求模型的权限。联系你的 AWS 账户团队申请访问。

400 错误并包含模型 ID，意味着该模型不在 Mantle 上提供。Mantle 有自己的模型列表，与标准 Bedrock 目录不同，因此推理配置文件 ID（例如 us.anthropic.claude-sonnet-4-6）不适用。请使用 Mantle 格式的 ID，或同时启用两个端点，让 Claude Code 将每个请求路由到模型可用的端点。

常见问题

Claude Code on Bedrock 需要哪些最低 IAM 权限？

至少需要 bedrock:InvokeModel、bedrock:InvokeModelWithResponseStream、bedrock:ListInferenceProfiles 和 bedrock:GetInferenceProfile，Resource 指向 inference-profile/*、application-inference-profile/* 和 foundation-model/*。如果使用 AWS_BEARER_TOKEN_BEDROCK 部署，缺少 GetInferenceProfile 不会直接失败，但每个新模型会增加一次额外重试。

部署给多人使用时为什么必须固定模型版本？

如果不固定模型版本，模型别名（sonnet、opus、haiku）会解析到最新版本。Anthropic 发布新模型时，你或你的用户的 Bedrock 账户中可能尚未启用该版本，导致 Claude Code 调用失败。固定版本（通过 ANTHROPIC_DEFAULT_*_MODEL 环境变量）可以控制升级节奏，避免意外中断。

Mantle 和标准 Bedrock Invoke API 有什么区别？

Mantle 使用原生 Anthropic API 形状（与直接调用 Anthropic API 格式相同），而 Bedrock Invoke API 使用 Bedrock 特有的 API 形状。Mantle 的模型 ID 格式为 anthropic.claude-haiku-4-5，不带版本后缀。两者可以同时启用，Claude Code 根据模型 ID 格式自动路由请求到正确的端点。

Claude Code on Amazon Bedrock：配置指南、IAM 权限与 Mantle 端点 #

前提条件 #

用 Bedrock 登录 #

手动设置 #

1. 提交使用场景说明 #

2. 配置 AWS 凭据 #

高级凭据配置（自动刷新） #

示例配置 #

配置说明 #

3. 配置 Claude Code #

4. 固定模型版本 #

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

启动模型检查 #

IAM 配置 #

1M token 上下文窗口 #

服务层 #

AWS Guardrails #

使用 Mantle 端点 #

启用 Mantle #

选择 Mantle 模型 #

同时运行 Mantle 和 Invoke API #

通过网关路由 Mantle #

Mantle 环境变量 #

故障排查 #

SSO 与企业代理的认证循环 #

区域问题 #

Mantle 端点错误 #

相关资源 #

常见问题 #

Claude Code on Bedrock 需要哪些最低 IAM 权限？ #

部署给多人使用时为什么必须固定模型版本？ #

Mantle 和标准 Bedrock Invoke API 有什么区别？ #