存储位置¶
存储位置为 OpenClaw 工件指定了一个目标位置。核心存储负责位置身份、加密和健康检查。提供者(Providers)负责传输对象,而每个消费者决定存储和保留哪些内容。配置位置不会安排备份或移动现有数据。
内置的 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.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 会拒绝备份并记录一次失败的尝试,从而防止主机名冲突导致共享保留策略。保留操作绝不会删除该声明。
将 --claim-namespace 传递给 backup create --to <location> 以有意接管一个命名空间,例如在迁移到新硬件之后。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 } 请求健康检查。两者都需要操作员读取权限。初始化仍然是显式的 CLI 操作。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw