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. 验证模型是否可用
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 界面):
你不需要伪造的 API 密钥。
3. 验证模型是否被发现
Warning
附加到你的 EC2 实例的 IAM 角色必须具有以下权限:
bedrock:InvokeModelbedrock:InvokeModelWithResponseStreambedrock: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 中按模型设置:
有效值为 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 OpenAI 兼容和 Claude Messages 模型。
提示缓存如何跨提供方工作。
常规故障排除和常见问题解答。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw