备份
OpenClaw 将其权威状态保存在 SQLite 中:在状态目录(通常是 ~/.openclaw)下有一个全局控制面数据库,另外每个已配置代理在 <agentDir>/openclaw-agent.sqlite 各有一个数据库。代理目录默认位于状态目录之下,但也可以配置到状态目录之外。确切的布局参见数据库模式。本指南介绍如何保护这些状态:一次性归档、按数据库快照、调度、异地副本,以及为不应在每次备份时重新上传整个数据库的安装提供持续复制。
当启用冷转录存储时,较旧的转录负载也保存在不可变的压缩文件中。请使用 OpenClaw 备份命令将这些负载与数据库一起捕获。
切勿将正在使用的 .sqlite、-wal、-shm 或 -journal 文件复制为备份。数据库在 Gateway 运行期间会被写入,对活动数据库的原始文件复制可能被撕裂或损坏。下文每条受支持的路径都能安全捕获已提交状态。
SQLite 快照(包括 Doctor 的迁移前备份以及重试时复用的备份)无需加载原生 sqlite-vec 扩展即可保留向量内存表。因此,备份创建可以在不支持 AVX 的老款 Intel CPU 上正常工作。向量搜索仍需要兼容的扩展;在这些主机上,请在不启用 AVX 的情况下构建 sqlite-vec,并将 memory.search.store.vector.extensionPath 设置为该构建的可加载扩展。
Warning
备份包含认证配置文件、渠道和提供方凭据、会话历史以及其他敏感记录。请加密存储它们,像限制活动状态目录一样限制目标位置;如果怀疑备份泄露,请轮换凭据。适用于机器迁移的相同规则,请参见机器间迁移。
选择路径¶
- 一次性状态与工作区归档:
openclaw backup create。 - 归档到磁盘或对象存储:
openclaw backup create --to <location>。 - 单个数据库,紧凑且经过校验:
openclaw backup sqlite create。 - 按内容进行版本化与增量备份:
openclaw backup git create。 - 常规保护:配置 Gateway 自有的备份自动化功能。
- 持续、增量,数据丢失以秒计:使用 Litestream 复制数据库。
- 定期增量拉取到另一台机器,无需对象存储:
sqlite3_rsync。
完整归档¶
绝对符号链接会保留其原始目标位置,包括指向单独备份的配置或凭据的链接。在另一台主机或另一路径上激活状态之前,请检查这些链接;参见备份符号链接注意事项。
这会写入一个带时间戳的 .tar.gz,涵盖状态、配置、凭据、每个已配置的代理目录,以及(默认情况下)工作区,然后校验归档清单和负载。即使代理目录的配置位置位于状态目录之外,设置 --no-include-workspace 时仍会包含这些目录。OpenClaw 拥有的 SQLite 数据库(包括工作区或托管状态资产中的代理数据库)会通过 SQLite 的在线备份 API 捕获,并经过属主验证、清理和压缩。工作区中的其他 SQLite 文件仍作为普通工作区文件处理。备份 CLI 记录了所有标志、属主声明的可再生成资源、易失文件以及校验细节。
如果配置格式错误,状态归档创建会失败,因为无法解析代理和插件的属主关系。--no-include-workspace 仅排除工作区文件;它不会绕过属主发现。在修复配置之前,先保存当前生效的配置文件:
这只会保存当前生效的 JSON 配置文件,不解析它,也不包含其 $include 依赖。修复配置后,重新运行上面的完整归档命令,以保护状态、凭据、代理和工作区。
归档是完整副本:每次运行都会重新上传所有内容。它们适合在更新、重置、卸载或机器迁移之前使用,对于小型安装也是合理的日常做法。对于大型工作区或频繁备份,请优先使用下面的快照或持续复制。
在临时容器主机上,将归档保存在容器之外,并使用 openclaw backup restore 作为灾难恢复原语,重建全新的持久状态树。恢复仅暂存文件;激活仍然是一个明确的离线部署步骤。
按数据库快照¶
openclaw backup sqlite create --global --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqlite
每次运行都会在仓库目录中发布一个经过校验的快照目录(manifest.json 加 database.sqlite)。快照会经过 vacuum 处理,因此已删除页面的残留不会使其膨胀;每个快照都会记录一个 SHA-256,openclaw backup sqlite verify 会在之后重新校验。
--agent <id> 会从该代理配置的 agentDir 解析数据库,包括状态目录之外的根路径。相同的属主派生查找也适用于显式 Git 代理备份、--all 和计划 Git 备份。按代理 ID 校验或恢复历史产物时,并不要求该代理存在于当前配置中。
快照仓库是本地目录。调度、上传、保留和启动时恢复都明确留给操作员处理;下文各节会介绍这些内容。
冷转录备份¶
完整归档、按数据库的 SQLite 快照和 Git 备份都会包含所捕获数据库引用的每个冷转录。发布前,备份属主会读取每个不可变归档,校验其大小和 SHA-256,并将压缩字节嵌入私有快照中。这不会改变活动数据库的存储策略。如果归档缺失或损坏,备份创建将失败,而不会生成一个历史不完整的成功备份。
生成的数据库是自包含的:在另一台机器上恢复它时,不需要源 sessions/cold/ 目录。内嵌压缩负载会增加备份字节数,并可能使备份比活动数据库更大;压实后整体仍可能更小。完整归档也可能在自包含数据库快照旁边保留不可变文件。
恢复后,压缩负载最初仍保留在 SQLite 内部。如果启用了冷存储,后台工作进程会在释放内嵌数据库字节之前,发布并验证其归档文件。在此转换过程中,恢复的历史记录始终保持可用。设置会区分内嵌归档字节(计入数据库大小)和归档文件字节,并报告有多少内嵌归档已移回文件。
Litestream 和 sqlite3_rsync 仅复制数据库字节,不会执行此内嵌步骤。如果仍存在基于文件的冷归档,请同时捕获每个代理会话工件目录下的不可变 cold/ 目录,即使自动归档已禁用。先捕获数据库,再捕获文件,并保留该数据库快照引用的所有文件。缺少所引用冷文件的数据库副本是不完整的。当需要一个可移植的恢复工件时,请优先使用受支持的 OpenClaw 快照命令。
计划备份¶
在配置并初始化存储位置后,启用由 Gateway 拥有的每日归档备份:
Gateway 会使用存储位置的加密设置创建、验证并上传每个归档。添加 --no-include-workspace 以省略工作区文件,或使用 --namespace <name> 代替清理后的主机名使用稳定命名空间。确保存储位置的凭据和加密口令对 Gateway 进程可用。保留策略是可选的;如果没有任何 --keep-* 标志,备份永远不会被清理。参见保留规则。
每个命名空间属于首次上传到该命名空间的安装。若要有意接管现有命名空间,请将 --claim-namespace 传递给 backup enable --to。计划仅在显式传递时保留此标志;其运行随后可以替换现有的所有权声明。对于仍在运行的不同安装,请优先使用单独的 --namespace。
若要在 Git 中保留增量数据库历史,请初始化一个私有仓库,并改为启用 Git 计划。这会备份共享数据库和每个已配置的代理数据库,包括自定义代理根目录:
openclaw backup git init --repository ~/Backups/openclaw-git --remote git@github.com:you/openclaw-backups.git
openclaw backup enable --repository ~/Backups/openclaw-git --every 24h --push
当未配置 origin 远程时,backup enable --push 会拒绝创建计划,因此全新安装不会静默创建一个推送始终失败的计划。
推送计划默认会脱敏包含凭据的表和以 secret 前缀开头的机器状态行:否则无人值守的定期推送会将凭据持久保留在远程 Git 历史中。当你接受该权衡且远程为私有仓库时,传递 --include-secrets 以计划完整保真度的远程备份;从已脱敏历史恢复后,需要重新配对设备并重新认证提供商。本地(非推送)计划保持完整保真度,因此恢复是完整的。
使用 --global-only 或 --agent <id> 缩小 Git 范围。添加 --exclude-secrets 以获得脱敏的 Git 历史。
每种模式有一个受管作业:异地归档和 Git 备份可以一起运行。重新运行 backup enable 会更新所选模式的作业,包括其目标位置。现有 Git 计划仍会被识别。间隔默认为 24h。禁用一种模式或两种模式:
启用或禁用需要可访问的本地 Gateway,因为作业在 Gateway 主机上运行。没有本地回退调度器。对于远程 Gateway,请在那台主机上显式使用 openclaw cron add 创建作业。
作为替代方案,直接使用平台调度器。一个夜间 cron 示例,用于快照控制平面数据库和 main 代理数据库:
0 3 * * * openclaw backup sqlite create --global --repository "$HOME/Backups/openclaw-sqlite" --json >> "$HOME/Backups/openclaw-backup.log" 2>&1
5 3 * * * openclaw backup sqlite create --agent main --repository "$HOME/Backups/openclaw-sqlite" --json >> "$HOME/Backups/openclaw-backup.log" 2>&1
在 macOS 上,launchd 作业以相同方式工作;在根据托管指南配置的主机上,systemd 定时器是自然选择。--json 每次运行输出一个机器可读结果,因此日志同时充当备份审计跟踪。按你自己的保留计划清理旧快照目录。
每次非演练归档、本地 SQLite 快照和 Git 备份尝试也会记录在共享状态数据库中。主机级作业可以使用 openclaw backup record 报告其结果;参见外部备份作业。
openclaw status 显示最新的备份尝试和异地结果。Control UI 在 Systems 落地页和 Gateway 主机视图中的备份部分会显示每个目标的最后成功、大小、目标位置、最新失败和下次计划运行。其存储位置的 检查 操作会在不写入备份的情况下检查访问权限。openclaw doctor 保留 14 天新鲜度提示,并在异地计划尝试失败后,或其最后成功时间早于三个计划间隔时,标记该异地计划。使用 openclaw storage test <name> 诊断该目标位置。
记录的历史会保留最新的 200 次尝试,以及每种备份类型和目标的最新尝试和最新成功结果。Status 和 Doctor 会保留不常用目标位置的最后结果,即使另一个作业产生了超过 200 个更新的结果。
将备份复制到异地¶
为外部磁盘、已挂载的网络目录或插件提供的对象存储使用一个命名的存储位置。内置的
filesystem 提供者使用现有目录;Cloudflare 插件 提供 R2 存储。先配置
该位置及其加密,然后显式初始化目标位置:
备份命令在创建归档前会检查该位置,在本地验证 归档,上传它,并确认其存储大小。如果缺少 初始化标记,备份会被拒绝:重新连接磁盘或检查存储桶 和前缀,或者仅当该位置是新的时才初始化 该位置。运行时备份永远不会初始化位置 或创建缺失的文件系统根目录。参见存储 CLI。
默认情况下,本地归档只存在于受管理的临时空间中,并在
上传后被删除。添加 --output ~/Backups/openclaw 以保留本地
副本。即使存储
位置对上传的字节进行加密,本地副本也是明文 .tar.gz 归档;请相应地保护两个目标位置。
备份存储在 backups/<namespace>/ 下,其中命名空间默认
为清理后的主机名。对于共享同一目标位置的每个安装,
请使用不同的显式命名空间:
openclaw backup create --to offsite --namespace gateway --keep-daily 7 --keep-weekly 4 --keep-monthly 12
openclaw backup list --from offsite --namespace gateway
openclaw backup verify --from offsite --namespace gateway latest
openclaw backup restore --from offsite --namespace gateway latest --target ./restored-openclaw
首次上传会为安装持久的 Gateway
设备身份认领该命名空间。其 owner.json 包含设备 ID、主机名和认领
时间,并使用该位置的加密设置。OpenClaw 会在归档前、归档发布时以及每次保留删除前检查所有权。
不同的设备身份会导致尝试失败,并显示所有者的主机名和缩写设备 ID,即使
两台机器使用相同的主机名也是如此。
为单独的安装选择另一个 --namespace。若要有意接管
已停止或已退役安装的命名空间,例如迁移到
新硬件之后,请运行:
被替换的安装在其下次发布或删除时会被拒绝。 对象存储无法使对象的写入以单独的所有权 认领为条件,因此在最终检查 和实际效果之间仍然存在一个残留的提供者往返窗口。在接管之前停止旧安装;对于并发运行的安装,请使用单独的 命名空间。
保留策略仅在上传成功后运行。它会保留每个所选 UTC 日、周或月中最新的备份,
合并各项策略,并始终
保留最新备份。它永远不会删除其他命名空间或对象
键不匹配备份文件名模式的对象,包括 owner.json。
没有保留标志意味着
不删除;确切规则参见备份 CLI。
远程验证和恢复会下载并解密到受管理的临时空间,
然后使用与本地文件相同的归档检查。恢复仍然会暂存到
新的目标位置;在
激活结果之前,请遵循恢复完整归档。在另一台主机上恢复时,请指定原始
命名空间,并保留原始加密口令和位置标记。
不带 --namespace 的 backup list --from offsite 还会列出可用
命名空间及其认领主机名,以便找到原始数据。
列出、验证和恢复从不要求或更改命名空间所有权。
恢复后的安装会携带原始设备身份,并可以继续
使用其命名空间。并发运行的克隆副本会共享该身份;
请为其指定自己的 --namespace,以便两个副本不共享保留策略。
每个归档都是完整副本。对于上传大小很重要的大型安装, 请使用基于 Git 的快照或持续复制。普通本地归档和 快照仓库仍然是外部备份工具可以复制的普通文件。
版本化备份到 Git 仓库¶
基于 Git 的备份会将每个选定的数据库转储为确定性的 schema.sql、
manifest.json 和按表划分的 JSONL 文件,然后为
整个运行创建一个提交。未更改的数据库内容不会产生提交,因此 Git 从结构上只存储和
推送内容变更。OpenClaw 只暂存
备份拥有的 global 和 agents 路径,而不是仓库中其他位置的不相关文件。
openclaw backup git init --repository ~/Backups/openclaw-git --remote <private-git-url>
openclaw backup git create --repository ~/Backups/openclaw-git --all --push
openclaw backup git log --repository ~/Backups/openclaw-git
请使用专门用于 OpenClaw 备份的仓库。现有的 global/ 和
agents/<agentId>/ 作用域必须为空,或包含有效的 schema-version-1
OpenClaw 备份清单。OpenClaw 拒绝替换任何其他作用域,并且
--all 运行会在删除过期的
备份拥有条目之前验证每个现有代理作用域。
仓库根目录必须由当前用户拥有,并且不得对组或
所有用户可写。这会在 init 和每次 create 期间检查。在 POSIX 系统上,
请确认所有权并运行 chmod 700 <repository> 以修复不安全的权限。
该仓库是普通 Git 仓库,可以使用任何远程仓库,包括 GitHub。请保持
远程仓库私有:默认转储包含身份验证配置文件、令牌和其他
包含凭据的状态。当脱敏历史比包含完整凭据的备份更有用时,--exclude-secrets 会省略文档中记录的机密
表和机器状态键前缀;确切列表参见
备份 CLI。
在任何提交处验证或恢复单个数据库,而不会覆盖活动文件:
openclaw backup git verify --repository ~/Backups/openclaw-git --ref <commit> --global
openclaw backup git restore --repository ~/Backups/openclaw-git --ref <commit> --agent main --target ./restored-agent.sqlite
Git 恢复会收敛派生搜索状态:它会重建基于内容的 FTS5 索引,保留转录投影状态供 Gateway 启动时对账,并保留向量表供内存索引重新创建。然后它会验证表哈希、SQLite 完整性和外键。
触发器主体可以包含 CASE 表达式和 SQL 注释。不完整的触发器定义会在目标文件发布之前使恢复失败。
使用 Litestream 进行持续复制¶
Litestream 是一个用于 SQLite 的开源复制守护程序。它与 Gateway 并行运行,无需修改 OpenClaw:它监视每个数据库的预写日志,并将增量变更流式传输到对象存储,同时定期创建快照,以便恢复保持快速。只有已更改的页会离开机器,因此当备份不能重新上传整个数据库时,它是合适的工具。
Litestream 的唯一硬性要求是 WAL 模式,OpenClaw 在本地文件系统上使用它;在 NFS 或 SMB 等网络支持存储上,OpenClaw 会回退到回滚日志,因此请先使用 PRAGMA journal_mode; 验证。
一个最小的 litestream.yml,将控制平面数据库和一个 agent 数据库复制到 S3 兼容存储桶:
dbs:
- path: /home/user/.openclaw/state/openclaw.sqlite
replicas:
- url: s3://openclaw-backups/state
- path: /home/user/.openclaw/agents/main/agent/openclaw-agent.sqlite
replicas:
- url: s3://openclaw-backups/agents/main
在进程管理器下运行 litestream replicate,每个你关心的数据库一个条目。要恢复时,恢复到新路径并离线激活它:
对于具有自定义 agentDir 的 agent,请将示例中的默认 agent 数据库路径替换为其配置的 <agentDir>/openclaw-agent.sqlite。
Litestream 仅复制数据库字节。配置、凭据文件和工作区仍需要上述基于文件的路径之一,并且复制的数据与归档一样敏感,因此应用相同的存储桶访问和加密规则。
使用 sqlite3_rsync 进行拉取复制¶
sqlite3_rsync 是 SQLite 项目的官方复制工具,以 rsync 为模型:它比较源数据库和副本数据库之间的页哈希,并仅传输已更改的页,通常通过 SSH 进行,且两端安装相同的二进制文件。与原始文件复制不同,它会在源端获取读事务,因此在 Gateway 运行时从活动数据库拉取会产生一致的副本。源端要求 WAL 模式。OpenClaw 在本地文件系统上使用 WAL,但在 NFS 或 SMB 等网络支持存储上会故意回退到回滚日志,因此在依赖此路径之前请检查源端:
如果它输出任何非 wal 的值,请改用上述基于文件的路径之一。
该工具随 SQLite 下载页面 上的 sqlite-tools 二进制包以及完整源码树一起提供;包管理器提供的 SQLite 构建通常不包含它。将数据库拉取到你控制的另一台机器:
重新运行该命令是增量的:未更改的数据库仅交换几 KB 的哈希,追加数据大约按其自身大小传输。将副本视为只读,并像源端一样敏感。
两个注意事项。首先,增量基于页,并且 OpenClaw 的数据库会在周期性维护定时器上运行增量自动 VACUUM;VACUUM 过程会重新定位页,因此在 VACUUM 之后不久(或在大型删除之后,例如转录归档淘汰)同步可能传输远多于实际数据变化的量。其次,与 Litestream 一样,它仅复制数据库字节:配置、凭据文件和工作区仍需要上述基于文件的路径。对于具有可预测上传大小的持续复制,优先使用 Litestream;在没有对象存储的机器之间进行计划性或临时拉取时,使用 sqlite3_rsync。要恢复时,将副本视为任何已恢复的数据库:在 Gateway 停止时将其复制到指定位置,然后按照 恢复数据库 操作。
恢复¶
恢复是有意显式的;不会就地覆盖活动状态。
恢复完整归档¶
仅从你创建或可信任的归档开始。openclaw backup
verify 会检查归档结构和负载布局,但不会验证归档身份,也不会使不受信任的内容变得安全。
在执行完整恢复之前,查看 哪些内容会被备份。然后使用一条命令验证并提取到新的暂存目录:
ARCHIVE=./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz
openclaw backup restore "$ARCHIVE" --target ./restored-openclaw
目标必须不存在或为空,并且不得位于活动状态目录或任何已配置的活动 agent 目录内。OpenClaw 在写入目标之前,会验证归档结构、清单、硬链接、符号链接条目,以及根 SQLite 快照及其持久注册的 agent 快照。其他负载保持不透明。非空目标会被拒绝,失败的提取会清理其不完整输出。该命令从不写入活动状态或 agent 根目录,也没有强制或就地模式。将恢复后的目录视为敏感目录:它可能包含凭据、认证配置、会话和工作区数据。
恢复前,确保目标文件系统有足够空间容纳归档的完整未压缩负载以及提取开销,同时活动目录树仍保留在原位。在同一文件系统上将活动目录树重命名或移动到同级路径不会释放其块;因此完整恢复需要为第二棵目录树预留空间。
Warning
恢复归档相当于时间旅行。带有 ratchet 状态的消息渠道凭据,尤其是 WhatsApp,在回滚后可能失去同步,需要重新关联。审批以及投递/去重状态也会回滚,因此在恢复 Gateway 之前,请检查待处理审批。插件的 node_modules 目录树不会被归档;激活后,运行 openclaw plugins update <id> 或使用 openclaw plugins install <spec> --force 重新安装。运行 openclaw
skills list 或启动一个 agent 会话,以根据当前插件元数据重新生成被省略的 plugin-skills/ 符号链接索引。
schema-version-1 清单记录 archiveRoot、paths 下的原始路径、assets[] 列表,以及增量配置的 agent 所有权元数据。每个资产包含其 kind、原始 sourcePath,以及 tar 包内的 archivePath。当外部自定义 agent 根目录需要自己的源时,其 kind 为 agent;已由 state 或 workspace 资产覆盖的根目录会出现在所有权元数据中,而不会重复归档条目。请以资产和所有权字段作为唯一事实来源;不要从归档文件名推导归档根目录,也不要从默认布局重建 agent 路径。没有增量所有权元数据的旧归档仍然可以验证。
归档布局如下:
<archive-root>/manifest.json
<archive-root>/payload/posix/<absolute-source-path-without-leading-slash>/...
<archive-root>/payload/windows/<DRIVE>/<rest>/...
<archive-root>/payload/relative/<relative-source-path>/...
要激活,请停止 Gateway 以及任何使用已恢复文件的 node 主机。为当前状态创建一份新的备份,或将其移开。然后将提取出的 state 资产移动到指定位置,或将 OPENCLAW_STATE_DIR 指向该资产。使用记录的 agent id 和原始源路径恢复每个自定义 agent 根目录;保留其配置的 agentDir,或将该设置更新为其新位置。在新机器上或不同的主目录下,还请使用清单将配置、凭据和工作区资产映射到它们的新路径。在重启 Gateway 之前,运行 openclaw doctor。有关回滚工作流,请参阅 更新。
选择性提取原始 tar 成员是一种面向专家的离线最后手段,适用于完整分阶段恢复无法容纳的情况,并非推荐的恢复路径。它会绕过 restore 命令的完整布局和清理保护。请保持原始归档不变,先对其进行验证,停止所有写入者,并使用 manifest.json 确认每个所选成员的准确资产路径和 agent 所有权。从同一备份代中恢复配置、共享数据库以及所有必需的按 agent 划分的数据库。仅从归档的受管快照中提取 SQLite 成员;切勿将数据库与来自另一代的 -wal、-shm 或 -journal 文件组合使用。尽可能优先将恢复目标设置为具有足够空间容纳完整归档的存储。
恢复数据库¶
对于快照,openclaw backup sqlite restore <snapshot-directory> --target
<new-database-path> 会将重新验证的数据库写入新的目标。对于 Git 历史,openclaw backup git restore --repository <dir> --ref <commit>
(--global | --agent <id>) --target <new-database-path> 会生成并验证一个全新的数据库。对于 Litestream,litestream restore 会写入一个全新的数据库文件。在 Gateway 停止时,将结果移动到指定位置,然后启动 Gateway 并检查 openclaw health 和 openclaw doctor。
在恢复到不同的 OpenClaw 版本后,请先使用 openclaw database preflight 对数据库进行预检;请参阅 数据库架构。
相关¶
- Agent 工作区 用于将工作区文件保存在私有 git 仓库中
- 备份 CLI 参考
- Cloudflare Containers — 面向临时容器部署,持续将 Litestream 复制到 R2
- Cloudflare 插件 — 用于归档备份的 R2 存储位置
- 数据库架构
- 在机器之间迁移
- 存储位置
- 更新
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw