Cloudflare

捆绑的 Cloudflare 插件通过 Cloudflare 的 S3- 兼容 API 提供 r2 存储位置。 OpenClaw 处理位置身份和加密；该插件将对象传输到您的存储桶。配置位置不会安排备份或移动现有数据。

创建存储桶和凭证

1. 在Cloudflare仪表板中，打开R2对象存储并创建私有存储桶，例如openclaw-artifacts。存储桶名称必须包含 3-63 个小写字母、数字或连字符，并且不能以连字符开头或结尾。
2. 记录您的 Cloudflare 账户 ID 以及存储桶的管辖区（如果有）。
3. 从R2的账户详细信息中，选择API代币旁边的管理，然后创建账户API代币。
4. 选择 Object Read & Write 并限制对您创建的存储桶的访问。
5. 将 访问密钥 ID 和 秘密访问密钥 保存在您的秘密管理器中。 Cloudflare 仅显示一次秘密访问密钥。

使用此流程中的 R2 S3 凭证。请参阅Cloudflare的桶创建指南和R2代币指南。

配置位置

在运行 CLI 和网关的环境中，使保存的凭据可用作 R2_ACCESS_KEY_ID 和 R2_SECRET_ACCESS_KEY。创建单独的加密密码，在机密管理器中保留可恢复的副本，并在该环境中将其提供为 OPENCLAW_STORAGE_PASSPHRASE。

将此添加到您的 OpenClaw 配置中，替换示例帐户 ID 和存储桶：

{  storage: {    locations: {      offsite: {        provider: "r2",        settings: {          accountId: "00000000000000000000000000000000",          bucket: "openclaw-artifacts",          prefix: "openclaw",          accessKeyId: {            source: "env",            provider: "default",            id: "R2_ACCESS_KEY_ID",          },          secretAccessKey: {            source: "env",            provider: "default",            id: "R2_SECRET_ACCESS_KEY",          },        },        encryption: {          passphrase: {            source: "env",            provider: "default",            id: "OPENCLAW_STORAGE_PASSPHRASE",          },        },      },    },  },}

R2凭证设置需要SecretRefs；纯文本凭证字符串被拒绝。您可以使用另一个配置的秘密提供程序而不是环境变量。作为服务运行的网关需要其自身环境中的值，而不仅仅是交互式 shell 中的值。

在正常插件策略下，引用 provider: "r2" 会自动启用捆绑的 cloudflare 插件。显式禁用和拒绝规则仍然适用。

初始化并测试

确认桶和前缀，然后初始化位置并验证完整的write/read/delete循环：

openclaw storage init offsiteopenclaw storage test offsiteopenclaw storage list --json

对于上面的示例，初始化将位置标记写入 openclaw/openclaw-storage.json。显示的目标是r2://openclaw-artifacts/openclaw。成功的测试确认它写入、读取、验证和删除了其检查对象；添加 --json 为 state: "ok"。保留标记和加密密码：丢失其中任何一个都会导致加密对象不可读。 R2 运行状况检查验证存储桶访问，而不报告可用空间或总空间。

设置

以下所有字段均属于 storage.locations.<name>.settings。

该插件使用区域 auto。默认选择 https://<accountId>.r2.cloudflarestorage.com，"eu" 默认选择 https://<accountId>.eu.r2.cloudflarestorage.com，"fedramp" 默认选择 https://<accountId>.fedramp.r2.cloudflarestorage.com。不需要自定义端点。前缀是存储桶内的命名空间，而不是单独的权限边界；令牌的范围仍然是存储桶。

故障排查

下载使用连续的 64 个 MiB 范围，并在连接重置、超时或可重试服务器错误后从最后接收的字节恢复，每个范围最多重试八次。每个范围必须与原始对象的 ETag 匹配。如果对象在下载过程中发生变化，请重新启动命令以读取新对象。失败的下载报告字节数和下一个偏移量；重新启动命令会启动新的下载，而不是重用以前的临时文件。

对于 401 或 403 错误，请检查 R2 令牌在配置的存储桶上是否具有 Object Read & Write，以及 SecretRefs 是否在运行命令的进程中解析。对于临时凭证，还要验证会话令牌是否存在且尚未过期。

如果桶缺失，请在配置的账户中创建或者修改accountId、bucket、jurisdiction。 OpenClaw 不创建桶。

如果该位置没有初始化标记，请在运行 openclaw storage init <name> 之前确认前缀正确。更改前缀会选择不同的位置根。对于wrong-key，恢复原始加密密码；替换标记不会恢复加密数据。

请参阅 存储位置 了解加密和位置生命周期，并参阅 存储 CLI 参考 了解命令输出。