跳转至

Amazon Bedrock

OpenClaw 可以通过其 Bedrock Converse 流式提供商使用 Amazon Bedrock 模型。Bedrock 认证使用 AWS SDK 默认凭证链,而不是 API 密钥。

属性 值
提供商 amazon-bedrock
API bedrock-converse-stream
认证 AWS 凭证(环境变量、共享配置或实例角色)
区域 AWS_REGION 或 AWS_DEFAULT_REGION(默认:us-east-1)

快速开始

选择你偏好的认证方法,并按照设置步骤操作。

**最适合:** 开发机器、CI,或直接管理 AWS 凭证的主机。

1. 在网关主机上设置 AWS 凭证

export AWS_ACCESS_KEY_ID="EXAMPLE_AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# Optional:
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# Optional (Bedrock API key/bearer token):
export AWS_BEARER_TOKEN_BEDROCK="..."

2. 在配置中添加 Bedrock 提供商和模型

不需要 apiKey。使用 auth: "aws-sdk" 配置提供商:

{
  models: {
    providers: {
      "amazon-bedrock": {
        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
        api: "bedrock-converse-stream",
        auth: "aws-sdk",
        models: [
          {
            id: "us.anthropic.claude-opus-4-6-v1",
            name: "Claude Opus 4.6 (Bedrock)",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1" },
    },
  },
}

3. 验证模型可用

openclaw models list

Tip

使用环境变量标记认证(AWS_ACCESS_KEY_ID、AWS_PROFILE 或 AWS_BEARER_TOKEN_BEDROCK)时,OpenClaw 会自动启用隐式 Bedrock 提供商以进行模型发现,无需额外配置。

**最适合:** 附加了 IAM 角色的 EC2 实例,使用实例元数据服务进行认证。

1. 显式启用发现

使用 IMDS 时,OpenClaw 无法仅通过环境变量标记检测 AWS 认证,因此你必须选择加入:

openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1

2. 可选:为自动模式添加环境变量标记

如果你也希望环境变量标记自动检测路径生效(例如用于 openclaw status 界面):

export AWS_PROFILE=default
export AWS_REGION=us-east-1

你不需要伪造的 API 密钥。

3. 验证模型已被发现

openclaw models list

Warning

附加到你的 EC2 实例的 IAM 角色必须具有以下权限:

  • bedrock:InvokeModel
  • bedrock:InvokeModelWithResponseStream
  • bedrock:ListFoundationModels(用于自动发现)
  • bedrock:ListInferenceProfiles(用于推理配置文件发现)

或者附加托管策略 AmazonBedrockFullAccess。

Note

只有当你确实需要为自动模式或状态界面提供环境变量标记时,才需要 AWS_PROFILE=default。实际的 Bedrock 运行时认证路径使用 AWS SDK 默认链,因此即使没有环境变量标记,IMDS 实例角色认证也能工作。

自动模型发现

OpenClaw 可以自动发现支持流式和文本输出的 Bedrock 模型。发现使用 bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles,结果会被缓存(默认:1 小时)。

在 OpenClaw 缓存结果之前,两个列表(包括每个推理配置文件页面)都必须成功。刷新失败会报告目录访问不可用或被拒绝,并保留兼容的上次有效模型。恢复对两个列表操作的访问权限后,再次刷新。成功返回空列表会清除已发现的成员资格。

在启动时如果没有兼容的上次目录,推理配置文件列表失败也会阻止仅基础模型清单。授予两个列表权限,或使用显式的 models.providers["amazon-bedrock"].models 列表。

插件公开发现辅助函数的编程调用者保留 v2026.9.2 中的建议默认值。传入 discoveryMode: "strict" 以传播获取失败并保留成功的空提供商结果,正如捆绑的目录钩子所做的那样。建议的部分结果不会被缓存为完整清单。

隐式提供商如何启用:

  • 如果 plugins.entries.amazon-bedrock.config.discovery.enabled 为 true, 即使没有 AWS 环境变量标记,OpenClaw 也会尝试发现。
  • 如果 plugins.entries.amazon-bedrock.config.discovery.enabled 未设置, OpenClaw 只有在看到以下 AWS 认证标记之一时,才会自动添加 隐式 Bedrock 提供商: AWS_BEARER_TOKEN_BEDROCK、AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY 或 AWS_PROFILE。
  • 实际的 Bedrock 运行时认证路径仍使用 AWS SDK 默认链,因此 共享配置、SSO 和 IMDS 实例角色认证可以工作,即使发现 需要 enabled: true 来选择加入。

Note

对于显式的 models.providers["amazon-bedrock"] 条目,OpenClaw 仍可以从 AWS_BEARER_TOKEN_BEDROCK 等 AWS 环境变量标记中提前解析 Bedrock 环境变量标记认证,而无需强制加载完整的运行时认证。实际的模型调用认证路径仍使用 AWS SDK 默认链。

发现配置选项

配置选项位于 plugins.entries.amazon-bedrock.config.discovery 下:

{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          discovery: {
            enabled: true,
            region: "us-east-1",
            providerFilter: ["anthropic", "amazon"],
            refreshInterval: 3600,
            defaultContextWindow: 32000,
            defaultMaxTokens: 4096,
          },
        },
      },
    },
  },
}
选项 默认值 描述
enabled auto 在 auto 模式下,OpenClaw 仅在看到受支持的 AWS 环境变量标记时启用隐式 Bedrock 提供商。设置为 true 以强制发现。
region AWS_REGION / AWS_DEFAULT_REGION / us-east-1 用于发现 API 调用的 AWS 区域。
providerFilter 全部 匹配 Bedrock 提供商名称(例如 anthropic、amazon)。
refreshInterval 3600 缓存时长(秒)。设置为 0 可禁用缓存。
defaultContextWindow 32000 用于没有已知 Token 限制的已发现模型的上下文窗口(如果你知道模型限制,可覆盖)。
defaultMaxTokens 4096 用于没有已知 Token 限制的已发现模型的最大输出 Token 数(如果你知道模型限制,可覆盖)。
上下文窗口与最大 Token 限制

Bedrock 的 ListFoundationModels 和 GetFoundationModel API 不返回 Token 限制元数据,只返回模型 ID、名称、模态和生命周期状态。OpenClaw 内置了热门 Bedrock 模型(Claude、Nova、Llama、Mistral、DeepSeek 等) 的已知上下文窗口和输出限制查找表,以便会话管理、压缩阈值和上下文溢出 检测对这些模型正常工作。

不在表中的已发现模型会回退到 defaultContextWindow 和 defaultMaxTokens。如果你使用的模型缺少准确限制,请使用显式的 models.providers["amazon-bedrock"].models 条目进行覆盖。

快速设置(AWS 路径)

本演练将创建一个 IAM 角色,附加 Bedrock 权限,关联实例配置文件,并在 EC2 主机上启用 OpenClaw 发现。

# 1. Create IAM role and instance profile
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"
    }]
  }'

aws iam attach-role-policy --role-name EC2-Bedrock-Access \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

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

# 2. Attach to your EC2 instance
aws ec2 associate-iam-instance-profile \
  --instance-id i-xxxxx \
  --iam-instance-profile Name=EC2-Bedrock-Access

# 3. On the EC2 instance, enable discovery explicitly
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1

# 4. Optional: add an env marker if you want auto mode without explicit enable
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc

# 5. Verify models are discovered
openclaw models list

高级配置

推理配置文件

OpenClaw 会同时发现区域性和全局推理配置文件以及基础模型。当某个 配置文件映射到已知基础模型时,该配置文件会继承该模型的能力(上下文窗口、 最大 Token 数、推理、视觉),并自动注入正确的 Bedrock 请求区域。这意味着 跨区域 Claude 配置文件无需手动提供商覆盖即可工作。全局跨区域配置文件 (global.*)会优先列在 openclaw models list 中,因为它们通常提供 更好的容量和自动故障转移。

推理配置文件 ID 形如 us.anthropic.claude-opus-4-6-v1(区域性)或 anthropic.claude-opus-4-6-v1(全局)。如果底层模型已存在于发现结果中, 配置文件会继承其完整能力集;否则应用安全默认值。

无需额外配置。只要发现已启用,并且 IAM 主体具有 bedrock:ListInferenceProfiles 权限,配置文件就会与基础模型一起显示在 openclaw models list 中。

服务层级

某些 Bedrock 模型支持 service_tier 参数,以优化成本或延迟。可用层级 如下:

层级 描述
default 标准 Bedrock 层级
flex 适用于可容忍较长延迟的工作负载的折扣处理
priority 适用于延迟敏感型工作负载的优先处理
reserved 适用于稳态工作负载的预留容量

通过 agents.defaults.params 为 Bedrock 模型请求设置 serviceTier (或 service_tier),或在 agents.defaults.models["<model-key>"].params 中按模型设置:

{
  agents: {
    defaults: {
      params: {
        serviceTier: "flex", // applies to all models
      },
      models: {
        "amazon-bedrock/mistral.mistral-large-3-675b-instruct": {
          params: {
            serviceTier: "priority", // per-model override
          },
        },
      },
    },
  },
}

有效值为 default、flex、priority 和 reserved。Claude Fable 5、 Opus 5 和 Sonnet 5 仅支持 default 层级;OpenClaw 会发出警告并忽略针对 这些模型请求的 flex、priority 或 reserved。对于其他模型,并非每个 模型都支持每个层级——不支持的层级会返回 Bedrock 验证错误,且错误信息可能 具有误导性(例如显示 "The provided model identifier is invalid",而不是 指出层级是问题所在)。如果你看到此错误,请检查该模型是否支持所请求的层级。

Claude Opus 5、4.8 和 4.7 的 temperature

Bedrock 会拒绝 Claude Opus 5、Opus 4.8 和 Opus 4.7 的 temperature 参数。对于任何匹配的 Bedrock ref,OpenClaw 都会自动省略 temperature,包括基础模型 ID、命名推理配置文件、通过 bedrock:GetInferenceProfile 解析为 Opus 5/4.8/4.7 的应用推理配置文件,以及带可选区域前缀 (us.、eu.、ap.、apac.、au.、jp.、global.)的点分 opus-4.7/opus-4.8 变体。 无需任何配置项,且该省略同时适用于请求选项对象和 inferenceConfig 负载字段。

Claude Opus 5

在 Messages-API Bedrock 端点上使用 amazon-bedrock/anthropic.claude-opus-5,或者当区域/全局推理配置文件 出现在 Bedrock 发现中时,使用诸如 global.anthropic.claude-opus-5 的配置文件。 OpenClaw 会应用 1,000,000 token 上下文窗口、128,000 token 输出限制、图像输入、提示缓存、 拒绝安全流式传输,以及原生 xhigh/max effort 级别。

自适应思考默认为 high。/think off 会禁用思考,而 /think xhigh|max 会保持自适应思考启用。 OpenClaw 会省略自定义采样参数以及不受支持的非默认服务层级。

Claude Fable 5

在 us-east-1 中使用 amazon-bedrock/anthropic.claude-fable-5,或使用诸如 us.anthropic.claude-fable-5 的区域推理 ID。 OpenClaw 会应用 Fable 的 1M 上下文窗口、128K 输出限制、始终启用的自适应思考, 以及受支持的 effort 映射。Fable 5 和 5.1 默认使用 medium effort;显式 effort 设置优先。 /think off 和 /think minimal 映射到 low;temperature 和强制工具选择控制会被省略, 与 Opus 4.7/4.8 路由一致。流式输出会保留,直到 Bedrock 返回终止状态, 因此流中拒绝不会暴露部分文本。

AWS 要求在 Fable 可用之前显式选择加入 provider_data_share 数据保留。提示和补全会与 Anthropic 共享,并最多保留 30 天用于信任和安全。启用该模型之前,请审阅并配置 Bedrock 数据保留。

Claude Mythos 5

Claude Mythos 5 仅对具有所需有限访问批准的账户通过 Bedrock 提供。OpenClaw 识别基础模型 anthropic.claude-mythos-5 以及诸如 us.anthropic.claude-mythos-5 的区域或全局推理配置文件。

OpenClaw 会应用 1,000,000 token 上下文窗口、128,000 token 输出限制、图像输入、提示缓存、 拒绝安全流式传输,以及原生 effort 级别。自适应思考始终启用:/think off 和 /think minimal 映射到 low,而 xhigh 和 max 仍可用。自定义采样和强制工具选择值会被省略。

Claude Sonnet 5

