古法编程

Appearance

Claude Code on Amazon Bedrock ​

本文说明如何在 Amazon Bedrock 上配置和使用 Claude Code。支持登录向导（/setup-bedrock）快速配置，也支持通过环境变量手动设置（适合 CI 和企业批量部署）。关键步骤包括：提交使用场景、配置 AWS 凭据（支持 CLI/环境变量/SSO/Bedrock API Key）、启用 CLAUDE_CODE_USE_BEDROCK、固定模型版本。还介绍了 AWS Guardrails 内容过滤和新增的 Mantle 端点。

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

前提条件 ​

开始前确保：

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

使用登录向导 ​

如果已有 AWS 凭据，可以通过登录向导快速完成 Bedrock 配置。AWS 侧前提条件每个账户只需完成一次，向导负责处理 Claude Code 侧配置。

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

手动设置 ​

通过环境变量配置 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 配置

bash
aws configure

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

bash
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 配置）

bash
aws sso login --profile=<your-profile-name>
export AWS_PROFILE=your-profile-name

选项 D：AWS Management Console 凭据

bash
aws login

选项 E：Bedrock API Keys

bash
export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API Keys 提供更简单的认证方式，无需完整的 AWS 凭据。

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

Claude Code 支持 AWS SSO 和企业身份提供商的自动凭据刷新。当检测到凭据过期（本地时间戳判断或 Bedrock 返回凭据错误），Claude Code 会自动运行配置的命令获取新凭据后重试。

在 Claude Code 设置文件中添加：

json
{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}
  • awsAuthRefresh：修改 .aws 目录的命令（更新凭据、SSO 缓存等），输出会显示给用户，不支持交互式输入。适合浏览器 SSO 流程（CLI 显示 URL 或验证码，用户在浏览器完成认证）。
  • awsCredentialExport：直接返回凭据的命令（当无法修改 .aws 时使用），输出静默捕获，必须输出以下 JSON：
json
{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

3. 配置 Claude Code ​

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

bash
# 启用 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

注意：AWS_REGION 是必填环境变量，Claude Code 不从 .aws 配置文件读取此设置。使用 Bedrock 时，/login 和 /logout 命令被禁用，认证通过 AWS 凭据处理。

4. 固定模型版本 ​

bash
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. 前缀）。不设置 ANTHROPIC_DEFAULT_OPUS_MODEL 时，Bedrock 上的 opus 别名会解析为 Opus 4.6。将其设置为 Opus 4.7 ID 即可使用最新模型。如果使用不同区域前缀或应用推理配置文件，请相应调整。当前模型 ID 和历史 ID 参见 Models overview。

未设置固定变量时的默认模型：

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

自定义模型设置：

bash
# 使用推理配置文件 ID
export ANTHROPIC_MODEL='global.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

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

如果组织需要在 /model 选择器中暴露同一模型家族的多个版本（各自路由到独立的应用推理配置文件 ARN），使用设置文件的 modelOverrides：这个例子将四个 Opus 版本映射到独立的 ARN，让用户可以在不同版本间切换，而不会绕过组织的应用推理配置文件：

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

启动模型检查 ​

Claude Code v2.1.94+ 在 Bedrock 配置下启动时，会验证目标模型是否可在你的账户中访问：

  • 如果固定的版本比当前默认版本旧，且你的账户可以调用新版本，Claude Code 会提示更新固定——确认后写入用户设置文件并重启
  • 如果未固定模型且当前默认版本不可用，当前会话回退到上一版本并显示提示（不持久保存）
  • 指向应用推理配置文件 ARN 的固定跳过此检查（由管理员管理）

IAM 配置 ​

为 Claude Code 创建包含必要权限的 IAM 策略：

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "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 IAM 文档。

1M Token 上下文窗口 ​

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Amazon Bedrock 上支持 1M token 上下文窗口。Claude Code 选中 1M 模型变体时自动启用扩展上下文。登录向导（/setup-bedrock）在固定模型时提供 1M 上下文选项。要为手动固定的模型启用 1M 上下文，在模型 ID 后追加 [1m]。详情参见模型配置。

AWS Guardrails ​

通过 Amazon Bedrock Guardrails 为 Claude Code 实施内容过滤。在控制台创建 Guardrail 并发布版本后，在设置文件中添加 Guardrail 请求头：

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

如果使用跨区域推理配置文件，需在 Guardrail 上启用 Cross-Region inference。

Mantle 端点 ​

Mantle 是通过原生 Anthropic API 形状而非 Bedrock Invoke API 服务 Claude 模型的 Amazon Bedrock 端点，使用相同的 AWS 凭据和 IAM 权限。

启用 Mantle ​

凭据配置完成后，设置 CLAUDE_CODE_USE_MANTLE 路由请求到 Mantle 端点：

bash
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。可用模型取决于你的账户权限。联系 AWS 账户团队申请访问白名单模型。

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

同时运行 Mantle 和 Invoke API ​

同时设置 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_MANTLE 可让同一会话调用两个端点——anthropic. 格式的模型 ID 路由到 Mantle，其他 ID 走 Bedrock Invoke API：

bash
export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

在设置文件的 availableModels 中列出 Mantle 模型，使其出现在 /model 选择器中：

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

两端点同时激活时，/status 显示 Amazon Bedrock + Amazon Bedrock (Mantle)。

通过网关路由 Mantle ​

如果组织通过集中 LLM 网关路由模型流量（服务端注入 AWS 凭据），可禁用客户端认证，让 Claude Code 发送请求时不带 SigV4 签名或 x-api-key 头：

bash
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 环境变量 ​

变量说明
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 不断重试。在此类网络环境中，建议在启动 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 端点错误 ​

  • /status 没有显示 Amazon Bedrock (Mantle)：确认变量已在启动 claude 的 Shell 中导出，或在设置文件的 env 块中设置
  • 403 错误且凭据有效：账户没有访问所请求模型的权限，联系 AWS 账户团队申请
  • 400 错误且包含模型 ID：该模型不在 Mantle 上提供（Mantle 有独立的模型列表，推理配置文件 ID 如 us.anthropic.claude-sonnet-4-6 在 Mantle 不适用）

相关资源 ​

常见问题 ​

Q: Claude Code 使用 Bedrock 时需要哪些最低 IAM 权限？

至少需要 bedrock:InvokeModel、bedrock:InvokeModelWithResponseStream 和 bedrock:ListInferenceProfiles，Resource 指向 inference-profile/*、application-inference-profile/* 和 foundation-model/*。

Q: 为什么要固定 Bedrock 模型版本？

如果使用模型别名（sonnet/opus/haiku）而不固定具体版本，Anthropic 发布新模型时 Claude Code 可能尝试调用 Bedrock 账户中尚未启用的新版本，导致用户出错。部署给多人使用时必须固定版本。

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

Mantle 通过原生 Anthropic API 形状服务模型（与直接调用 Anthropic API 格式相同），而 Bedrock Invoke API 使用 Bedrock 特有的 API 形状。两者可以同时启用，Claude Code 根据模型 ID 格式自动路由。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策