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. 验证模型可用
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 默认链,因此
共享配置、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":
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 搜索配置的 Bedrock 嵌入。
完整的 Bedrock 嵌入模型列表和维度选项。
Bedrock Mantle OpenAI 兼容和 Claude Messages 模型。
Prompt 缓存如何在各提供商之间工作。
通用故障排除和常见问题解答。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw