跳转至

回滚与恢复

Downgrades, automatic rollback, verified pre-update backups, and triage when an update leaves you stuck. Part of the Updating guide.

降级

在通过 openclaw update cleanup 移除恢复原始文件之前，请先验证升级和你的会话历史。降级软件包不会回滚配置或数据库迁移。一旦状态已迁移到超出旧版本支持的范围，受支持的恢复方式是使用与其匹配的 OpenClaw 版本恢复经过验证的更新前备份。

升级和恢复时优先使用 openclaw update。它会验证目标版本，运行所需的 Doctor 迁移，并验证已激活的 Gateway。直接使用 npm i -g 替换不会保留之前的软件包，也不会运行此恢复工作流；请使用 openclaw update 或先创建备份。

更新器在激活期间会保留之前的软件包，并且在恢复失败无法证明安装可用时也会继续保留它。迁移恢复原始文件会一直保留，直到显式执行更新清理。这些是相互独立的恢复机制：清理不会管理软件包或 Git 运行时备份，保留的迁移原始文件也不是完整的更新前备份。在验证安装之前，请保留更新报告中列出的所有恢复位置。

启动器备份会比较链接类型和目标，并在可以保留时比较所有权。符号链接权限位不会阻止更新；在受支持时，macOS 链接模式会被复制。常规文件启动器仍要求模式和内容匹配。如果备份验证失败，报告会列出不同的字段以及保留的失败副本，供重试前检查。

此行为属于已安装的更新器。较旧的更新器（包括 2026.9.4）可能在目标版本运行之前拒绝 macOS 启动器备份。如果首次更新被阻止，请使用该安装的手动包管理器更新流程。

对于能够读取当前状态的目标版本，请预览并使用受管理的回滚路径：

openclaw update --tag <known-good-version> --dry-run
openclaw update --tag <known-good-version>

更新器会检查兼容性并要求确认降级。如果已保存的通道是 extended-stable，请为一次性精确标签添加 --channel stable。受支持的目标会完成配置写入器时间戳，重启服务，并验证正在运行的版本。较旧的目标可能缺少该完成步骤或迁移继续契约；如果激活被拒绝，请遵循打印的恢复指南。不要绕过针对较新架构或较新配置的拒绝。

当更新报告识别出保留的原始文件时，请在清理前使用相应的Doctor 恢复命令。恢复旧版会话工件不会回滚 SQLite 架构，也不会恢复仅在 SQLite 中创建的会话。如果旧版本无法读取当前状态，请使用恢复完整归档恢复更新前备份。在激活已恢复状态期间，请保持 Gateway 和其他写入器停止，并先单独保留当前状态：恢复会丢弃自备份以来所做的更改。通过安装的包管理器重新安装匹配的软件包；备份归档不包含软件包。

完整的恢复点必须同时涵盖以下内容：

  • 匹配的 OpenClaw 软件包版本或源代码修订版本以及构建的运行时。
  • openclaw.json，包括 meta.lastTouchedVersion。
  • state/openclaw.sqlite 以及每个 agents/<id>/agent/openclaw-agent.sqlite，包括位于默认布局之外的已配置路径中的数据库。
  • 该安装所需的工作区、凭据和保留的原始文件。

使用 openclaw backup create --verify 创建经过验证且支持 WAL 的归档。切勿仅从活动 WAL 数据库复制主 .sqlite 文件：已提交的数据可能仍在 -wal 中。请离线恢复经过验证的合并数据库；不要将其与来自另一代数据库的 -wal 或 -shm 文件混用。有关归档覆盖范围和遗漏内容，请参阅备份。

具有启动预检修复的版本在预检拒绝启动时，会保持配置、数据库和迁移输入不变。成功启动可能会将状态向前迁移。较旧的二进制文件随后可能同时拒绝数据库架构和配置中的 meta.lastTouchedVersion；更改任一版本标记都无法撤销迁移。请使用 openclaw doctor --fix --non-interactive 修复已安装版本，或使用上述备份恢复。

在恢复期间，请在 Gateway 环境中设置 OPENCLAW_NO_AUTO_UPDATE=1，以防止已启用的自动更新器立即重新应用较新的版本。

恢复后，在清理前验证正在运行的安装：

openclaw --version
openclaw health
openclaw gateway status --deep --json
openclaw doctor --lint --json
openclaw update cleanup --dry-run

