跳转至

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)

自定义提供商 ID(例如 amazon-bedrock-east1)可以使用 api: "bedrock-converse-stream" 和 auth: "aws-sdk"。它们会激活同一个 Bedrock 插件。区域来自所选提供商的标准 bedrock-runtime.<region>.amazonaws.com URL,然后是解析后的模型 URL,再然后是插件发现区域。如果没有其中任何一项,则应用 AWS SDK 区域环境变量和配置文件设置。自定义路由不会继承标准 amazon-bedrock 提供商的区域。

快速入门

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

**最适合:** 开发机器、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 默认链,因此即使发现需要 enabled: true 来选择加入,共享配置、SSO 和 IMDS 实例角色认证也可以工作。

Note

对于显式的 models.providers["amazon-bedrock"] 条目,OpenClaw 仍可在早期从 AWS 环境变量标记(例如 AWS_BEARER_TOKEN_BEDROCK)解析 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 (all) 匹配 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 参数。OpenClaw 会自动为任何匹配的 Bedrock 引用省略 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,或使用区域推理 id,例如 us.anthropic.claude-fable-5。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 data retention 后再启用该模型。

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。完整模型列表和维度选项请参见 记忆配置参考 -- 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 提供方。

模型选择

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

记忆搜索

用于记忆搜索配置的 Bedrock 嵌入。

记忆配置参考

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

Bedrock Mantle

Bedrock Mantle OpenAI 兼容和 Claude Messages 模型。

提示缓存

提示缓存如何跨提供方工作。

故障排除

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

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