OpenClaw 集成 Amazon Bedrock 完全指南

原创

jack.yang

发布于 2026-03-18 20:45:28

核心能力：通过 Bedrock Converse API 无缝接入 AWS 托管的顶级模型（如 Claude 3.5/4.0, Llama 3, Mistral 等）。 认证机制：原生支持 AWS SDK 凭证链（无需 API Key），完美适配 EC2 实例角色、IAM User 及本地 Profile。 特色功能：自动模型发现、流式推理、企业级安全隔离。

🏗️ 一、架构与原理

OpenClaw 通过 pi-ai 提供的 bedrock-converse-stream 适配器与 Amazon Bedrock 交互。

Provider ID: amazon-bedrock
API 模式: bedrock-converse-stream (支持流式输出)
认证方式: 遵循标准 AWS SDK 凭证链 (Environment Variables > Shared Config > Instance Role)。
区域默认值: us-east-1 (可通过 AWS_REGION 覆盖)。

💡 优势：相比直接调用第三方 API，Bedrock 提供了数据不出境、VPC 私有连接、审计日志等企业级安全特性。

🔐 二、认证配置 (三种场景)

Bedrock 不需要 传统的 apiKey 字段，而是依赖 AWS 环境凭证。

场景 A: 本地开发 / 非 EC2 服务器 (IAM User)

在运行 OpenClaw Gateway 的机器上导出环境变量：

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1" 
# 如果有临时凭证 (如 SSO)
export AWS_SESSION_TOKEN="..."

场景 B: EC2 实例角色 (推荐生产环境) ⭐

当 OpenClaw 运行在附带 IAM Role 的 EC2 实例上时，SDK 会自动通过 IMDS 获取凭证。

⚠️ 重要变通方案 (Workaround)：目前 OpenClaw 的凭证检测逻辑主要检查环境变量。为了触发 Bedrock provider 的激活，必须手动设置 AWS_PROFILE 变量，即使你使用的是实例角色。

操作步骤：

编辑 ~/.bashrc 或系统环境变量：export AWS_PROFILE=default # 关键步骤：欺骗检测逻辑 export AWS_REGION=us-east-1
生效配置：source ~/.bashrc
实际鉴权仍由 AWS SDK 通过 IMDS 自动完成，无需真实存在 default profile 文件。

所需 IAM 权限：确保 EC2 实例角色拥有以下权限（或直接附加 AmazonBedrockFullAccess）：

bedrock:InvokeModel
bedrock:InvokeModelWithResponseStream
bedrock:ListFoundationModels (用于自动发现模型)

场景 C: AWS Profile 多账户管理

如果你使用 ~/.aws/credentials 管理多账户：

export AWS_PROFILE="my-bedrock-prod"
export AWS_REGION="us-west-2"

🔍 三、自动模型发现 (Auto Discovery)

OpenClaw 可以自动扫描你的 AWS 账户中已启用且支持流式文本的 Bedrock 模型，无需手动录入每个模型 ID。

配置选项 (`models.bedrockDiscovery`)

{
  "models": {
    "bedrockDiscovery": {
      "enabled": true,          // 有 AWS 凭证时默认为 true
      "region": "us-east-1",    // 扫描区域
      "providerFilter": ["anthropic", "amazon", "meta"], // 只扫描特定厂商
      "refreshInterval": 3600,  // 缓存时间 (秒), 0 为禁用缓存
      "defaultContextWindow": 32000, // 发现模型的默认上下文 (若元数据缺失)
      "defaultMaxTokens": 4096     // 发现模型的默认最大输出
    }
  }
}

工作原理

调用 bedrock:ListFoundationModels 接口。
过滤出支持 TEXT 输入/输出且支持 STREAMING 的模型。
结果缓存 1 小时，避免频繁调用 AWS API。

注意：必须在 AWS Bedrock 控制台先点击 "Request Access" 或 "Enable Model"，否则发现工具扫不到该模型。

⚙️ 四、手动配置模型 (高级)