完整状态恢复需要备份

软件包更新会将迁移前的 SQLite 快照与软件包备份一起保留，直到经过验证的成功激活随该备份将其移除。回滚、失败或未经验证的完成以及被拒绝的恢复都会保留它们。如果清理无法完成，更新会报告一条维护警告，并附上保留的路径。较旧的快照目录不会自动移除：无法从现有回执中证明其所有权和成功结果。Doctor 会报告较旧的 npm 快照目录，包括其大小和移除命令。在手动清理前，请确认没有更新正在进行，并检查相应的更新报告和恢复状态。如果在捕获期间已确认 Gateway 已停止，并且 Doctor 记录的写入指纹仍然匹配，则从未被允许启动的失败候选项可以在软件包回滚前恢复这些数据库。在捕获和 Doctor 接受之间，或在 Doctor 完成后发生的任何更改，都会保留当前数据库，并报告 state-migrated-no-rollback，同时附上快照位置和 Doctor 恢复指南。如果没有 Doctor 写入证据，回滚要求最后经过验证的数据库代际保持不变。在 Gateway 可能仍在写入时拍摄的快照，仅在经过验证的成功激活之前可用于手动恢复，即使它稍后退出也是如此。迁移后的文件会保留为 <database>.migrated-<runId> 以供检查，报告会列出快照和被替换的文件。有关磁盘要求和生命周期检查，请参阅恢复限制。

数据库恢复会保留当前更新历史，包括捕获后记录的失败详情。保留的原始快照保持不变。

这需要由修复后的更新器来驱动更新；已在运行的旧驱动无法从候选版本获得数据库回滚。可能已提供服务的候选版本会保持现有的拒绝，以避免丢弃较新的写入。仅替换其包无法逆转迁移。对于有意降级，请使用经过验证的更新前备份及其匹配版本。更新器不会创建或重放完整状态检查点。

现有的待处理检查点恢复记录会阻止进一步的可变更新。更新器会报告其不受支持，并保持其记录、备份和状态不变。不要删除或修改保留的工件以强制获得干净状态，也不要使用 update finalize 绕过拒绝。请保留报告的位置，以便用于兼容的恢复实现或独立的已验证备份。被中断或被拒绝的恢复不是成功的回滚。

自动架构中立回滚

如果新激活的包未通过验证，openclaw update 将共享的以及受影响的每个代理的 SQLite user_version 值与其激活前的值进行比较，并检查配置文件是否仍与新版本的激活 Doctor 写入器报告的内容匹配。 在激活或验证期间首次创建的数据库，当其版本与该数据库类型在新版本中支持的版本匹配时，是架构中立的。 架构版本发生变化、缺失预先存在的数据库，或新数据库处于外部版本，仍会阻止回滚。在恢复代码之前，更新器还会检查之前的包是否支持任何新数据库；未知或不兼容的支持会以 rollback-state-unverified 拒绝回滚。 当两项检查均通过，且保留的之前包在更新前已验证时，它会停止新版本并恢复上一代：包、命令垫片、服务定义以及激活前的精确配置字节，包括之前的写入器戳。配置替换使用仅所有者权限（0600）；未更改的配置无需写入。拥有且可写的服务元数据会被刷新；受保护的服务定义会被保留。 CLI 会再次验证重启后的之前 Gateway 的服务健康状态、版本/构建标识、插件、通道以及 /readyz。更新验证不使用模型推理：托管服务必须正在运行并拥有其端口，且 Gateway hello 握手必须与预期工件匹配。

新版本在主配置文件及其 $include 文件中的 Doctor 迁移不会阻止回滚，包括全新安装的首次更新。更新器会保留 Doctor 之前的配置，并验证 Doctor 在做出更改之前已消费了这些捕获的字节。 它还会将每个当前文件与 Doctor 写入器报告的输出哈希进行比对。 仅当两个哈希都匹配时，回滚才会恢复原始字节。恢复过程会持有常规配置写入器锁，并在获取锁后重新检查文件。激活后由操作员做出的编辑会阻止恢复，包括 Doctor 读取配置之前的编辑，以及 Doctor 最后一次写入与更新器捕获之间的编辑。更改的 include 路径也会阻止恢复。仅保留根文件的旧更新器交接仍要求 include 保持不变。现有的有意恢复豁免仅适用于服务命令，因此旧二进制文件保护不会阻止恢复；它永远不会保存在配置或服务环境中。

