Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw backup
为 OpenClaw 状态、配置、身份验证配置文件、渠道/提供商凭证、会话以及可选的工作区创建本地备份归档文件。
注意事项
- 归档文件包含一个
manifest.json文件，其中记录了解析后的源路径和归档布局。 - 默认输出是在当前工作目录中带时间戳的
.tar.gz归档文件。 - 如果当前工作目录位于已备份的源树内，OpenClaw 会回退到你的主目录作为默认归档位置。
- 现有归档文件永远不会被覆盖。
- 位于源状态/工作区树内部的输出路径会被拒绝，以避免自包含。
openclaw backup verify <archive>会验证归档文件仅包含一个根清单，拒绝遍历式归档路径，并检查清单声明的每个载荷是否都存在于 tarball 中。openclaw backup create --verify会在写入归档文件后立即运行该验证。openclaw backup create --only-config只备份当前活动的 JSON 配置文件。
会备份哪些内容
openclaw backup create 会根据你的本地 OpenClaw 安装规划备份源：
- OpenClaw 本地状态解析器返回的状态目录，通常是
~/.openclaw - 当前活动的配置文件路径
- 当解析出的
credentials/目录存在于状态目录外部时，会包含该目录 - 从当前配置中发现的工作区目录，除非你传入
--no-include-workspace
agents/<agentId>/agent/auth-profiles.json 下，因此它们通常会被状态备份条目覆盖。
如果你使用 --only-config，OpenClaw 会跳过状态、凭证目录和工作区发现，只归档当前活动的配置文件路径。
OpenClaw 会在构建归档文件前对路径进行规范化。如果配置、凭证目录或工作区已经位于状态目录内部，它们不会作为单独的顶级备份源重复包含。缺失的路径会被跳过。
归档载荷会存储这些源树中的文件内容，嵌入的 manifest.json 会记录解析后的绝对源路径，以及每个资产使用的归档布局。
在创建归档文件期间，OpenClaw 会跳过已知的实时变更文件，因为它们没有恢复价值，包括活动 Agent 会话转录、cron 运行日志、滚动日志、投递队列、状态目录下的 socket/pid/临时文件，以及相关持久队列临时文件。JSON 结果包含 skippedVolatileCount，以便自动化流程查看有多少文件被有意省略。
状态目录的 extensions/ 树下已安装的插件源文件和清单文件会被包含，但其嵌套的 node_modules/ 依赖树会被跳过。这些依赖是可重建的安装产物；恢复归档文件后，如果恢复的插件报告缺少依赖，请使用 openclaw plugins update <id>，或通过 openclaw plugins install <spec> --force 重新安装该插件。
无效配置行为
openclaw backup 会有意绕过常规配置预检，以便在恢复期间仍能提供帮助。由于工作区发现依赖有效配置，当配置文件存在但无效且仍启用工作区备份时，openclaw backup create 现在会快速失败。
如果你在这种情况下仍想进行部分备份，请重新运行：
--only-config 也可以在配置格式错误时工作，因为它不依赖解析配置来发现工作区。
大小和性能
OpenClaw 不会强制执行内置的最大备份大小或单文件大小限制。 实际限制来自本地机器和目标文件系统：- 临时归档写入和最终归档所需的可用空间
- 遍历大型工作区树并将其压缩为
.tar.gz所需的时间 - 如果你使用
openclaw backup create --verify或运行openclaw backup verify，重新扫描归档文件所需的时间 - 目标路径处的文件系统行为。OpenClaw 优先使用不覆盖的硬链接发布步骤，并在不支持硬链接时回退到独占复制
--no-include-workspace。
若要获得最小的归档文件，请使用 --only-config。