存储位置¶

存储位置为 OpenClaw 产物指定一个目标位置。核心存储负责位置标识、加密和健康检查。提供者传输对象，每个消费者决定存储和保留什么。配置位置不会安排备份或移动现有数据。

内置的 filesystem 提供者支持现有目录，包括外部磁盘或已挂载的网络文件系统。其他提供者来自插件。在配置中引用捆绑的提供者会通过常规插件策略启用其所属插件；显式禁用仍然适用。

对于 Cloudflare R2 对象存储，请按照 Cloudflare 插件设置创建存储桶、配置 SecretRefs，并初始化一个 r2 位置。

配置并初始化目录¶

在初始化存储之前，挂载目标磁盘并在其上创建目标目录。OpenClaw 从不创建已配置的根目录。使用运行 CLI 或 Gateway 的进程所看到的绝对路径。

在该进程的环境中设置 OPENCLAW_STORAGE_PASSPHRASE，并在您的密钥管理器中保留其值的一份可恢复副本。在配置中添加一个位置：

{
  storage: {
    locations: {
      archive: {
        provider: "filesystem",
        settings: { path: "/mnt/archive/openclaw" },
        encryption: {
          passphrase: {
            source: "env",
            provider: "default",
            id: "OPENCLAW_STORAGE_PASSPHRASE",
          },
        },
      },
    },
  },
}

显式初始化目标，然后验证写入/读取/删除循环：

openclaw storage init archive
openclaw storage test archive
openclaw storage list --json

初始化会在位置根目录写入 openclaw-storage.json。使用相同的加密设置和密码短语再次运行 init 是安全的。运行时操作从不创建此标记：空挂载点不应静默地变成系统磁盘上的存储。

配置参考¶

存储是可选的；省略 storage 或 storage.locations 表示不定义任何位置。 storage.locations 下的每个键都是一个名称，匹配 [a-z0-9][a-z0-9-]{0,62}：1–63 个小写字母、数字或连字符，以字母或数字开头。

键	必需	含义
`storage.locations.<name>.provider`	是	非空提供者 id；`filesystem` 为内置。
`storage.locations.<name>.settings`	是	由提供者拥有的 JSON 对象，在打开后端之前进行验证。
`storage.locations.<name>.encryption`	是	`{ passphrase: SecretInput }` 或显式字符串 `"none"`。
`storage.locations.<name>.encryption.passphrase`	启用加密时	密码短语字符串或 SecretRef；优先使用引用。

filesystem 提供者接受 settings: { path: "/absolute/existing/directory" }。它拒绝缺失的根目录，并且从不覆盖现有对象键。其探测在可用时会报告文件系统的可用空间和总空间。

提供者设置必须是有限的、有界的 JSON：最多 32 层嵌套、4,096 个值、每个对象 512 个键、字符串长度 65,536，序列化后 256 KiB。包含密钥的设置（包括 accessKeyId、secretAccessKey 和嵌套凭据）必须使用有效的 SecretRefs。特定提供者的验证可以施加额外约束。SecretRefs 保持为引用，直到提供者通过核心密钥解析器请求其值。

审慎选择加密¶

使用密码短语时，核心存储会在提供者接收对象流之前对其进行加密，并在读取时解密。 OCSTOR1 格式使用 scrypt 派生主密钥，并为每个对象使用独立的密钥进行经过身份验证的 AES-256-GCM 分段。错误的密码短语会产生 wrong-key 并拒绝访问。更改已配置的密码短语不会重新加密现有数据。

同时保留密码短语和位置标记。丢失其中任何一个都可能导致加密对象无法读取。对象名称和初始化标记对存储提供者可见；加密保护对象内容。

仅将 encryption: "none" 作为显式的操作员选择，例如目标已由磁盘加密保护。备份可能包含凭据。 如果没有存储加密，任何能够读取目标的人都可以读取存储的字节。

备份在位置内使用 backups/<namespace>/。命名空间默认为清理后的主机名；使用 --namespace <name> 为共享目标的每个安装选择稳定且不同的名称。

首次上传会创建一个 owner.json 声明，其中包含该安装的持久 Gateway 设备 ID、主机名和声明时间。它使用与归档相同的位位置加密设置。备份创建会在归档前检查声明，并在保留前再次检查。不同的设备 ID 会拒绝备份并记录一次失败尝试，防止主机名冲突导致共享保留。保留策略从不删除声明。

向 backup create --to <location> 传递 --claim-namespace 以有意接管一个命名空间，例如迁移到新硬件之后。backup enable --to 也接受该标志，并且仅在显式传递时将其存储在计划命令中；这些计划运行随后可以替换另一个安装的声明。如果两个安装都将继续运行，请优先使用单独的命名空间。

恢复保持只读：使用 --from <location> 的 backup list、backup verify 和 backup restore 不需要或更改声明。不带 --namespace 的列表还会显示可用命名空间及其声明主机名。恢复的安装会保留其原始设备身份，并可以继续其命名空间。并发运行的克隆副本会共享该身份，并且必须使用自己的 --namespace 以避免共享保留。

备份状态和 Doctor 会为每种备份类型和目标保留最新一次尝试和最新一次成功结果，同时保留最新的 200 条全局尝试记录。繁忙的任务不会隐藏低频目标的上一次结果。有关命令和状态详情，请参阅备份和备份 CLI。

诊断位置¶

openclaw storage list 会探测已配置的位置。openclaw storage test <name> 还会在位置根目录写入一个临时 .openclaw-probe-<uuid> 对象，读取并验证它，然后删除它。所有存储命令都支持 --json；请参阅 CLI 参考。

状态	下一步
`ok`	标记和加密身份有效，并且后端探测成功。
`unavailable`	重新连接磁盘或恢复对已配置目标的访问权限。检查 CLI 和 Gateway 是否看到相同的路径和凭据。
`uninitialized`	确认这是预期的新目标，然后运行 `openclaw storage init <name>`。切勿初始化意外的空挂载点。
`wrong-key`	恢复原始密码短语或更正 SecretRef。不要替换标记以隐藏不匹配。
`error`	阅读返回的消息，并更正提供商设置、权限或报告的后端故障。

Gateway 客户端可以使用 storage.locations.list 列出已配置的位置，而无需进行存储 I/O，并可以使用 storage.locations.probe { name } 请求健康检查。两者都需要 operator read 权限范围。初始化仍然是显式的 CLI 操作。

请参阅配置参考了解其他配置域，并参阅密钥了解密钥提供商设置。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

存储位置¶

配置并初始化目录¶

配置参考¶

审慎选择加密¶

跨安装共享位置¶

诊断位置¶