缺失或格式错误的 include 不会阻止 Doctor 运行。当更新器无法捕获完整的 include 图时，它会警告自动配置回滚不可用，并且如果更新稍后失败，会保留任何 Doctor 修复。

成功恢复会让之前的 Gateway 保持运行，并将运行结束为 rolled-back，其中 after.version 设置为之前的版本，停机时间从服务停止到验证恢复完成进行测量。标题为 ↩️ OpenClaw update rolled back to <previous>: <reason>，保留原始验证失败。命令仍以非零退出；恢复不会将被拒绝的版本变成成功的更新。

恢复报告会区分已恢复的包文件和健康的 Gateway。 已验证的回滚会指明恢复后提供服务的版本，包括需要额外修复的情况。如果恢复的服务未通过健康检查， 结果会记录 recovery.service: "failed"；报告会说明健康检查失败，并包含记录的恢复原因。仅当验证无法运行或完成时，健康状态才会报告为未验证，例如就绪超时。两种结果都会引导你使用 openclaw gateway status --deep 检查提供服务的版本和就绪状态。回滚使用与更新激活检查相同的启动豁免。 重启通知会保留恢复后的运行时所理解的恢复字段。 详细的恢复原因保留在更新结果、状态诊断和失败报告中。

使用 openclaw update status 查看记录的原因，并使用 openclaw triage 诊断失败的检查。恢复指南会根据最新的服务观察报告 Gateway 正在运行还是已停止，即使新版本正在运行但未通过验证。恢复的 Gateway 必须先通过其自身的验证检查，运行才能以 rolled-back 结束。

在 Control UI 中，打开 设置 → 更新 并选择 诊断更新，以要求 OpenClaw 调查记录的失败。加载仪表板、重新连接或收到更新失败都不会启动诊断。每次诊断请求都需要按下按钮；它不会重试更新。

自动 CLI 分诊永远不会跟随已验证的回滚；它仅在更新以失败结束时运行。在交互式终端中，你可以选择 诊断更新失败、报告更新失败 或 退出，默认选中 退出。报告会显示脱敏预览，并在创建问题之前需要单独确认。跳过或取消不会启动诊断或提交报告。 JSON、--yes、非交互式以及托管服务交接调用在回滚后不会显示此菜单。

If the config file changed after the activation Doctor pass or the databases remain incompatible after eligible pre-start restoration, rollback is refused with state-migrated-no-rollback. For config edits, the next action names the file whose changes blocked restoration. The updater preserves the failed outcome and migrated state. Optional post-failure triage can run after update ownership and service compensation settle, including after failed rollback. Use the printed diagnostics and installation-specific repair command before considering an older version. Triage does not rewrite that failed update as successful. Automatic rollback restores code and captured config, and restores pre-migration database snapshots only when the Gateway was confirmed stopped during capture and the candidate was never allowed to start, with matching write fingerprints through Doctor and rollback. The temporary snapshots used to check migrations are removed after validation and do not replace your backup. If the schema comparison cannot be completed, automatic rollback is refused (rollback-state-unverified). The newly installed version owns final verification and reporting after migration, preserving the same run ID and recorded activation steps.

对于 pnpm 和 Bun，如果在暂存后更改了同级全局包，则自动回滚会被拒绝（rollback-project-changed），并且不会恢复共享项目；请保留一个可用版本已安装，否则保持 Gateway 停止，并按照报告中的修复命令操作。 如果在实时切换之前被拒绝，则会重启未更改的 Gateway，并保留同级更改。

更新前：创建经过验证的备份

openclaw update 会保留一份自动的更新前配置副本，而不是完整状态恢复点。在进行重要更新之前，请显式创建一个独立的、经过验证的备份：

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

归档清单会记录 OpenClaw 版本以及备份中包含的源路径。归档可能包含凭据、身份验证配置文件和通道状态，因此请仅以所有者权限存储，并施加与实时状态目录相同的保护。有关包含的文件和有意省略的文件，参见 备份。

对于包含便携式归档所省略的易失性工件的逐字节恢复点，请停止 Gateway，并使用你的平台提供的文件系统、卷或 VM 快照。这对旧的基于文件的安装很重要：便携式归档会省略对应的 JSONL 转录和日志，即使它们已不再被写入。

在迁移大型遗留历史记录时，请同时为原始文件、临时 SQLite spool 以及目标数据库/WAL 预留空间。SQLite 可能比原始 JSONL 更大；流式导入并不意味着固定的 RAM 需求或迁移时间。请检查系统临时卷和状态卷上的可用空间。有关暂存和内存详情，参见 会话 SQLite 迁移。

如果你卡住了

在 Gateway 主机的终端中运行 openclaw triage，使用打印出的针对该安装环境的命令，或保持相同的配置文件以及状态/配置覆盖设置。它会按以下顺序打开第一个可直接启动的编码代理：Claude Code、Codex、OpenCode，然后是 Pi。该代理会接收本地诊断信息和任何已记录的失败更新结果，以便修复安装并验证 Gateway 健康状况，同时使用其常规身份验证、沙箱和审批设置。使用 openclaw triage --agent codex 可选择特定代理。

失败的交互式更新会在更新器清理后提供分诊，并在新诊断可能延迟交接之前将捕获的失败传递给代理。启动前，OpenClaw 会显示代理、可用的已保存提示词路径，以及使用你自己的账户/令牌。只有明确的 Yes 才会继续。按 Enter、n、取消，或 30 秒内未作答，都会跳过启动，打印手动恢复命令，并保留诊断信息和失败更新的退出状态。显式运行 openclaw triage 不会请求此确认。JSON、--yes 和非交互式更新调用可以在符合条件的失败后启动一次受控的自动修复；其他失败会保留诊断信息和交接命令。如果仅用于诊断收集，请使用 openclaw triage --non-interactive；添加 --update-result <path> 以包含已保存的更新失败工件。有关命令格式和安装目标定位，参见 分诊。

分诊会保持失败更新的报告完整。在修复期间启动的更新会创建自己的历史记录条目。包替换后，重启命令会从更新后的安装中运行。被服务所有者接受的重启仍可能未通过就绪检查；重试前请检查 openclaw gateway status --deep。

在修复期间，请保持已停止且未验证的 Gateway 处于停止状态，并保留已迁移状态。模式迁移后保留的可用版本可以在你诊断时继续提供服务。 即使代理修复了它，失败更新仍会保留其非零退出码。

  • 对于源代码检出中的 openclaw update --channel dev，更新器会在需要时自动引导 pnpm。如果你看到 pnpm/corepack 引导错误，请手动安装 pnpm（或重新启用 corepack），然后重新运行更新。
  • 检查：故障排除
  • 在 Discord 中提问：https://discord.gg/clawd

使用你自己的推理进行无人值守修复

更新、验证、校验和回滚不需要推理或模型身份验证。不可用的模型路由不会阻止这些操作。验证失败会丢弃已暂存的候选版本，同时旧 Gateway 继续提供服务。激活后，更新器会先完成其现有的经过兼容性检查的回滚和服务补偿流程。

符合条件的失败更新在更新所有权释放后，可以启动一次受控的分诊修复。分诊会针对剩余的安装环境，保留已迁移状态，并保持原始失败更新的结果和非零退出码。成功修复不会追溯地发布成功更新或已验证的回滚。旧版更新器的报告仍可能包含 repairing 阶段及其尝试摘要。

2026.9.4 发布的更新器可能在更新完成前调用候选项的 repair-worker 入口。新候选项保留其响应协议，但在不加载模型或更改操作员状态的情况下报告推理修复不可用。已发布的驱动程序仍拥有该首次更新的控制流和预算。

对于使用已配置推理的显式修复，请在 Gateway 主机的终端中运行 openclaw triage --run。Triage 会运行 Doctor 健康检查，尝试最多一个带时间和工具调用限制的嵌入式修复轮次，然后再次运行 Doctor。它使用常规运行时凭据解析器，包括继承的配置文件和 OAuth 刷新；推理不可用会产生外部交接，而不是登录提示。修复会保留现有安装范围和工具策略限制。

已保存的激活或恢复失败还要求记录更新器完成状态以及当前安装和 Gateway 验证。可归因的 Doctor/config 阻塞项可通过新的 Doctor 检查和已记录的已安装身份解决，而其历史失败运行保持不变。原生服务激活和恢复保留其现有权限检查。有关安装目标、修复限制和验证结果，请参阅 Triage。

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