openclaw backup

为 OpenClaw 的状态、配置、凭据、会话以及可选的工作区创建本地备份归档。

在重装或重置之前，先用这个命令给你的龙虾做个备份，以防万一。

openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz

注意事项

• 归档包含一个 manifest.json 文件，记录已解析的来源路径和归档布局。
• 默认输出是当前工作目录中以时间戳命名的 .tar.gz 归档。
• 如果当前工作目录位于某个已备份的来源树内，OpenClaw 会将默认归档位置回退到你的主目录。
• 现有归档文件不会被覆盖。
• 位于来源 state/workspace 树内的输出路径会被拒绝，以避免自我包含。
• openclaw backup verify <archive> 验证归档中恰好包含一个根 manifest，拒绝遍历式归档路径，并检查 manifest 中声明的每个负载都存在于 tarball 中。
• openclaw backup create --verify 在写入归档后立即运行该验证。
• openclaw backup create --only-config 仅备份活跃的 JSON 配置文件。

备份内容

openclaw backup create 从你的本地 OpenClaw 安装中规划备份来源：

• OpenClaw 本地状态解析器返回的状态目录，通常为 ~/.openclaw
• 活跃的配置文件路径
• OAuth / 凭据目录
• 从当前配置中发现的工作区目录（除非传入 --no-include-workspace）

如果使用 --only-config，OpenClaw 会跳过 state、凭据和工作区发现，只归档活跃的配置文件路径。

OpenClaw 在构建归档前会规范化路径。如果 config、凭据或工作区已经位于 state 目录内，它们不会作为单独的顶级备份来源重复出现。缺失的路径会被跳过。

归档负载存储这些来源树的文件内容，嵌入的 manifest.json 记录每个资产所使用的已解析绝对来源路径和归档布局。

配置无效时的行为

openclaw backup 有意绕过正常的配置预检，以便在恢复期间仍能提供帮助。由于工作区发现依赖有效配置，当配置文件存在但无效且仍启用工作区备份时，openclaw backup create 会快速失败。

如果你仍想在这种情况下进行部分备份，请重新运行：

openclaw backup create --no-include-workspace

这会保留 state、config 和凭据的备份范围，同时完全跳过工作区发现。

如果只需要配置文件本身的副本，--only-config 在配置格式错误时也有效，因为它不依赖解析配置来进行工作区发现。

大小与性能

OpenClaw 不强制内置的最大备份大小或单文件大小限制。

实际限制来自本地机器和目标文件系统：

• 临时归档写入加最终归档所需的可用空间
• 遍历大型工作区树并压缩为 .tar.gz 的时间
• 使用 openclaw backup create --verify 或运行 openclaw backup verify 时重新扫描归档的时间
• 目标路径处的文件系统行为。OpenClaw 优先使用无覆盖的硬链接发布步骤，当硬链接不支持时回退到独占复制

大型工作区通常是归档大小的主要驱动因素。如果你想要更小或更快的备份，请使用 --no-include-workspace。

若要最小归档，使用 --only-config。