跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 可以通过 pi-ai 的 Bedrock Converse 流式提供商使用 Amazon Bedrock 模型。Bedrock 凭证使用 AWS SDK 默认凭证链，而不是 API 密钥。
属性值
提供商amazon-bedrock
APIbedrock-converse-stream
凭证AWS 凭证（环境变量、共享配置或实例角色）
区域AWS_REGION 或 AWS_DEFAULT_REGION（默认：us-east-1）

​
入门指南

选择你偏好的凭证方式，并按设置步骤操作。
**最适合：**开发机器、CI，或你直接管理 AWS 凭证的主机。
1

在 Gateway 网关主机上设置 AWS 凭证

export AWS_ACCESS_KEY_ID="AKIA..."
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:0",
            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:0" },
    },
  },
}
3

验证模型可用

openclaw models list
使用环境标记凭证（AWS_ACCESS_KEY_ID、AWS_PROFILE 或 AWS_BEARER_TOKEN_BEDROCK）时，OpenClaw 会自动启用隐式 Bedrock 提供商，用于模型发现，无需额外配置。

​
自动模型发现

OpenClaw 可以自动发现支持流式传输和文本输出的 Bedrock 模型。发现使用 bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles，结果会被缓存（默认：1 小时）。 隐式提供商的启用方式：
  • 如果 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 才能选择启用时也可以工作。
对于显式的 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,
          },
        },
      },
    },
  },
}
选项默认值说明
enabledauto在 auto 模式下，OpenClaw 只有在看到受支持的 AWS 环境变量标记时，才会启用隐式 Bedrock 提供商。设为 true 可强制设备发现。
regionAWS_REGION / AWS_DEFAULT_REGION / us-east-1用于设备发现 API 调用的 AWS 区域。
providerFilter(all)匹配 Bedrock 提供商名称（例如 anthropic、amazon）。
refreshInterval3600缓存时长，单位为秒。设为 0 可禁用缓存。
defaultContextWindow32000用于已发现模型的上下文窗口（如果你知道模型限制，可覆盖）。
defaultMaxTokens4096用于已发现模型的最大输出 token 数（如果你知道模型限制，可覆盖）。

​
快速设置（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 配置文件无需手动提供商覆盖即可工作。推理配置文件 ID 的形式类似于 us.anthropic.claude-opus-4-6-v1:0（区域）或 anthropic.claude-opus-4-6-v1:0（全局）。如果其背后的模型已经在发现结果中，该配置文件会继承其完整能力集；否则会应用安全默认值。不需要额外配置。只要已启用发现，并且 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。并非所有模型都支持所有层级。如果请求了不受支持的层级，Bedrock 会返回验证错误。注意：该错误消息有些误导；它可能会说“The provided model identifier is invalid”，而不是指出服务层级不受支持。如果你看到此错误，请检查该模型是否支持所请求的层级。
Bedrock 会拒绝 Claude Opus 4.7 的 temperature 参数。对于任何 Opus 4.7 Bedrock 引用，OpenClaw 都会自动省略 temperature，包括基础模型 ID、命名推理配置文件、其底层模型通过 bedrock:GetInferenceProfile 解析为 Opus 4.7 的应用推理配置文件，以及带有可选区域前缀（us.、eu.、ap.、apac.、au.、jp.、global.）的点分 opus-4.7 变体。不需要配置开关，并且该省略同时适用于请求选项对象和 inferenceConfig 载荷字段。
你可以通过在 amazon-bedrock 插件配置中添加 guardrail 对象，将 Amazon Bedrock Guardrails 应用于所有 Bedrock 模型调用。Guardrails 允许你强制执行内容过滤、 主题拒绝、词语过滤、敏感信息过滤和上下文 grounding 检查。
{
  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是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"。
Gateway 网关使用的 IAM 主体除了标准调用权限外，还必须拥有 bedrock:ApplyGuardrail 权限。
Bedrock 也可以作为 记忆搜索的嵌入提供商。这与 推理提供商分开配置，将 agents.defaults.memorySearch.provider 设为 "bedrock"：
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0", // default
      },
    },
  },
}
Bedrock 嵌入使用与推理相同的 AWS SDK 凭证链（实例 角色、SSO、访问密钥、共享配置和 Web 身份）。不需要 API key。当 provider 为 "auto" 时，如果该凭证链成功解析，Bedrock 会被自动检测到。支持的嵌入模型包括 Amazon Titan Embed（v1、v2）、Amazon Nova Embed、Cohere Embed（v3、v4）和 TwelveLabs Marengo。完整模型列表和维度选项见 记忆配置参考 — Bedrock。
  • Bedrock 要求在你的 AWS 账户/区域中启用模型访问权限。
  • 自动发现需要 bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles 权限。
  • 如果你依赖自动模式，请在 Gateway 网关主机上设置一个受支持的 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 provider。

​
相关内容

模型选择

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

记忆搜索

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

记忆配置参考

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

故障排除

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