---
summary: "降级、自动模式中立回滚、经过验证的更新前备份以及在更新陷入困境时进行分类"
read_when:
  - "更新后出现问题，您需要返回"
  - "你想知道`openclaw update`什么时候可以自动回滚"
  - "您正在重大更新之前创建经过验证的备份"
  - "更新失败，您需要分类或无人值守修复"
title: "回滚和恢复"
---

降级、自动回滚、验证更新前备份以及在更新陷入困境时进行分类。 [Updating](/install/updating) 指南的一部分。

## <a id="before-you-upgrade"></a> 升级之前

- 创建 [ 已验证备份 ](#before-updating-create-a-verified-backup) 并保留相同的服务帐户、配置文件和 state/configuration 路径。
- 将 `openclaw --version` 与 `openclaw status` 和 `openclaw gateway status --deep` 进行比较。第一个报告CLI版本；状态报告针对不同安装的网关服务。在`openclaw status --json`中，将`update.root`与`gatewayService.layout.packageRootReal`进行比较； `gatewayService.layout.entrypointReal` 标识服务二进制文件，`gatewayService.installationDrift` 解释不匹配情况。
- 使用 `node -p "process.execPath + ' ' + process.version"` 检查实际的 Node 可执行文件和版本。将它们与更新程序检测到的运行时和所需范围进行比较，因为该服务可以选择与您的 shell 不同的 Node。请参阅 [ 支持的 Node 版本](/install/node)。
- 运行 `openclaw update --dry-run` 并检查任何指定的预检检查。根据请求将服务经理访问权限恢复为所属帐户。不可用的管理器会发出警告并跳过自动服务重启；所有权拒绝需要在重试之前解决报告的不匹配问题。
- 如果安装路径不同，请在考虑重新安装之前对齐入口点。在Windows上，使用`Get-Command openclaw -All`和`Get-Command node -All`；在 macOS/Linux 上，使用 `type -a openclaw node`。通过预期安装的绝对启动器重试并遵循更新程序的恢复命令。单独更改 shell 的 Node 不会更新服务定义。

预检诊断可识别更新安装和二进制文件、检测到的运行时以及检查时的服务安装。未解析的服务路径意味着无法验证，而不是没有网关正在运行。较旧安装的更新程序会保留第一个升级跃点的原始消息。

## <a id="downgrade"></a> 降级

在使用 `openclaw update cleanup` 停用恢复原始版本之前验证升级和您的会话历史记录。降级软件包不会逆转配置或数据库迁移。一旦状态迁移超出旧版本支持的格式，支持的恢复将使用其匹配的 OpenClaw 版本恢复经过验证的更新前备份。

<Warning>
租户容器管理停用后创建的新共享状态数据库省略 `fleet_cells`。即使数字模式版本匹配，需要此表的旧版本也可能会拒绝它们。现有数据库保留旧的表和行，但仅此并不能建立降级兼容性。不要重建已停用的表或更改模式标记来绕过验证。继续使用当前版本，或使用下面的恢复过程使用其匹配的旧版本恢复经过验证的完整备份。
</Warning>

首选 `openclaw update` 进行升级和恢复。它验证目标，运行所需的 Doctor 迁移，并验证激活的网关。原始 `npm i -g` 替换不会保留以前的包或运行此恢复工作流程；使用`openclaw update`或[先创建备份](#before-updating-create-a-verified-backup)。

更新程序会在激活期间保留以前的软件包，并在恢复失败无法证明安装有效时保留它。迁移恢复原始数据和原始状态更新捕获将保留，直到显式 [update cleanup](/cli/update#update-cleanup)。这些是单独的恢复机制：清理不管理包或 Git 运行时备份，并且保留的迁移原始数据不是完整的更新前备份。保留更新报告中指定的每个恢复位置，直到验证安装为止。

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

包回滚检查文件哈希、inode 身份、权限、所有权和符号链接目标。它忽略常规 `node_modules/.package-lock.json` 文件（npm 将其记录为一次性缓存）以及可以在不更改保留字节的情况下更改的链接计数和更改时间。可执行的 `.bin` 条目仍然是验证的一部分。在原始更新过程中，不匹配会在故障事实和报告中记录最多五个不同的相对路径和字段名称（包括 `sha256` 表示更改的内容）。进程重新启动后的恢复会保留保存的摘要检查，但无法重建该条目列表。

此行为属于已安装的更新程序。较旧的更新程序（包括 2026.9.4）可以在目标版本运行之前拒绝程序包或启动器验证，并且无法从候选版本获得这些诊断信息。如果第一个更新被阻止，请使用安装的 [ 手动包管理器更新过程 ](/install/updating/update-methods#alternative-manual-npm-pnpm-or-bun)。

对于可以读取当前状态的目标，预览并使用托管回滚路径：

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

更新程序检查兼容性并要求降级确认。如果保存的通道是 `extended-stable`，则添加 `--channel stable` 以获得精确的一次性标签。支持的目标完成配置编写器标记、重新启动服务并验证正在运行的版本。较旧的目标可能缺乏最终确定或迁移延续合同；如果激活被拒绝，请按照打印的恢复指南进行操作。不要绕过较新的架构或较新的配置拒绝。

当更新报告识别出保留的原始文件时，请在清理之前使用相应的 [Doctor 恢复命令 ](/cli/doctor#session-sqlite-migration)。恢复旧会话工件不会反转 SQLite 架构或恢复仅在 SQLite 中创建的会话。如果旧版本无法读取当前状态，请使用 [ 恢复完整存档 ](/install/backups#restore-a-full-archive) 恢复更新前备份。在恢复状态的激活过程中保持网关和其他编写器停止，并首先单独保留当前状态：恢复会放弃自备份以来所做的更改。通过安装的包管理器重新安装匹配的包；备份存档不包含该包。

完整的恢复点必须同时涵盖这些内容：

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

从一个备份生成中恢复该集。请勿将更新前的配置或共享数据库与更新后的每个代理数据库相结合，反之亦然。模型身份验证配置文件及其状态在每个 `openclaw-agent.sqlite` 中都是权威的。名为 `auth-profiles.json.sqlite-import.<id>.bak` 或 `auth-state.json.sqlite-import.<id>.bak` 的文件是保留的迁移输入或恢复工件，而不是实时凭据存储。在没有匹配的每个代理数据库的情况下恢复这些 JSON 文件不会恢复该代的身份验证状态。

使用 `openclaw backup create --verify` 进行验证的 WAL-aware 存档。切勿仅从实时 WAL 数据库复制主 `.sqlite` 文件：提交的数据仍可以位于 `-wal` 中。离线恢复已验证的统一数据库；请勿将其与其他数据库生成的 `-wal` 或 `-shm` 文件混合。有关存档覆盖范围和遗漏，请参阅 [Backup](/cli/backup)。

当预检拒绝启动时，具有 [startup 预检修复 ](https://github.com/openclaw/openclaw/pull/141451) 的版本会使配置、数据库和迁移输入保持不变。成功的开始可以使状态向前迁移。较旧的二进制文件可能会拒绝数据库架构和配置的 `meta.lastTouchedVersion`；更改任一版本标记都不会撤消迁移。用`openclaw doctor --fix --non-interactive`修复已安装的版本，或者使用上面的备份恢复。

在恢复期间，通过在网关环境中设置 `OPENCLAW_NO_AUTO_UPDATE=1` 来防止已启用的 [auto-updater](/install/updating/automatic-updates#auto-updater) 立即重新应用较新版本。

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

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

<a id="automatic-checkpoint-recovery" />

### <a id="full-state-recovery-requires-a-backup"></a> 全状态恢复需要备份

程序包更新将迁移前 SQLite 快照与程序包备份一起保留，直到验证成功的激活会删除该备份中的可恢复快照。即使成功激活后，无法密封源写入代的快照仍可用于手动恢复。回滚、失败或未经验证的完成以及拒绝恢复也会保留快照。如果清理无法完成，更新会报告保留路径的维护警告。较旧的快照目录不会自动删除：无法从现有收据中证明其所有权和成功结果。 Doctor 报告较旧的 npm 快照目录及其大小和删除命令。确认没有更新正在进行，并在手动清理之前检查相应的更新报告和恢复状态。如果在捕获期间确认网关已停止，则仅当数据库写入指纹通过 Doctor 和恢复保持不变时，从未允许启动的失败候选者才能在包回滚之前恢复这些数据库。维护所有权无法识别独立的 SQLite 写入者，因此 Doctor 期间的任何更改（包括 Doctor 自己的写入或新创建的数据库）都会使这些快照仅可用于手动恢复。在 Doctor 期间或 Doctor 完成后，捕获和 Doctor 入院之间的更改会保留当前数据库并报告 `state-migrated-no-rollback` 以及快照位置和 Doctor 恢复指南。如果没有Doctor写入证据，回滚需要最后验证的数据库世代保持不变。快照捕获首先将本地 SQLite 写入器置于维护所有权之下，因此稍后写入器关闭不会被误认为是干预写入。在该所有权下，capture 会私下复制每个数据库文件系列，而不是打开源文件，因此退出的编写器留下的 WAL 文件不会在捕获期间被误认为发生了更改。安装的更新程序拥有此顺序；暂存较新的候选程序无法更改已经运行的较旧的更新程序。在跟踪这些指纹的同时，新版本的 Doctor 还通过私有副本读取数据库以进行模式检查。因此，在写入之前失败的 Doctor 会使快照保持可恢复状态，并且包会回滚。在 Windows 上，符合条件的捕获首先运行回滚所使用的相同本机 SQLite 排除检查。这会在记录写入指纹之前解决所有保留的 WAL，因此稍后的检查清理不会被误认为是其他写入器。如果另一个连接阻止排除，快照仍可用于手动恢复。网关可能仍在写入时拍摄的快照仅可用于手动恢复，直至验证成功激活，即使稍后退出。迁移的文件保留为 `<database>.migrated-<runId>` 以供检查，报告会命名快照和移位的文件。有关磁盘要求和生命周期检查，请参阅 [ 恢复限制](/cli/update/how-updates-run#recovery-limits)。

数据库恢复保留当前更新历史记录，包括捕获后记录的故障详细信息。保留的原始快照保持不变。

这需要修复的更新程序来驱动更新；已经运行的旧驱动程序无法从候选驱动程序获得数据库回滚。可能已服务的候选人保留现有的拒绝以避免丢弃新的写入。仅更换其软件包无法逆转迁移。使用经过验证的更新前备份及其匹配版本进行有意降级。更新程序不会创建或重播全状态检查点。

现有的挂起检查点恢复记录会阻止进一步的可变更新。更新程序报告它不受支持，并保持其记录、备份和状态不变。请勿删除或更改保留的工件以强制进入干净状态，也不要使用 `update finalize` 来绕过拒绝。保留报告的位置以进行兼容的恢复实施或独立验证的备份。中断或拒绝的恢复并不是成功的回滚。

### <a id="automatic-schema-neutral-rollback"></a> 自动模式中立回滚

如果新激活的软件包验证失败，`openclaw update` 会将共享和受影响的每个代理 SQLite `user_version` 值与其激活前值进行比较，并检查配置文件是否仍与新版本的激活 Doctor writer 报告的内容匹配。当激活或验证期间首次创建的数据库的版本与该数据库类型的新版本支持的版本匹配时，该数据库是架构中立的。更改的架构版本或缺少预先存在的数据库，或者外部版本的新数据库仍然会阻止回滚。在恢复代码之前，更新程序还会检查以前的包是否支持任何新数据库；未知或不兼容的支持拒绝使用 `rollback-state-unverified` 进行回滚。当两项检查都通过并且在更新之前验证了保留的先前包时，它会停止新版本并恢复上一代：包、命令填充程序、服务定义和确切的预激活配置字节，包括先前的编写器标记。配置替换使用仅限所有者的权限（`0600`）；未更改的配置无需写入。拥有的、可写的服务元数据被刷新；受保护的服务定义被保留。 CLI 再次验证重新启动的先前网关的服务运行状况、version/build 身份、插件、通道和 `/readyz`。更新验证不使用模型推断：托管服务必须正在运行并拥有其端口，并且网关问候握手必须与预期工件匹配。

新版本的主配置文件中的 Doctor 迁移及其 `$include` 文件不会阻止回滚，包括全新安装的第一次更新。更新程序保留 Doctor 之前的配置，并验证 Doctor 在进行更改之前消耗了这些捕获的字节。它还根据 Doctor 的作者报告的输出哈希检查每个当前文件。仅当两个哈希值匹配时，回滚才会恢复原始字节。恢复会保留正常的配置写入器锁，并在获取文件后重新检查它们。操作员在激活块恢复后进行的编辑，包括 Doctor 读取配置之前以及 Doctor 的最后写入和更新程序捕获之间的编辑。更改的包含路径也会阻止恢复。仅保留根文件的较旧更新程序切换仍然需要包含内容保持不变。现有的有意恢复津贴仅适用于服务命令，因此较旧的二进制防护不会阻止恢复；它永远不会保存在配置或服务环境中。

缺失或畸形的内容不会阻止 Doctor 运行。当更新程序无法捕获完整的包含图时，它会警告自动配置回滚不可用，并在更新失败时保留任何 Doctor 修复。

成功的恢复使以前的网关继续运行，并以 `rolled-back` 的形式完成运行，其中 `after.version` 设置为以前的版本，并从服务停止到经过验证的恢复测量停机时间。标题为`↩️ OpenClaw update rolled back to <previous>: <reason>`，保留原来验证失败的内容。该命令仍然以非零值退出；恢复不会将被拒绝的版本转变为成功的更新。

恢复报告将恢复的包文件与正常的网关区分开来。经过验证的回滚会命名恢复后提供的版本，包括需要额外修复的时间。如果恢复的服务健康检查失败，结果记录`recovery.service: "failed"`；报告称健康状况不佳，并包括记录的恢复原因。仅当验证无法运行或完成时（例如就绪超时），运行状况才会报告为未经验证。这两种结果都会引导您前往 `openclaw gateway status --deep` 以检查服务版本和准备情况。回滚使用与更新的激活检查相同的启动限额。重新启动通知保留恢复的运行时可以理解的恢复字段。详细的恢复原因保留在更新结果、状态诊断和故障报告中。

使用 `openclaw update status` 记录原因，使用 `openclaw triage` 诊断失败的检查。恢复指南根据最新的服务观察报告网关是正在运行还是已停止。当网关回答更新的目标版本时，该观察结果将取代保存的运行时验证重新启动警告；原始失败的运行和任何迁移回滚限制都会保留记录。不安全的 Doctor 流程结算将保留其恢复指导，直到恢复所有者验证结算；仅响应网关无法清除该拒绝。恢复的网关必须通过自己的验证检查，然后才能以 `rolled-back` 的形式完成运行。

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

自动 CLI 分类永远不会遵循经过验证的回滚；它仅在更新结束失败时运行。在交互终端中，可以选择“**诊断更新失败**”、“**报告更新失败”**或“**退出”**，默认选中。报告显示经过清理的预览，并需要在创建问题之前单独确认。跳过或取消不会开始诊断或提交报告。 JSON、`--yes`、非交互式和托管服务切换调用在回滚后不会显示此菜单。

如果激活 Doctor pass 后配置文件发生更改，或者在符合条件的预启动恢复后数据库仍然不兼容，则回滚将被拒绝，并显示 `state-migrated-no-rollback`。对于配置编辑，下一个操作会命名其更改阻止恢复的文件。更新程序保留失败的结果和迁移的状态。可选的 [ 故障后分类 ](/install/updating#unattended-repair-on-your-own-inference) 可以在更新所有权和服务补偿解决后（包括失败回滚后）运行。在考虑旧版本之前，请使用打印的诊断和特定于安装的修复命令。分类不会将失败的更新重写为成功。

在 macOS 和 Linux 上，如果 Doctor 在迁移后超时，更新程序将停止其跟踪的进程组并等待每个组消失，然后再尝试恢复。一旦解决被证明，它就可以在保留的迁移状态上启动已安装的候选者并验证网关的健康状况。报告保留Doctor故障，记录维护警告，推荐`openclaw update repair`；恢复并不声称未完成的医生修复已完成。如果任何写入者仍然存在或无法解释，报告会命名已知的 PID 并使网关保持停止状态，因为并发写入会使数据面临风险。即使原始更新程序已退出，以后的更新尝试也会保留此块。在重试修复之前，保留恢复快照并遵循报告的流程检查指南。安装的更新程序拥有此过程监督：由 2026.9.5 驱动的首次更新仍然受到该年长父级的结算检查的限制。

在启动保留的候选者之前，更新程序会根据候选者的合同检查共享的和现有的代理数据库模式。如果在失败的 Doctor 停止后迁移仍处于待处理状态，它将在 Doctor 的维护和备份保护下再次运行候选 Doctor，然后在重新启动网关之前检查完成情况。被拒绝或不完整的修复会保留在更新报告中，并附有原因和命令 `openclaw doctor --fix`，后跟 `openclaw gateway start`。此修复永远不会降级较新的数据库架构。即使恢复恢复服务，原始更新失败仍会被记录。当网关再次启动时，会发送持久重启通知。

自动回滚会恢复代码和捕获的配置，并仅在确认网关在捕获期间停止并且候选者从未被允许启动时恢复迁移前数据库快照，并通过 Doctor 和回滚匹配写入指纹。用于检查迁移的临时快照将在验证后删除，并且不会替换您的备份。如果模式比较无法完成，则拒绝自动回滚（`rollback-state-unverified`）。更新程序捕获创作的配置并包含文件，而无需打开迁移的状态；新安装的版本拥有迁移后的状态验证和最终报告，保留相同的运行 ID 和记录的激活步骤。

对于pnpm和Bun，暂存后对同级全局包的更改拒绝自动回滚（`rollback-project-changed`）而不恢复共享项目；保持安装可访问的版本，否则保持网关停止并按照报告的修复命令进行操作。实时交换之前的拒绝将重新启动未更改的网关并保留同级更改。

### <a id="before-updating%3A-create-a-verified-backup"></a><a id="before-updating-create-a-verified-backup"></a> 更新前：创建经过验证的备份

`openclaw update` 保留自动更新前配置副本，而不是全状态恢复点。在进行重大更新之前，显式创建独立的经过验证的备份：

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

归档清单会记录 OpenClaw 版本以及备份中包含的源路径。归档可能包含凭据、身份验证配置和频道状态，因此请使用仅所有者可访问的权限存储它，并采用与实时状态目录相同的保护措施。有关已包含和有意省略的文件，请参阅[备份](/cli/backup)。

对于包含可移植存档省略的易失性工件的逐字节恢复点，请停止网关并使用平台提供的文件系统、卷或 VM 快照。这对于较旧的文件支持安装很重要：可移植存档会忽略匹配的 JSONL 转录本和日志，即使它们不再被写入。

迁移大型旧历史记录时，请同时为原始文件、临时 SQLite 假脱机和目标 database/WAL 留出空间。 SQLite可以比原来的JSONL大；流式导入并不意味着固定的 RAM 要求或迁移时间。检查系统临时卷和状态卷上的可用空间。有关暂存和内存详细信息，请参阅 [Session SQLite 迁移](/cli/doctor#session-sqlite-migration)。

## <a id="if-you-are-stuck"></a> 如果遇到问题

使用打印的安装特定命令或保留相同的配置文件和 state/config 覆盖，在网关主机上的终端中运行 `openclaw triage`。它按以下顺序打开第一个可直接启动的编码代理：Claude Code、Codex、OpenCode，然后是 Pi。代理接收本地诊断信息和任何记录的失败更新结果，以便它可以使用正常的身份验证、沙箱和批准设置修复安装并验证网关运行状况。使用 `openclaw triage --agent codex` 选择特定代理。

失败的交互式更新在更新程序清理后提供分类，并在新的诊断延迟切换之前将捕获的故障传递给代理。在启动之前，OpenClaw 显示代理、已保存的提示路径（如果可用）以及使用您自己的 account/tokens. 只有确认“是”才会继续。输入 `n`、取消或 30 秒无应答会跳过启动、打印手动恢复命令，并保留诊断信息和失败更新的退出状态。显式 `openclaw triage` 不要求此确认。 JSON、`--yes` 和没有 TTY 的更新调用永远不会启动修复代理。它们保存诊断信息并打印 `openclaw triage --run --update-result <path>` 以进行明确的选择修复。托管切换和前台 `gateway run` 启动失败也仅收集诊断信息。仅用于诊断收集，请使用 `openclaw triage --non-interactive`；添加 `--update-result <path>` 以包含已保存的更新失败工件。有关命令格式和安装目标，请参阅 [Triage](/cli/triage)。

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

使已停止、未经验证的网关保持停止状态，并在修复期间保留迁移状态。架构迁移后保留的可访问版本可以在您诊断时继续提供服务。即使代理修复了失败的更新，它也会保留其非零退出代码。

- 对于使用 `openclaw update --channel dev` 的源码检出版本，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后再次运行更新。
- 参见：[故障排除](/gateway/troubleshooting)
- 在Discord中询问：[https://discord.gg/clawd](https://discord.gg/clawd)

### <a id="unattended-repair-on-your-own-inference"></a> 无人值守维修自行推断

更新、验证、验证和回滚不需要推理或模型认证。不可用的模型路线无法阻止这些操作。验证失败会丢弃暂存的候选者，而旧网关继续服务。激活后，更新程序首先完成其现有的兼容性检查回滚和服务补偿流程。

符合条件的失败更新可以在更新所有权释放后启动一项自有分类修复。分类的目标是保留的安装，保留迁移的状态，并保留原始失败更新的结果和非零退出代码。成功的修复不会追溯发布成功的更新或经过验证的回滚。来自旧更新程序的报告仍然可以包含 `repairing` 阶段及其尝试摘要。

已发布的 2026.9.4 更新程序可能会在更新解决之前调用候选者的修复工作人员条目。新候选者保留其响应协议，但报告推理修复在不加载模型或更改操作员状态的情况下不可用。已发布的驱动程序仍然拥有第一次更新的控制流和预算。

要使用配置的推理进行显式修复，请在网关主机上的终端中运行 `openclaw triage --run`。 Triage 运行 Doctor 运行状况检查，在时间和工具调用限制下尝试最多一次嵌入式修复，然后再次运行 Doctor。它使用正常的运行时凭证解析器，包括继承的配置文件和 OAuth 刷新；不可用推理会产生外部切换而不是登录提示。修复保留了现有的安装范围和工具策略限制。

保存的激活或恢复失败还需要记录更新程序完成情况以及当前安装和网关验证。归因于 Doctor/config 的拦截器可以通过新的 Doctor 检查和记录的安装身份来解决，而其历史失败运行保持不变。本机服务激活和恢复保留其现有的权限检查。有关安装目标、修复限制和验证结果，请参阅 [Triage](/cli/triage#installation-target-and-embedded-handoff)。