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-09T08-00-00.000+08-00-openclaw-backup.tar.gz
openclaw backup restore ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz --target ./restored-openclaw
openclaw backup sqlite create --global --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite list --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id>
openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id> --scratch ~/Private/openclaw-scratch
openclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqlite
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 backup git verify --repository ~/Backups/openclaw-git --global
openclaw backup git restore --repository ~/Backups/openclaw-git --agent main --target ./restored/agent.sqlite
openclaw backup enable --repository ~/Backups/openclaw-git --every 24h --push
openclaw backup disable

归档的 create、verify、restore，以及 SQLite 的 create、list、verify、restore 命令都接受 --json，用于在 stdout 上输出单条机器可读结果。

备注¶

• 归档中嵌入了 schema-version-1 的 manifest.json，其中包含解析后的源路径和归档布局。附加式归属元数据记录已配置的 agent id 和根路径，包括已被其他资产覆盖的 agent 根路径；现有归档布局和旧版归档仍受支持。新归档还会记录创建时捕获的权威 SQLite 快照；独立验证会拒绝缺失或不匹配的清单条目。没有此清单的旧版归档仍可读取，但验证会报告 sqliteInventoryVerified: false，因为无法确立完整的数据库覆盖范围。空清单表示没有捕获任何权威数据库（例如仅导出配置），并不代表完整的数据库恢复点。
• 默认输出为当前工作目录下带时间戳的 .tar.gz 归档文件。带时间戳的文件名使用本机本地时区，并包含 UTC 偏移量。如果当前工作目录位于某个被备份的源目录树内，OpenClaw 将回退到你的主目录作为默认归档位置。
• 现有归档文件永远不会被覆盖。位于源状态/工作区目录树内的输出路径会被拒绝，以避免自我包含。
• openclaw backup verify <archive> 会检查归档是否恰好包含一个根清单，拒绝路径遍历式归档路径和不安全的符号链接，确认清单声明的每个 payload 都存在，并验证清单中列出或已捕获的持久化注册表中的根 SQLite 快照和 agent 快照。它会拒绝这些快照的 sidecar 文件，并检查其完整性和数据库角色，包括每个 agent 的身份。其他文件（包括创建期间已验证的插件快照）在验证和还原期间仍不会被解析。openclaw backup create --verify 会在写入归档后立即执行该验证。
• 完整归档包含当前生效的配置及其必需的 $include 文件，包括状态目录之外的依赖项。它们保留原始字节、注释和环境占位符；解析后的机密不会写入配置副本。这些额外文件可能包含敏感数据，因此请相应保护归档。
• 名为 ._*.sqlite 的 AppleDouble 元数据（例如 ._cron.sqlite）仅在其文件签名确认为该格式时，才会从状态和 agent 数据库根中排除。使用这些名称的真实 SQLite 文件和硬链接别名遵循与其他数据库相同的归属规则。
• 完整归档会拒绝无法解析的 include 图、配置捕获期间发生变化的文件，以及无法安全表示的 include 别名。请修复缺失或不可读的文件，使用普通文件 include 路径，或暂停并发编辑后重试。--no-include-workspace 仍会包含必需的配置依赖项，即使这些依赖项位于被排除的工作区内。
• openclaw backup create --only-config 仅备份当前生效的 JSON 配置文件，不包含其 $include 依赖项。它是根文件导出，不是完整的模块化配置恢复点。
• 配置文件会在数据库捕获之前被固定（pin）。SQLite 快照保留其已有的逐数据库一致性和清理状态；归档并不是同时覆盖配置和所有数据库的单个原子快照。后续写入仍然生效，并且可能不会出现在归档中。

归档成员位于带时间戳的根目录和 payload/ 之下，源路径编码在其下方。因此，即使 agent 数据库存在，统计以 .openclaw/agents/ 开头的条目也会返回零。请检查根 manifest.json 及其 sqliteSnapshots 清单，然后运行 openclaw backup verify <archive>。被报告为 covered by 另一个资产的路径会通过该父资产包含进来；它并未从归档中排除。

还原完整归档¶

将完整归档还原到一个全新的暂存目录中，而不触碰活跃状态目录：

openclaw backup restore <archive.tar.gz> --target <fresh-directory>

目标路径必须不存在，或者必须是空目录，并且不能位于活跃状态目录或任何已配置的活跃 agent 目录内。还原会在创建或写入目标之前验证归档及其 SQLite 数据库；如果目标非空则拒绝继续，如果任何步骤失败则移除不完整的解压结果。它永远不会就地还原，也没有 --force 模式。解压后的布局会保留归档根目录、清单和 payload/ 路径，与归档中记录的内容完全一致。

激活是一个独立的离线运维步骤。停止 Gateway，将恢复的状态资产移动到指定位置，或将 OPENCLAW_STATE_DIR 指向该资产，然后在重启前运行 openclaw doctor。将 manifest.json 作为状态、配置、凭据、工作区以及已配置代理路径的权威来源。将自定义代理根目录恢复到由 agentDir 配置的位置，或在重启前将这些设置更新为其新位置。完整的灾难恢复流程，请参阅 恢复完整归档。

私有更新捕获¶

受管理的 <stateDir>.update-captures/ 根目录会从普通归档、SQLite 快照、Git 备份和支持导出中排除。选择包含它或嵌套它的工作区不会覆盖此规则。将捕获文件选择为配置或数据库备份源时，备份会被拒绝。其他状态的捕获通过精确的相邻布局识别：<owner>/ 位于 <owner>.update-captures/ 旁边，并且存在一个 owner 目录，包括已解析的目录链接。无关的类似名称工作区目录仍会被包含；仅凭后缀不能确立所有权。

被标记的私有目录在其 owner 被删除或重命名后，或该标记目录被移动或复制后，仍会被排除。请将标记与整个目录一起保留。未携带该标记而被复制出去的文件不会被此规则识别。固定的 .openclaw-private-update-capture 文件恰好包含 openclaw-private-update-capture-v1，后跟一个换行符。导出检查使用 lstat 检查每个路径组件，并在循环和深度限制下解析符号链接。已解析目标的真实祖先会接受与所选路径相同的标记检查。指向已标记目录的链接会被省略；格式错误或无法读取的真实标记会拒绝导出。循环和悬空链接没有已解析目标，并保持为链接条目，除非某个真实所选祖先将它们排除。普通未标记链接保留其原始目标，而不会通过链接复制目标内容。Windows 目标分隔符以正斜杠存储。

显式内容导出（包括 SQLite 快照）会通过同一分类器检查所选归档路径和实际内容源。支持包会报告被拒绝的输入，而不包含其内容。这些检查不会解析工作区清单，也不会扫描其他状态根。

该标记是一条排除指令，而不是工件所有权或重新打开、采用或删除它的权限证明。生产者必须在原始数据之前持久写入它，包括在每个可独立移动的暂存或捕获目录中。清理过程必须保留它，直到私有内容消失。此排除不会创建捕获，不会更改保留策略，也不会更改普通备份清理。

SQLite 快照¶

当你需要为一个 OpenClaw 拥有的 SQLite 数据库创建可移植工件，而不是广泛的状态归档时，请使用 openclaw backup sqlite。

快照创建恰好接受一个命名源。代理源始终使用当前配置解析出的 <agentDir>/openclaw-agent.sqlite，即使 agentDir 位于状态目录之外：

存储库为每个已提交快照包含一个目录。每个快照目录恰好包含：

• manifest.json
• database.sqlite

快照创建会在读取前验证活动数据库，使用 SQLite 的在线备份 API 捕获已提交的 WAL 状态，而不会持有一个长时间读事务，关闭活动数据库，使用 VACUUM 压缩私有副本，再次验证生成的数据库，并发布完成的目录，而不覆盖现有路径。全局快照在压缩前删除所有投递队列行，包括待处理工作、失败的所有权栅栏以及完成或幂等回执，因此负载详情和所有权墓碑既不会被发布，也不会保留在空闲页中。因此，恢复此经过清理的可移植快照并不是恰好一次投递的继续边界。这是有意为之的隐私与无重放可移植性权衡。

不要将活动的 .sqlite、-wal、-shm 或 -journal 文件作为可移植工件复制。只复制已完成的快照目录。

当数据库包含冷转录时，快照创建会在检查文件大小和 SHA-256 后，将每个被引用的压缩归档嵌入其私有数据库副本中，即使自动归档已禁用。完整归档和 Git 备份使用相同的冷负载捕获。恢复的数据库不需要原始冷目录；缺失或损坏的源归档会导致备份创建失败。请参阅 冷转录备份。

SQLite 快照可能包含身份验证配置、会话状态、插件状态和其他敏感记录。请使用与活动 OpenClaw 状态目录相同的权限、加密、保留策略和目标限制来保护存储库。

验证和恢复¶

openclaw backup sqlite verify <snapshot-directory>
openclaw backup sqlite restore <snapshot-directory> --target <new-database-path>

验证会检查严格的清单结构、制品大小和 SHA-256、SQLite 完整性、外键、架构版本、数据库角色和所有者，以及 OpenClaw 拥有的索引定义。

验证会校验一份私有的内容固定副本，以防止路径名竞争替换 SQLite 检查的字节。默认情况下，该临时副本会在快照仓库旁边创建，并在命令返回前删除。暂存根目录及其祖先链必须防止其他用户替换它。POSIX 根目录必须由当前用户拥有，且不可被组或其他用户写入；对于用户拥有的子项，接受具有粘滞位的祖先目录（例如 /tmp）。如果 macOS ACL 授权会暴露暂存目录或使其可被替换，则会被拒绝。Windows 根目录和祖先目录必须由当前用户或受信任的操作系统主体拥有，并且 ACL 必须拒绝不受信任的暂存访问。对于只读挂载或网络共享，请在具有等效加密和目标控制的存储上传入 --scratch <existing-private-directory>。

快照创建会在暂存或发布数据库字节之前，对仓库应用相同的拥有者、ACL、祖先目录和路径身份检查。新创建的目录项和最终发布元数据会在受支持的文件系统上通过共享的 fs-safe 持久性边界进行同步，然后才报告成功。

恢复会重复执行验证，并且只写入全新的目标。它会拒绝已存在的目标、-wal、-shm 或 -journal 附属文件，并且绝不会就地替换正在运行的 OpenClaw 数据库。目标父目录具有与验证暂存目录相同的路径安全要求。激活恢复后的数据库仍然是显式的离线操作员步骤。

快照仓库是本地目录。调度、上传、保留、增量 WAL 包、故障转移以及开机恢复行为均有意不在此命令范围内。

版本化 Git 备份¶

openclaw backup git 会在由操作员拥有的普通 Git 仓库中存储确定性的、按表划分的 JSONL 转储。一个仓库可以容纳共享数据库和每个代理的数据库：

global/manifest.json
global/schema.sql
global/tables/<table>.jsonl
agents/<agentId>/manifest.json
agents/<agentId>/schema.sql
agents/<agentId>/tables/<table>.jsonl

初始化仓库，然后为共享数据库和所有已配置的代理数据库创建快照：

openclaw backup git init --repository ~/Backups/openclaw-git --remote <private-git-url>
openclaw backup git create --repository ~/Backups/openclaw-git --all --push

仓库根目录必须由当前用户拥有，且不可被组或其他用户写入。OpenClaw 会在初始化或采用仓库时，以及每次创建之前检查这一点。在 POSIX 系统上，确认其所有权后，使用 chmod 700 <repository> 修复不安全的权限。

仓库必须专用于 OpenClaw 备份。现有的 global/ 或 agents/<agentId>/ 作用域只有在为空或包含有效的 schema-version-1 manifest.json 时，才被视为备份拥有。OpenClaw 会拒绝替换任何其他作用域。使用 --all 时，它会先验证 agents/ 下的每个现有条目，然后再删除过期的备份拥有的代理作用域，因此未拥有的条目会在删除任何内容之前中止清理。

使用 --all 时，只有从配置中移除的代理才会被修剪其作用域。如果某个已配置代理的数据库缺失或无法通过快照验证，则其先前的备份作用域保持不变，同时其他代理继续备份。该命令会在 CLI 警告、JSON warnings 以及记录的备份结果中将该代理报告为降级。如果该代理从未被备份过，则不会创建作用域。如果所选数据库无法复制，显式的 --agent <id> 选择仍会失败；如果没有可复制的数据库，则运行失败。

你也可以选择 --global、重复 --agent <id>，或将共享数据库与所选代理组合。显式代理选择、--all 和计划备份会从各自配置的 agentDir 解析每个数据库；历史制品验证和恢复使用制品中记录的代理 id，而不要求该代理仍保留在当前配置中。快照创建使用与 backup sqlite create 相同的在线备份、清理器、VACUUM、拥有者验证和完整性检查；它从不直接读取正在运行的 SQLite 文件。行和架构条目具有确定性顺序，整数和 blob 使用无损编码。该命令会创建一个名为 openclaw backup <ISO8601> 的提交。如果数据库内容未发生变化，它会打印 no changes 且不创建提交。

Git 暂存仅限于备份拥有的 global 和 agents 路径；在已采用仓库中其他位置的不相关文件永远不会被暂存。

--push 会将当前分支推送到 origin。在本地提交成功之后，推送失败只是一个警告，不会丢弃本地备份，也不会将其标记为失败。

备份清单会在 excludedTables 中记录被省略的表，并在 excludedConfigStateKeyPrefixes 中记录被省略的机器状态前缀。恢复会报告被省略的表和机器状态前缀，以免脱敏快照被误认为完整的凭据备份。

在不更改实时数据库的情况下检查或验证历史记录：

openclaw backup git log --repository ~/Backups/openclaw-git --limit 20
openclaw backup git verify --repository ~/Backups/openclaw-git --ref <commit> --global
openclaw backup git verify --repository ~/Backups/openclaw-git --ref <commit> --agent main

Git 历史记录输出必须能容纳在 16 MiB 读取范围内。如果日志请求报告输出限制错误，请使用更小的 --limit 重试。过大的提交主题即使使用 --limit 1 也可能超出限制；请直接用 Git 检查该历史记录。OpenClaw 会报告失败，而不会返回部分历史记录条目。

验证会将所选快照恢复到私有临时空间，检查每个表的行数和 SHA-256，运行 PRAGMA integrity_check 和 PRAGMA foreign_key_check，然后删除临时副本。恢复只会写入一个全新的目标，并拒绝已存在的 -wal、-shm 和 -journal 附属文件：

openclaw backup git restore --repository ~/Backups/openclaw-git --ref <commit> --global --target ./restored/openclaw.sqlite

恢复会在加载其内容表之后重建基于内容的 FTS5 索引。它会刻意省略派生的 session_transcript_index_state 投影，以便 Gateway 启动时对账重建转录搜索。由于扩展在恢复过程中不可用，vec0 虚拟表不会被物化；内存索引会重新创建它们并安排一次完整重建索引。

Git 备份创建、恢复和验证会流式传输表数据，而不是在内存中保留完整的表转储。恢复仍然需要为物化的 Git 文件和私有 SQLite 暂存副本预留空间；验证不会写入第二组表转储。

备份计划¶

创建一个由 Gateway 拥有、名称固定的自动化：

openclaw backup enable --repository ~/Backups/openclaw-git --every 24h --push

当省略 --every 时，间隔默认为 24h。在创建或更新计划之前，会拒绝显式为空或仅包含空白的间隔。

默认范围是所有数据库。使用 --global-only 或 --agent <id> 缩小范围，并添加 --exclude-secrets 以生成脱敏历史。推送计划（--push）默认会对包含凭据的表和具有 secret 前缀的机器状态行进行脱敏，因为无人值守的周期性推送会将其持久保留在远程历史中；如需显式的全保真远程备份，请传入 --include-secrets（从脱敏历史恢复需要设备重新配对和提供商重新认证）。--push 还要求仓库已经具有 origin 远程。重新运行 backup enable 会更新现有自动化，而不是创建重复项。openclaw backup disable 会移除它；禁用一个已不存在的作业是成功的空操作。备份计划目前要求本地 Gateway，因为命令作业运行在 Gateway 主机上；对于远程 Gateway，请使用 openclaw cron add 手动创建 cron 作业。

禁用计划时会跨所有列表页查找受管理的自动化，即使它已被重命名。名称相同但无关的自动化会保持原样。

已记录运行与新鲜度¶

每次真实的归档、SQLite 快照和 Git 创建尝试都会在现有共享状态数据库中记录一个紧凑的结果。试运行不会被记录。日志保留最新的 200 次尝试，因此频繁的计划仍保持有界。

openclaw status 显示一行 Backups 概览，openclaw status --json 包含最新尝试和最近一次成功运行。当没有记录到成功备份，或最新成功备份已超过 14 天时，openclaw doctor 会打印一条信息性提示。记录是尽力而为的：记录写入失败会打印警告，但绝不会把一次成功备份变成失败命令。

备份内容¶

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

• 状态目录（通常是 ~/.openclaw）
• 当前生效的配置文件路径
• 当 credentials/ 目录存在于状态目录之外时，其解析后的目录
• 所有已配置的 agent 目录，包括位于状态目录之外的自定义 agentDir 根目录
• 从当前配置中发现的工作区目录，除非你传入 --no-include-workspace
• 由实际已激活且可加载的插件清单声明的持久资源

认证配置和其他每个 agent 的运行时状态位于 <agentDir>/openclaw-agent.sqlite。默认 agent 根目录是 <stateDir>/agents/<agentId>/agent，但自定义根目录始终具有权威性， 无论它位于状态目录之外、工作区内部，还是嵌套在其他可再生的受管状态根目录下。--no-include-workspace 会省略普通工作区源，而不是已配置的 agent 目录。

--only-config 会跳过状态、agent、凭据目录、工作区和插件资源发现，只归档当前生效的配置文件路径。

OpenClaw 首先从配置中规划资源。它会在线捕获根 SQLite 数据库，然后从该私有快照中推导并冻结已注册 agent 的所有权，用于数据库发现和归档遍历。路径会被规范化：已被另一个包含根目录覆盖的配置、凭据、工作区和 agent 不会作为顶层源重复。只有当没有现有资产覆盖自定义 agent 根目录时，它才会成为一个独立的 agent 资产；当另一个资产包含它时，清单仍会记录其 agent id 和根目录。缺失的路径会被报告为已跳过。

工作区可以包含状态目录，包括工作区是你的主目录的情况。covered 跳过表示外层资产已包含这些文件。同一 agent 数据库的重复注册会解析为一个物理所有者；不同所有者共享同一个数据库时仍会拒绝备份。使用 --no-include-workspace 时也是如此。

旧版审计原始归档、导入声明和清理日志作为原始文件被排除；可恢复的审计源会获得经过清理的备份替换。它们的 .quarantined-* 变体仍被排除，并保留在本地，不会被导入或重写。经过清理的 .migrated 伴随文件和保留的 SQLite 审计历史仍包含在备份中。

在创建归档期间，OpenClaw 会在 tar 读取已知实时变更路径之前将其排除。这可避免文件记录的大小与并发写入之间的竞态。该过滤器在每个已备份状态目录下应用这些状态相对规则：

显式选择的资产根目录即使其名称匹配临时文件名规则，也会保持包含。活动配置文件即使其名称或位置匹配上述规则，也会保持包含。此例外仅保留所选配置文件；被排除目录下的相邻文件仍不会进入归档。

临时文件名规则适用于所有选定的根目录，包括每个代理工作区。特定于状态的日志、队列和浏览器规则仍限定在状态范围内。它们还会省略与表中匹配的已完成转录和日志文件，因此如有需要请单独保留这些记录。JSON 结果中的 skippedVolatileCount 报告有意省略的易失性条目，每个条目都在 skipped 中列出，原因为 volatile；可再生的代理临时根目录会单独列出，不计入该数量。

如果某个条目在遍历期间或打开之前消失，归档将继续处理存留的条目。每个被省略的路径都会以原因 vanished 出现在结果的 skipped 列表中，并出现在结果的 warnings 和文本摘要中。必需的源根目录和暂存捕获仍必须存在；权限和 I/O 错误仍会导致归档失败。可能将读取重定向到选定根目录之外的更改也会导致失败。文件会在其归档头写入之前打开，因此消失的文件不会留下部分条目。

Chromium 单例条目用于协调同一主机上运行的一个浏览器，并会在该配置文件启动时重新创建；配置文件的 user-data/ 其余部分仍保留在归档中。沙箱技能工作区是当前技能源的生成副本，并在 OpenClaw 在恢复后准备下一个沙箱上下文时再次实体化；相邻的沙箱注册表和其他持久状态仍保持包含。

托管 SQLite 快照涵盖共享的 OpenClaw 数据库、隔离和完整性验证存储，以及由配置声明、记录在捕获的持久代理注册表中，或在 <stateDir>/agents/<agentId>/agent/openclaw-agent.sqlite 处发现的每个代理数据库。这包括配置的自定义 agentDir 位置，以及代理移动或从配置中移除后遗留在默认位置的数据库。属于同一代理的不同数据库会分别捕获。--no-include-workspace 会保留此数据库覆盖范围。

在已激活插件声明的 backupResources 下具有 disposition: "include" 的 SQLite 文件也会获得托管快照。仅状态目录或代理目录下的其他文件名不会确立 SQLite 所有权。

托管数据库使用 SQLite 的在线备份 API 捕获，并离线使用 VACUUM 压缩。已提交的前写日志（WAL）更改会被包含，已删除页面的残留会被移除，边车文件会被省略。共享数据库和代理数据库也会接受其现有的临时状态清理，并且必须与其预期角色和代理所有者匹配。不安全的别名或所有者不匹配会失败关闭。声明的插件数据库如果要求不可用的 SQLite 功能，也会失败关闭，而不是回退到直接文件复制。

状态和已配置代理根目录下的其他 SQLite 文件（包括其边车文件）会作为不透明字节复制。创建过程会在 warnings 中以 opaque 标签报告每个文件名。超过链接解析限制（ELOOP）的未托管 SQLite 符号链接（包括循环）会被跳过，并带有指明该链接的警告。其他链接保留其现有处理方式。验证和恢复会保留这些字节，而不会打开、压缩或验证数据库。这些副本不具备活动数据库一致性或已删除数据移除保证。当需要这些保证时，请使用拥有该数据库的应用程序的备份流程。

指向托管 SQLite 数据库的硬链接共享一个捕获的映像，并为每个名称存储为单独的常规归档条目。每个硬链接都必须是核心清单或声明的插件备份资源所拥有的、被包含的 SQLite 文件。如果恰好有一个名称具有非空的前写日志（WAL），则该名称提供已提交的数据。没有非空 WAL 的已关闭数据库仍受支持。多个非空 WAL、非空回滚日志，或备份清单之外的硬链接会导致明确拒绝且不生成归档。在重试之前，请干净地关闭数据库写入器，并将所有硬链接包含在这些资源中。捕获期间对共享数据库文件的更改也会拒绝备份，包括在日志检查重复之前截断其 WAL 的并发别名检查点。规范的 OpenClaw 数据库别名保留其现有的所有者验证和清理。

Installed plugin source and manifest files under the state directory's extensions/ tree are included, but their nested node_modules/ dependency trees are skipped as rebuildable install artifacts. After restoring an archive, use openclaw plugins update <id> or reinstall with openclaw plugins install <spec> --force if a restored plugin reports missing dependencies.

The state directory's plugin-skills/ root is a generated, OpenClaw-owned symlink index, not authoritative state. Backup creation reports and omits that root because its absolute targets are specific to the source installation. After activating restored state, run openclaw skills list or start an agent session to rebuild the links from current plugin metadata.

Agent-scoped temporary trees under agents/<agentId>/agent/**/{tmp,.tmp}/ are also omitted and reported as regenerable. This includes temporary files directly below an agent directory and temporary trees inside agent runtime homes; durable sibling directories remain included. An explicitly configured config file, credentials directory, or workspace nested below an omitted temporary root remains included.

Symbolic links are archived as link entries, including absolute and dangling targets. Windows target separators are stored as forward slashes to match tar's reader; POSIX target text, including literal backslashes, is preserved. Creation never follows a link to copy its target. Targets outside the state directory, including separately backed-up config, credentials, or workspace targets, are recorded in the manifest and JSON result's externalSymbolicLinks list and reported in the text summary. Restore recreates the links after extracting the file content; it never writes through a restored link. Verification rejects archive entries nested beneath a symbolic link.

Absolute links retain their original location after restore, including links to separately backed-up config or credentials. They are no longer rewritten to relative targets. Review these links before activating a restored tree on another host or at another path. Older releases, including v2026.9.4, reject archives with absolute or escaping link targets; use the current release to restore those archives. Existing archives remain readable.

Installer-managed and rebuildable runtime roots under the state directory are also skipped: dev/, git/, npm/, legacy npm-runtime/, tmp/, and tools/. These contain managed checkouts, package trees, compiler caches, temporary files, and downloaded runtimes rather than authoritative user state; reinstall or update the corresponding runtime or plugin after restore. Effectively activated, loadable plugins can declare additional durable or regenerable state- or agent-relative roots through backupResources. Disabled or unloadable plugins cannot exclude data. Explicit config, credentials, workspace, agent, and plugin-included paths override exclusions, and any excluded parent remains traversable to reach those protected descendants. Names such as tmp and .tmp are not blanket exclusions in custom agent directories; only an applicable owner declaration can omit their durable-looking siblings.

Local edits inside a managed dev/ checkout are developer source, not OpenClaw product state, and are not included. Commit and push those edits or copy the checkout separately before relying on a state backup.

无效配置行为¶

openclaw backup 会绕过常规配置预检，以便在恢复期间仍能提供帮助。状态归档要求已解析的代理和插件所有权。如果发现失败，backup create 会报告底层错误并拒绝发布归档。--no-include-workspace 会排除工作区文件；它不会绕过所有权发现。

发现通过在线 SQLite 快照读取共享状态，因此并发写入者不会使有效配置显得无效。如果无法读取状态，请解决报告的错误并重试备份。

当配置格式错误或状态发现失败时，--only-config 仍然有效。它仅保存当前活动的 JSON 配置文件，不解析该文件，也不包含其依赖项。

大小和性能¶

OpenClaw 不强制内置的最大备份大小或单文件大小限制。如果归档写入五分钟没有产生数据，则会失败并删除其部分临时文件，而不是无限期挂起。其他实际限制来自：

• 用于临时归档写入和最终归档的可用空间
• 遍历大型工作区树并将其压缩为 .tar.gz 所需的时间
• 使用 --verify 或 openclaw backup verify 重新扫描归档所需的时间
• 目标文件系统行为：OpenClaw 要求不覆盖的硬链接发布，因此最终归档路径永远不会暴露正在进行的副本；不支持的文件系统会以可操作的错误失败

如果在发布后最终目录持久性确认失败，命令会报告失败，但会保留完整的最终条目，而不是冒着删除并发替换的风险。

大型工作区通常是归档大小的主要驱动因素。使用 --no-include-workspace 可获得更小/更快的备份，或使用 --only-config 获得最小的归档。

归档创建会为其临时 openclaw-backup-owned-* 暂存目录保持一个 SQLite 生命周期事务。下一次备份运行只有在获得独占控制权后才会删除被遗弃的暂存目录；正在运行的备份即使其暂存目录较旧也会保留它。清理失败会保留已发布的归档，并以警告形式出现在文本和 JSON 输出中，其中包含暂存路径。该 owned 前缀还允许清理在新创建者的令牌存在之前与其协调，而不会将该分配误认为旧版暂存。如果清理在创建者声明其目录之前获胜，创建会使用新目录重试。目录标识发生变化仍会被拒绝。扫描观察到但在清理前消失的暂存目录会被记录为已回收，不会发出警告，也不会声称本次运行删除了它。

openclaw doctor 会报告活动临时目录以及已记录的归档目标目录中的 scratch。openclaw doctor --fix 会删除其生命周期事务已结束的已识别 scratch。未知内容、符号链接以及没有生命周期令牌的旧版目录会被保留，并提供检查指引。旧版本不会创建这些令牌，因此在手动删除其报告的 scratch 目录之前，请先停止旧版备份进程。已发布的归档和包回滚备份不在此清理范围内。已退役的 scratch 在删除前会被重命名为 openclaw-backup-retired-*，以便即使生命周期令牌已消失，后续处理也能完成部分清理。

相关¶

• CLI 参考
• 迁移 OpenClaw 安装
• 恢复完整归档