跳转至

备份

OpenClaw 将其权威状态存储在 SQLite 中：状态目录（通常为 ~/.openclaw）下有一个全局控制平面数据库，另外每个已配置代理在 <agentDir>/openclaw-agent.sqlite 各有一个数据库。代理目录默认位于状态目录下，但也可以配置到状态目录之外。有关确切布局，请参阅 数据库模式。本指南介绍如何保护该状态：一次性归档、按数据库快照、计划任务、异地副本，以及为那些不应在每次备份时重新上传整个数据库的安装提供持续复制。

启用 冷会话记录存储 后，较旧的会话记录负载也会以不可变的压缩文件形式存在。请使用 OpenClaw 备份命令将这些负载与数据库一并捕获。

切勿将正在使用的 .sqlite、-wal、-shm 或 -journal 文件复制为备份。数据库在 Gateway 运行期间会被写入，对活动数据库的原始文件复制可能被撕裂或损坏。下文所有受支持的路径都能安全地捕获已提交状态。

Warning

备份包含认证配置文件、渠道和提供方凭据、会话历史以及其他敏感记录。请以加密方式存储它们，像限制活动状态目录一样限制备份目的地，若怀疑备份泄露请轮换凭据。有关适用于机器迁移的相同规则，请参阅 在机器之间迁移。

选择路径

  • 一次性状态和工作区归档：openclaw backup create。
  • 单个数据库，紧凑且经过验证：openclaw backup sqlite create。
  • 按内容进行版本化和增量备份：openclaw backup git create。
  • 定期保护：配置 Gateway 自有的备份自动化。
  • 持续、增量式，最多丢失数秒数据：使用 Litestream 复制数据库。
  • 定期增量拉取到另一台机器，无需对象存储：sqlite3_rsync。

完整归档

绝对符号链接会保留其原始目标位置，包括指向单独备份的配置或凭据的链接。在另一台主机或另一路径上激活状态之前，请审查这些链接；参阅 备份符号链接注意事项。

openclaw backup create --output ~/Backups/openclaw --verify

这将写入一个带时间戳的 .tar.gz，涵盖状态、配置、凭据、每个已配置的代理目录，以及（默认情况下）工作区，然后验证归档清单和负载。即使设置了 --no-include-workspace，代理目录仍会被包含，即使它们的配置位置位于状态目录之外。OpenClaw 拥有的 SQLite 数据库（包括工作区内或受管状态资产中的代理数据库）会通过 SQLite 的在线备份 API 捕获，并经过所有者验证、净化和压缩。工作区中的其他 SQLite 文件仍作为普通工作区文件处理。备份 CLI 文档说明了每个标志、所有者声明的可再生成资源、易变文件以及验证细节。

如果配置格式不正确，状态归档创建将失败，因为无法解析代理和插件所有权。--no-include-workspace 仅排除工作区文件；它不会绕过所有权发现。在修复配置之前，请先保存当前生效的配置文件：

openclaw backup create --only-config --output ~/Backups/openclaw --verify

这只保存当前生效的 JSON 配置文件，不解析它，也不包含其 $include 依赖。修复配置后，重新运行上面的完整归档命令，以保护状态、凭据、代理和工作区。

归档是完整副本：每次运行都会重新上传所有内容。它们适合在更新、重置、卸载或迁移机器之前使用，也是小型安装的合理日常例行操作。对于大型工作区或频繁备份，请优先选择下面的快照或持续复制。

在临时容器主机上，请将归档保存在容器之外，并使用 openclaw backup restore 作为重建全新持久状态树的灾难恢复原语。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/ 目录。嵌入的压缩负载会增加备份字节数，并可能使备份大于活动数据库；不过压缩（compaction）仍可能使整体更小。完整归档也可能在自包含数据库快照之外，同时包含保留的不可变文件。

恢复后，压缩负载最初仍保留在 SQLite 中。如果启用了冷存储，后台工作器会先发布并验证其归档文件，然后才释放嵌入的数据库字节。在整个转换过程中，恢复后的历史记录始终保持可用。设置界面会区分嵌入式归档字节（计入数据库大小）与归档文件字节，并报告有多少嵌入式归档已移回文件。