AWS 为 bedrock-runtime 和 bedrock-mantle 端点 都记录了 Sonnet 5。OpenClaw 识别 Bedrock 基础模型 anthropic.claude-sonnet-5 以及诸如 us.anthropic.claude-sonnet-5 的区域或全局推理配置文件。它会应用 1,000,000 token 上下文 窗口、128,000 token 输出限制、图像输入、原生 effort 级别、提示缓存,以及拒绝安全流式传输。

Bedrock 会为 Sonnet 5 保持自适应思考启用。OpenClaw 默认为 high;由于此路由无法禁用思考, /think off 和 /think minimal 映射到 low。在自适应思考激活时,自定义 temperature 和 强制工具选择值会被省略。

Guardrails
你可以通过在 `amazon-bedrock` 插件配置中添加 `guardrail` 对象,将 [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)
应用于所有 Bedrock 模型调用。Guardrails 可让你强制内容过滤、主题拒绝、词过滤、敏感信息过滤
和上下文接地检查。

```json5
{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          guardrail: {
            guardrailIdentifier: "abc123", // guardrail ID or full ARN
            guardrailVersion: "1", // version number or "DRAFT"
            streamProcessingMode: "sync", // optional: "sync" or "async"
            trace: "enabled", // optional: "enabled", "disabled", or "enabled_full"
          },
        },
      },
    },
  },
}
```

`guardrailIdentifier` 和 `guardrailVersion` 是必需的。

| 选项 | 描述 |
| ------ | ----------- |
| `guardrailIdentifier` | Guardrail ID(例如 `abc123`)或完整 ARN(例如 `arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123`)。 |
| `guardrailVersion` | 已发布版本号,或用于工作草稿的 `"DRAFT"`。 |
| `streamProcessingMode` | 流式传输期间用于 guardrail 评估的 `"sync"` 或 `"async"`。如果省略,Bedrock 会使用其默认值。 |
| `trace` | 用于调试的 `"enabled"` 或 `"enabled_full"`;生产环境请省略或设置为 `"disabled"`。 |

Warning

网关使用的 IAM 主体除了标准调用权限外,还必须具有 bedrock:ApplyGuardrail 权限。

用于记忆搜索的嵌入

Bedrock 也可以作为 记忆搜索 的嵌入提供方。 这与推理提供方分开配置——将 memory.search.provider 设置为 "bedrock":

{
  memory: {
    search: {
      provider: "bedrock",
      model: "amazon.titan-embed-text-v2:0", // default
    },
  },
}

Bedrock 嵌入使用与推理相同的 AWS SDK 凭证链(实例角色、SSO、访问密钥、共享配置和 Web 身份)。无需 API 密钥。

支持的嵌入模型包括 Amazon Titan Embed(v1、v2)、Amazon Nova Embed、Cohere Embed(v3、v4)和 TwelveLabs Marengo。完整模型列表和维度选项,请参阅 Memory 配置参考 -- Bedrock。

说明与注意事项
  • Bedrock 需要在您的 AWS 账户/区域中启用模型访问。
  • 自动发现需要 bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles 权限。
  • 如果依赖自动模式,请在网关主机上设置其中一个受支持的 AWS 身份验证环境变量标记。如果偏好 IMDS/共享配置身份验证而不使用环境变量标记,请设置 plugins.entries.amazon-bedrock.config.discovery.enabled: true。
  • OpenClaw 按以下顺序显示凭证来源:AWS_BEARER_TOKEN_BEDROCK, 然后是 AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY,然后是 AWS_PROFILE,最后是 默认 AWS SDK 链。
  • 推理支持取决于模型;请查看 Bedrock 模型卡片了解当前能力。
  • 如果偏好托管密钥流程,也可以在 Bedrock 前面放置一个 OpenAI 兼容 代理,并将其配置为 OpenAI 提供商。

模型选择

选择提供商、模型引用和故障转移行为。

Memory 搜索

用于 Memory 搜索配置的 Bedrock 嵌入。

Memory 配置参考

完整的 Bedrock 嵌入模型列表和维度选项。

Bedrock Mantle

Bedrock Mantle OpenAI 兼容和 Claude Messages 模型。

Prompt 缓存

Prompt 缓存如何在各提供商之间工作。

故障排除

通用故障排除和常见问题解答。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw