备份任务显示成功，但你还没在新目录启动过恢复副本？ 最快解法：先核对 SQLite、Agent 目录、配置、凭证和工作区是否都在保护范围，再隔离恢复并检查 Gateway；任务成功不等于恢复可用。
负责 OpenClaw Gateway 和 Agent 持久化数据的 IT 负责人，需要明确故障后能恢复哪些状态。
负责远程 Mac 与 Agent 运行环境的平台工程负责人，需要验证备份和恢复流程能否在目标主机执行。
负责凭证治理与数据保护的安全负责人，需要审查备份包含的敏感信息及其访问控制。
最后更新于 2026 年 10 月 14 日；版本状态核对自OpenClaw 官方发布索引。下文涉及的命令、备份范围与恢复边界，按 OpenClaw 官方备份、CLI 和数据库文档复核；这不是 MACNOX 的恢复演练或服务能力声明。
SECTION 01开始演练前：把恢复目标写成一份范围清单
先写清“恢复可用”对你的业务意味着什么，而不是把“找回一个 .sqlite 文件”当作目标。主机损坏通常要求恢复整套运行状态；误删可能只需恢复特定数据；升级回退还要确认旧版本是否能读取备份中的数据库结构。目标不同，恢复范围和启动检查也不同。
依据官方数据库布局说明，默认部署至少要盘点共享状态数据库和各个已配置 Agent 的数据库。每个 Agent 的路径要以实际配置为准：agentDir 可以指向状态目录之外的位置，迁移时不能只照抄默认目录结构。
清单应逐项列出：
- 共享状态与各 Agent 的
openclaw-agent.sqlite。 - 当前配置文件，以及配置所引用的
$include文件。 - 凭证目录、认证资料、会话历史和工作区。
- 自定义
agentDir的实际路径，以及已启用插件声明的持久化资源。 - 你的备份方式是否包含以上每一项，遗漏项由哪条独立流程保护。
做 macOS 到另一台 Mac 的迁移时，逐项比对源主机与目标主机的自定义路径映射。默认路径存在，不代表自定义 Agent 数据也被收进了备份。
SQLite 数据库怎么备份才不会漏掉 WAL 数据？
不要把运行中的主 .sqlite 文件单独复制走。采用 OpenClaw 支持的备份路径：完整归档可覆盖配置、凭证、会话、Agent 目录及可选工作区；SQLite 快照适合单独保护某个数据库，但需要为共享库和每个 Agent 库分别纳入计划。两者都不能替你跳过范围核对。
官方备份文档说明，直接复制运行中的 .sqlite、-wal、-shm 或 -journal 文件，不能作为可靠备份；WAL 中可能还有已提交的数据。完整归档与数据库快照的创建、验证和恢复命令则见官方 CLI 备份说明。
SECTION 02备份生成后：先审工件，再把结果留档
选择路径时，先看你要保护的是整套运行状态，还是单个数据库：
- 需要整套迁移或主机灾备：用完整归档，并确认工作区是否纳入。默认归档会计划收集状态目录、当前配置、配置依赖、外置凭证目录、配置中发现的 Agent 目录与工作区，以及符合条件的插件持久化资源。
--no-include-workspace会排除普通工作区文件；--only-config则只备份活动配置文件，不是完整配置恢复点。 - 需要单库快照：为共享数据库与每个配置中的 Agent 分别创建快照。只备份共享库不能替代 Agent 库、配置、凭证或工作区的保护。
- 需要版本化数据库备份：可以评估 Git 备份路径，但仍需确认恢复时目标库、工作区及配置等非数据库资源由什么机制恢复。
有个容易误判的边界：完整归档会先固定配置，再分别捕获数据库；它不是配置和所有数据库共同构成的原子时间点快照。备份期间若配置或其他状态仍在变化，就要评估这次归档是否符合你定义的恢复点，而不能仅凭归档文件生成成功就放行。
备份里会包含 API 凭证和聊天记录吗？
这取决于所选路径。完整归档可能包含认证资料、渠道与服务提供方凭证、会话历史及其他敏感记录；SQLite 快照也可能包含认证资料、会话状态和插件状态。完整归档会保留活动配置及必需的 $include 文件，但其说明中标注解析后的秘密值不会写入配置副本。不要据此推断凭证目录或数据库也不敏感：它们仍可能包含需要严格保护的信息。
把备份库的加密、访问限制、保留策略和目的地控制设为不低于在线状态目录的标准。每次备份至少留存备份标识、时间、范围、存放位置、所用命令与验证结果；记录中不应抄入凭证值或会话内容。
注意：工件存在、校验通过、恢复后能够启动，是三种不同证据。归档验证也不会替你证明所有非数据库文件都能被业务流程正确使用；应把它与隔离恢复及服务检查分开记录。
SECTION 03校验阶段：确认工件结构、校验结果和路径安全
对完整归档，按实际生成的工件执行官方校验，例如：
openclaw backup verify <archive-path>
需要生成后立即验证时，可在备份创建命令中使用 --verify。归档验证会检查清单、声明的载荷是否存在，并验证清单中列出的 SQLite 快照；但对其他文件的内容，不等同于逐项恢复后运行检查。因此，验证通过是必要证据，不是端到端恢复证明。
如果你选用的是 SQLite 快照，应对每个快照目录单独验证：
openclaw backup sqlite verify <snapshot-directory>
该验证会检查清单、文件大小与 SHA-256、SQLite 完整性、外键、架构版本，以及数据库角色和所有者。恢复命令会再次验证，并且只写入一个全新的目标文件；目标已存在或带有 SQLite sidecar 时会拒绝操作。快照仓库、验证临时目录和恢复目标父目录也有路径权限要求，不能放在不受控的共享临时位置。需要在只读挂载或网络共享上验证时，应提供受控的私有 scratch 目录。
如果目标运行版本与备份来源不同，先做兼容性预检，不要靠“数据库能打开”猜测兼容。数据库结构变更与发布预检说明指出，Agent 库预检会检查完整性、架构版本、结构及 Agent 所有权；只有结果为 exact 才是该预检所定义的兼容性证明。预检结果不能替代目标运行时的服务健康检查。
SECTION 04隔离恢复阶段：新建目标，不覆盖在线状态
恢复后如何确认 Agent 会话和配置正常？
把恢复副本写入一个新的暂存目录，绝不直接覆盖正在运行的状态目录。以单个 SQLite 快照为例：
openclaw backup sqlite restore <snapshot-directory> \
--target <new-directory>/openclaw.sqlite
如果恢复的是完整归档，使用官方归档恢复命令并把目标设为新的暂存目录。随后检查归档 manifest.json，核实状态、配置、凭证、工作区和 Agent 路径的记录；有资源显示由其他父项覆盖时，确认它确实通过该父项纳入，而不是误判为缺失。
在不接入生产写入的条件下，逐项核对：
- 恢复后的配置能否解析，所需
$include文件是否齐全，Agent 标识与自定义目录映射是否符合目标主机实际路径。 - 共享状态与各 Agent 数据库是否通过相应的校验；会话列表能否查看，选定的会话记录是否能读取。
- 预期工作区、认证资料及必需资源是否存在；需要重建的插件依赖是否已按维护流程处理。
- 目标版本的兼容性预检和诊断是否通过；失败项是否会阻断正式切换。
会话可见并不代表所有外部依赖已恢复。数据库能打开，也不代表消息渠道认证、插件或外部服务凭证仍然有效。把这些依赖列为单独的演练项，并在恢复环境中使用经批准的测试方式验证。
恢复操作可能需要额外磁盘空间：Git 备份恢复还需要容纳物化文件和私有 SQLite 暂存副本的空间。实际需求取决于你的工件和恢复方式，不应在没有实测或配置数据时预估固定容量。
SECTION 05激活与复核阶段：先停写，再切换并启动
Mac 主机迁移时哪些 Agent 目录需要单独核对？
逐个核对配置里实际解析出的 agentDir，尤其是状态目录之外、工作区内，或嵌套在其他目录中的自定义根路径。数据库布局文档给出的默认路径只是默认值；迁移时以清单和活动配置确认的路径为准。若新 Mac 的路径不同，先更新配置或把资源恢复到配置指定的位置，再进入激活阶段。
正式切换前，停止 Gateway 及会向相关数据库写入的进程。按官方恢复流程，将恢复状态放到指定位置，或让 OPENCLAW_STATE_DIR 指向已恢复状态，然后在重启 Gateway 前运行：
openclaw doctor
别把“恢复命令退出成功”当作可以立即开放流量。诊断未通过、Agent 目录不匹配或配置依赖缺失时，应暂停启动并先处理问题。兼容性预检、运行时身份与服务健康是不同检查，不能互相替代。
Gateway 启动后，检查服务健康、Agent 与会话是否可见，再验证业务必需的插件和外部认证。恢复本质上是回到一个较早状态：审批状态、消息投递或去重记录可能随备份时间点回退；涉及需要继续对话的渠道认证时，回退也可能要求重新关联。先评估待处理审批和重复发送风险，再恢复生产写入。插件依赖目录可能不在归档内，按官方恢复说明检查是否需要重装或更新插件，并确认技能索引等可重建资源已恢复。
SECTION 06演练结论阶段：留证据，再决定是否扩大负载
将以下记录保存在企业变更或恢复演练档案中，确保责任人能复核每项结果：
- 备份标识与时间：归档或快照位置、对应恢复点。
- 范围：共享数据库、每个 Agent、自定义目录、配置依赖、凭证、工作区及其他纳入资源。
- 工件验证：使用的命令、返回结果、失败项与复测结果。
- 隔离恢复：暂存目标位置、目标版本、兼容性预检和诊断结果。
- 业务复核：Gateway 状态、Agent 与会话可见性、外部依赖检查、待处理审批与投递风险。
- 责任归属：执行人、复核人、整改事项和重新验收条件。
按照以下分支作出验收决定：
- 若备份范围覆盖你声明的恢复目标，工件验证通过，隔离恢复与启动后检查也完成，且业务依赖有明确复核证据，则判定通过，按既定变更流程启用。
- 若核心数据可恢复，但某些路径、工作区或外部依赖仍有未验证项，则判定限期整改；完成补测前，不把演练记录描述成完整恢复证明。
- 若缺少关键 Agent 数据、恢复工件校验失败、目标版本不兼容，或尚未完成隔离恢复，则暂缓扩大 Agent 工作负载，先修复备份策略并重新演练。
你的现有方案若依赖运行中的 SQLite 主文件手工复制、只保留共享库，或没有恢复目标与责任记录，就存在 WAL 数据遗漏、Agent 目录失联和故障时无法证明恢复有效等缺口。先用现有受控 Mac 完成隔离演练；若团队需要一台持续运行的 Mac 来承载恢复验证或临时运行环境，再评估 MACNOX 的远程 Mac 环境与部署入口，并按你的使用期限和资源需求查看套餐与计费信息。若工作负载长期稳定、持续高强度运行，或依赖必须直连的物理设备，购置自有 Mac 也应纳入比较；无论选择哪条路径，都不能用托管环境替代独立备份和恢复验收。