如果你需要自定义模型参数（如成本核算、特定版本号），可以手动在 openclaw.json 中定义。

{
  "models": {
    "providers": {
      "amazon-bedrock": {
        "baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
        "api": "bedrock-converse-stream",
        "auth": "aws-sdk", // 关键：使用 AWS SDK 认证
        "models": [
          {
            "id": "us.anthropic.claude-opus-4-6-v1:0",
            "name": "Claude Opus 4.6 (Bedrock)",
            "reasoning": true,       // 是否支持推理
            "input": ["text", "image"], // 支持多模态
            "contextWindow": 200000, // 200k 上下文
            "maxTokens": 8192,
            "cost": { 
              "input": 0, "output": 0, // Bedrock 费用通常由 AWS 账单统一结算，此处可填 0 或内部核算价
              "cacheRead": 0, "cacheWrite": 0 
            }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { 
        "primary": "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" 
      }
    }
  }
}

🚀 五、EC2 一键部署脚本 (生产环境推荐)

如果你要在 AWS EC2 上快速搭建支持 Bedrock 的 OpenClaw 节点，可参考以下流程：

# 1. 创建 IAM Role (需在本地 AWS CLI 配置好的机器运行)
aws iam create-role --role-name EC2-Bedrock-Access \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# 2. 绑定 Bedrock 全量访问策略
aws iam attach-role-policy --role-name EC2-Bedrock-Access \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

# 3. 创建实例配置文件并关联 Role
aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-Bedrock-Access \
  --role-name EC2-Bedrock-Access

# 4. 将 Profile 绑定到目标 EC2 实例 (替换 i-xxxxx)
aws ec2 associate-iam-instance-profile \
  --instance-id i-0abcdef1234567890 \
  --iam-instance-profile Name=EC2-Bedrock-Access

# ---------------------------------------------------------
# 以下命令在 EC2 实例内部执行
# ---------------------------------------------------------

# 5. 开启模型发现
openclaw config set models.bedrockDiscovery.enabled true
openclaw config set models.bedrockDiscovery.region us-east-1

# 6. 设置环境变量变通方案 (关键!)
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc

# 7. 验证模型列表
openclaw models list

❓ 六、常见问题排查

问题	可能原因	解决方案
No credentials found	未检测到 AWS 凭证	1. 检查 AWS_ACCESS_KEY_ID 等环境变量。2. EC2 用户务必设置 AWS_PROFILE=default。
Model not found	模型未在 AWS 端启用	登录 AWS Console -> Bedrock -> Model Access，申请对应模型权限。
Access Denied	IAM 权限不足	确保 Role 包含 bedrock:InvokeModel 和 bedrock:ListFoundationModels。
Region Mismatch	模型不在当前区域	检查 AWS_REGION 是否与模型 ID 前缀匹配 (如 us. 开头需对应 US 区域)。
Throttling	请求速率限制	Bedrock 有默认的 TPM/RPM 限制，可在 AWS 控制台申请提额。

💡 七、最佳实践建议

优先使用 EC2 实例角色：避免在代码或配置文件中硬编码 Access Key，利用 IMDS 实现零密钥管理。
启用自动发现：利用 bedrockDiscovery 动态感知新发布的模型，减少维护配置的工作量。
关注区域一致性：Bedrock 模型具有区域性（如 us.anthropic... 只能在 US 区域调用），确保 AWS_REGION 与模型 ID 匹配。
成本监控：虽然配置中 cost 可设为 0，但请务必在 AWS Cost Explorer 中监控 Bedrock 的实际用量，特别是高分辨率图片输入和高 Token 输出场景。
备用方案：如果需要更灵活的密钥管理或跨云调度，也可以考虑在 Bedrock 前架设 OpenAI 兼容代理 (Proxy)，将其作为标准 OpenAI Provider 接入 OpenClaw。

通过 Amazon Bedrock，OpenClaw 能够为企业用户提供最安全、合规且强大的大模型推理后端。🛡️🧠

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

OpenClaw(Clawdbot)