Litestream 和 sqlite3_rsync 仅复制数据库字节，不执行此嵌入步骤。如果仍有任何文件型冷归档残留，即使自动归档已禁用，也要捕获每个代理会话工件目录下的不可变 cold/ 目录。先捕获数据库，再捕获文件，并保留该数据库快照引用的每个文件。缺少所引用冷文件的数据库副本是不完整的。当你需要可移植的恢复工件时，请优先使用受支持的 OpenClaw 快照命令。

调度备份

推荐的调度方式是 Gateway 拥有一个自动化任务。此示例每天备份共享数据库和所有已配置的代理数据库（包括自定义代理根目录），并将当前分支推送到 origin。推送要求仓库先配置 origin 远程，因此在启用推送调度前需先初始化一次：

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

backup enable --push 在未配置 origin 远程时会拒绝调度，因此全新安装不会在静默中创建推送总是失败的调度。

推送调度默认会编辑（redact）含凭据的表和以 secret 为前缀的机器状态行：否则无人值守的定期推送会将凭据持久保留在远程 Git 历史中。当你接受这种权衡且远程为私有时，可传入 --include-secrets 来调度全保真远程备份；从已编辑历史恢复后需要重新配对设备并重新认证各提供方。本地（非推送）调度保持完整保真，因此恢复是完整的。

使用 --global-only 或 --agent <id> 来缩小范围。添加 --exclude-secrets 以获得编辑过的 Git 历史。重新运行该命令会更新固定调度作业，而不是创建另一个作业。使用以下命令禁用它：

openclaw backup disable

启用或禁用调度时，Gateway 必须可达。没有本地备用调度器。

作为替代方案，也可以直接使用你的平台调度器。以下是一个夜间 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 status 显示最新尝试，openclaw doctor 在未记录到成功运行或最新成功超过 14 天时建议进行一次性或定期备份。

异地复制备份

归档和快照仓库都是普通文件，因此任何同步工具都可以使用。以下是一个针对 S3 兼容存储桶的 rclone 示例：

rclone sync ~/Backups/openclaw-sqlite remote:openclaw-backups/sqlite

由于每个归档和本地快照都是完整副本，异地同步会完整重新上传每个新备份。诸如 restic 之类的去重备份工具可减少目标端的存储占用，但仍会将完整快照作为输入读取。当每次备份的上传大小很重要时，请使用 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 运行会在删除过时的备份拥有条目之前验证每个现有代理作用域。

仓库根目录必须由当前用户拥有，且不得对组或其他用户可写。这会在初始化时和每次创建时检查。在 POSIX 系统上，请确认所有权并运行 chmod 700 <repository> 以修复不安全的权限。

该仓库是普通 Git 仓库，可以使用任何远程，包括 GitHub。请保持远程私有：默认导出包含认证配置文件、令牌和其他含凭据的状态。当编辑后的历史比包含完整凭据的备份更有用时，--exclude-secrets 会省略文档中说明的 secret 表和机器状态键前缀；确切列表请参阅 Backup 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 完整性以及外键。

使用 Litestream 持续复制

Litestream 是一个面向 SQLite 的开源复制守护进程。它与 Gateway 并行运行，无需对 OpenClaw 做任何改动：它会监视每个数据库的预写日志，并将增量更改流式传输到对象存储，同时定期生成快照，使恢复保持快速。只有变更过的页面才会离开机器，因此在备份不能重新上传整个数据库时，它是合适的工具。

Litestream 的一个硬性要求是 WAL 模式。OpenClaw 在本地文件系统上使用 WAL 模式；而在 NFS 或 SMB 等网络存储上，OpenClaw 会回退到回滚日志模式，因此请先用 PRAGMA journal_mode; 验证。下面是一个最小的 litestream.yml 示例，用于将控制平面数据库和一个智能体数据库复制到兼容 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，为你关心的每个数据库各配置一个条目。恢复时，将数据恢复到全新路径，并在离线状态下激活它：

litestream restore -o ./restored-openclaw.sqlite s3://openclaw-backups/state

