Cloudflare¶

内置 Cloudflare 插件通过 Cloudflare 的 S3 兼容 API 提供 r2 存储位置。OpenClaw 负责位置标识和加密；插件将对象传输到您的存储桶。配置位置不会安排备份或移动现有数据。

创建存储桶和凭据¶

1. 在 Cloudflare 控制台中，打开 R2 对象存储 并创建私有存储桶，例如 openclaw-artifacts。存储桶名称必须包含 3–63 个小写字母、数字或连字符，且不能以连字符开头或结尾。
2. 记录您的 Cloudflare 账户 ID 以及存储桶的辖区（如有）。
3. 在 R2 的 账户详情 中，选择 API 令牌 旁边的 管理，然后选择 创建账户 API 令牌。
4. 选择 对象读取和写入，并将访问权限限制到您创建的存储桶。
5. 将 访问密钥 ID 和 秘密访问密钥 保存在您的密钥管理器中。Cloudflare 只会显示一次秘密访问密钥。

使用此流程中的 R2 S3 凭据。参见 Cloudflare 的 存储桶创建指南 和 R2 令牌指南。

配置位置¶

在运行 CLI 和 Gateway 的环境中，将已保存的凭据作为 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； 明文凭据字符串会被拒绝。您可以使用另一个已配置的密钥提供程序，而不是环境变量。作为服务运行的 Gateway 需要在其自身环境中包含这些值，而不仅仅在您的交互式 shell 中。

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

初始化和测试¶

确认存储桶和前缀，然后初始化位置并验证完整的写入/读取/删除周期：

openclaw storage init offsite
openclaw storage test offsite
openclaw 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。 无需自定义端点。前缀是存储桶内的命名空间，而不是单独的权限边界；令牌仍然限定在存储桶范围内。

故障排除¶

如果出现 401 或 403 错误，请检查 R2 令牌是否在已配置的存储桶上具有 对象读取和写入 权限，并且两个 SecretRefs 都在运行命令的进程中解析成功。对于临时凭据，还请验证会话令牌是否存在且未过期。

如果缺少存储桶，请在已配置的账户中创建它，或更正 accountId、bucket 和 jurisdiction。OpenClaw 不会创建存储桶。

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

有关加密和位置生命周期，请参阅 存储位置；有关命令输出，请参阅 存储 CLI 参考。