对于使用自定义 agentDir 的智能体，请将示例中的默认智能体数据库路径替换为其配置的 <agentDir>/openclaw-agent.sqlite。

Litestream 仅复制数据库字节。配置文件、凭据文件和工作区仍然需要上述基于文件的路径之一，而且复制出来的数据与归档文件一样敏感，因此请应用相同的存储桶访问和加密规则。

使用 sqlite3_rsync 进行拉取复制

sqlite3_rsync 是 SQLite 项目官方的复制工具，以 rsync 为模型：它会比较源数据库与副本数据库之间的页面哈希，并且只传输变更过的页面，通常通过 SSH 在两端的相同二进制文件之间进行。与原始文件复制不同，它会在源端获取一个读事务，因此在 Gateway 运行时从活动数据库拉取能够生成一致的副本。源端必须使用 WAL 模式。OpenClaw 在本地文件系统上使用 WAL，但在 NFS 或 SMB 等网络存储上会刻意回退到回滚日志模式，因此在依赖此路径前请先检查源端：

sqlite3 ~/.openclaw/state/openclaw.sqlite "PRAGMA journal_mode;"

如果输出不是 wal，请改用上面的某个基于文件的路径。

该工具随 SQLite 下载页面 上的 sqlite-tools 二进制包以及完整源码树一起发布；包管理器提供的 SQLite 构建往往不包含它。将数据库拉取到你所控制的另一台机器：

sqlite3_rsync 'user@gateway-host:~/.openclaw/state/openclaw.sqlite' ./replica/openclaw.sqlite

重新运行该命令是增量的：未变更的数据库只需交换几十千字节的哈希，新增数据则以接近其自身大小的量传输。请将副本视为只读，并像对待源端一样敏感地对待它。

有两点需要注意。首先，增量是基于页面的，而 OpenClaw 的数据库会按周期性的维护定时器运行增量自动清理；一次清理会重定位页面，因此在清理之后不久（或在大量删除之后，例如转录归档逐出）进行同步，可能会传输远比实际数据变化多得多的内容。其次，与 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

目标目录必须不存在或必须为空，并且不能位于活动状态目录或任何已配置的活动智能体目录内。OpenClaw 在写入目标之前，会验证归档结构、清单、硬链接、符号链接条目、根 SQLite 快照及其持久注册的智能体快照。其他载荷保持不透明。非空目标会被拒绝，提取失败时会清理其不完整的输出。该命令绝不会写入活动状态或智能体根目录，也没有强制或就地模式。请将恢复出来的目录视为敏感内容：其中可能包含凭据、认证配置文件、会话和工作区数据。

Warning

恢复归档就像时间旅行。带有棘轮状态的消息通道凭据，尤其是 WhatsApp，在回滚后可能会失步并需要重新关联。审批以及投递/去重状态也会回滚，因此恢复 Gateway 之前请审查待处理的审批。插件的 node_modules 目录树不会被归档；激活后，请运行 openclaw plugins update <id>，或使用 openclaw plugins install <spec> --force 重新安装。运行 openclaw skills list 或启动一个智能体会话，以根据当前插件元数据重新生成被省略的 plugin-skills/ 符号链接索引。

schema-version-1 清单记录了 archiveRoot、paths 下的原始路径、assets[] 列表，以及增量式已配置代理所有权元数据。 每个资产包含其 kind、原始 sourcePath，以及 tarball 内的 archivePath。 当外部自定义代理根需要自己的源时，其 kind 为 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 以及任何使用已恢复文件的节点主机。 为当前状态创建新的备份，或将其移开。 然后将提取出的状态资产移动到指定位置，或将 OPENCLAW_STATE_DIR 指向该资产。 使用其记录的代理 ID 和原始源路径恢复每个自定义代理根； 保留其已配置的 agentDir，或将该设置更新为其新位置。 在新机器上或不同的主目录下，还请使用清单将配置、凭据和工作区资产映射到其新路径。 在重启 Gateway 之前运行 openclaw doctor。 回滚工作流参见 更新。

恢复数据库

对于快照，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 对数据库进行预检； 参见 数据库架构。

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