修复和恢复

更新失败时会发生什么，以及用于完成收尾工作的子命令。这是 openclaw update 参考的一部分。

恢复失败的更新¶

在交互式更新或修复失败后，OpenClaw 会完成清理，并提供 诊断更新失败、报告更新失败 或 退出。报告操作会预览已清理的问题正文， 并需要单独确认。

意外异常会保留已知的更新模式、已解析目标、失败步骤以及任何已记录的恢复结果。 报告通过失败命令相同的诊断机制包含有限且已脱敏的错误代码或名称以及首行消息； 无法识别的私有文本和堆栈跟踪不会包含在公开预览中。

选择 诊断更新失败 会打开 Triage，它会按以下顺序启动 PATH 上第一个可直接启动的编码代理：Claude Code、Codex、OpenCode，然后是 Pi。 它会直接传递捕获到的更新失败，并将新的 Doctor 检查和诊断收集交给代理， 因此损坏的安装不会延迟交接。代理保留其现有的身份验证、沙箱和审批设置。

代理在操作员的原始工作目录中启动；如果该目录不再可访问，则在其操作系统主目录中启动。 失败安装的已解析状态、配置和默认工作区路径在修复期间保持固定。

经过验证的回滚会让上一代继续运行。交互式菜单默认选择 退出； 拒绝或取消会保留失败更新的非零退出状态。在验证回滚后，--json、--yes、 非交互式以及托管服务交接运行不会提示或收集自动诊断。

对于没有验证回滚的失败，使用 --yes、--json 或非交互式会话 （包括管道输入或输出）的更新会收集诊断并打印交接命令，而不会启动外部编码代理。 符合条件的失败可以在更新所有权和服务补偿稳定后，在已配置的推理上启动 失败后分诊。 使用 --json 时，分诊输出会写入 stderr，因此 stdout 保留原始更新结果。 诊断收集失败永远不会掩盖更新失败。

对于后台或 Control UI 失败，请使用 Gateway 主机上打印的特定于该安装的命令。 打印的命令在 Windows 上使用 PowerShell，在 macOS、Linux 和 WSL 上使用 POSIX shell。 手动运行分诊时，请保持相同的配置文件以及状态/配置覆盖：

openclaw triage
openclaw triage --agent codex

使用 openclaw triage --non-interactive 可在不启动代理的情况下收集诊断。 添加 --update-result <path> 以包含已保存的更新失败工件。

验证失败不会改动正在服务的 Gateway。如果停止托管服务将其卸载，然后在激活前失败， OpenClaw 会在重新检查服务所有权后尝试恢复已验证的原始运行时。激活后， 如果数据库架构未更改且配置文件仍与候选项的激活 Doctor 输出匹配， 则失败的验证可以 恢复上一个包。 保留已迁移的状态和历史记录；仅替换代码无法撤销迁移。即使修复成功， 原始失败更新在代理完成后仍会以非零状态退出。

激活成功后，读取或发布更新报告的失败会保留已更新的安装。 报告失败不会触发包回滚。当必需的最终处理无法完成时，命令仍会以非零状态退出； 在拥有该更新的更新器退出后，请遵循其恢复指导。

激活 Doctor 会在其自身的实时维护范围内重新检查聊天请求者的权限。 这使它在状态数据库离线修复期间能够读取授权策略，而不会授予对无关操作的访问权限。 即使较旧的更新器启动 Doctor，候选项也会提供此修复。

支持数据库回滚的 Git 更新器会在激活 Doctor 之前对已停止安装的数据库进行快照。 如果 Doctor 失败，已验证的快照会在恢复之前的源、运行时、配置和托管 Gateway 之前 恢复迁移前的状态。Doctor 会将已接受和已确定的数据库代际记录到该备份中， 因此其自身的迁移不会阻止回滚。后续的操作员或运行时写入会阻止破坏性恢复： 更新器会保留这些写入，在已迁移的安装上重启并验证 Gateway， 并在下一次 Doctor 命令中报告拒绝。所有权丢失仍会阻止未授权的影响， 并保留恢复工件。此回滚支持属于已安装的更新器；新的候选项无法将其添加到 已在运行的较旧更新器中。

试运行以及被初始参数、外部监督者、状态存储所有权、交接身份或不可变配置检查拒绝的 命令不会收集诊断或启动代理。一旦这些检查通过，失败的元数据、架构、运行时和 托管服务检查即使安装被阻止也会使用上述失败操作。这包括无法安全停止其父 Gateway 进程的更新。诊断会保留该拒绝：它不会停止 Gateway、重试更新或绕过安全检查。 参见 更新故障排除。

原始状态捕获¶

在新的直接 CLI 更新写入运行时状态之前，已安装的更新器会尝试保留原始配置、 其包含项、本地数据库以及声明的插件迁移资源。捕获会保存在所选状态目录旁边的 <state-directory>.update-captures/<run-id> 中。Doctor 继续操作会保留同一捕获； 它们不会用已迁移的状态替换它。状态目录迁移会保持其原始位置和已记录路径不变。 继承的控制平面和托管辅助运行保留其现有捕获行为。独立的 doctor --fix 会保留单独的修复前副本；该副本不会替换之前更新的原始文件。

这些捕获结果是手动恢复的依据。活动写入方可能在捕获期间更改状态；观察到变更会使捕获不完整并产生警告。该集合并非跨活动存储的原子快照。缺失、不可读或不完整的捕获不能构成安全的回滚点。更新进程会保持可选的 debug-proxy 持久化处于禁用状态，因为其更新历史可能使用较旧的数据库模式。Doctor 在保留原始文件并接受修复后的模式后，可以恢复捕获。因此，跳过 Doctor 的成功更新可能会在本次调用中保持本地 HTTP 跟踪处于禁用状态。直接更新（包括 --dry-run）在启用调试捕获时会报告此限制。

使用 openclaw update status --json 检查保留的证据。运行时回滚并不能证明较早的原始捕获已被恢复。只有当恢复证据标识了该捕获的清单时，状态才会将其报告为已恢复。独立 Doctor 副本显示为 manual；它们的存在并不记录修复成功或失败。未完成的捕获会与有效捕获一起显示为 incomplete，带有其目录且没有密封的清单引用。在尝试恢复之前，请保留当前数据并检查原始文件。较旧的已安装更新程序可能不会保留或转发原始捕获；较新的 Doctor 会报告该限制，而不是将当前字节视为更新前状态。当您需要完整的恢复副本时，请在升级前进行已验证的备份。

保留的更新程序运行时¶

更新可以在安装目录旁或系统临时目录中的 openclaw-update-runtime-* 目录中保留其运行代码。更新程序在成功、失败、异常或 SIGINT/SIGTERM 后（包括报告结果时的失败）会排空其工作进程并删除该目录。如果某个工作进程无法排空或删除失败，它会记录 Runtime retained at <path>: <reason>，并将清理工作留给 Doctor。清理警告不会取代原始更新结果。在清理排空期间，此前的非零退出仍保持非零。变更和恢复所有者仍必须排空；即使打印的命令结果是成功的，它们的失败也会产生非零退出。

保留操作会复制插件清单以及插件安全检查所检查的文件，因此保留更新程序不会使检出中的插件在硬链接验证时失败。在支持的情况下，其他运行时文件仍保持硬链接。

这些生命周期和复制变更仅在已安装的更新程序支持时才适用；安装更新的候选版本无法更改已在运行的更新程序。在该更新程序退出后，从原始检出运行较新的 openclaw doctor --fix，以定位其同级运行时目录。Doctor 还会检查已知的临时目录，包括托管服务的 TMPDIR、TMP 和 TEMP。相对服务路径需要其记录的绝对工作目录。在同一存储中发生版本化包根目录变更后，旧版 pnpm 投影仍可识别；查找限制为 4,096 个直接投影存储条目。已识别的运行时投影是可丢弃的；当不再有任何工作进程使用它们时，Doctor 会将其删除。如果无法验证所有权或进程存活状态，Doctor 会保留该目录并报告原因。

候选 Doctor 堆栈溢出¶

通过聊天触发的对 2026.9.6 的更新可能会失败，并显示 authority-check-failed: Maximum call stack size exceeded，有时前面会出现 Update history reconciliation could not complete。这是候选 Doctor 的 authority-check 缺陷；它可能在首次更新时发生，无需迁移状态或之前失败的运行。纠正性候选版本可以通过已安装的更新程序运行，保留的历史记录完好无损。运行较旧安装中的独立 Doctor 无法修复候选包中的代码。

没有受支持的命令可以重置保留的更新历史。update repair 会完成被中断的收尾，而 update cleanup 会淘汰符合条件的恢复原始文件；两者都不会清空运行账本。请保留历史和备份，而不是通过删除数据库行来绕过此失败。

update repair 修复¶

在核心包已经更改但后续修复工作未干净完成时，重新运行更新收尾。当 openclaw update 安装了新的核心包，但核心后插件同步、受管 npm 插件元数据、注册表刷新或 doctor 修复未能收敛时，这是受支持的恢复路径。

openclaw update repair
openclaw update repair --channel beta
openclaw update repair --json
openclaw update repair --accept-capabilities

当更新、核心后延续或修复在 Bun 下运行时，其 OpenClaw 维护子进程会使用同一个 Bun 可执行文件，包括全新的 Doctor、配置验证、就绪检查、完成以及非交互式失败诊断。托管服务的运行时选择仍由服务定义及其 runtime pin 决定。

如果较旧的更新程序发布了新的核心，但随后报告 update-executor-settlement-failed 并带有 Parent executor is suspended for its candidate.，请等待该更新程序退出，然后在已更新的安装中运行 openclaw update repair --yes --json，保留其配置及 state/config 覆盖项。这会通过新的所有者完成 Doctor 和核心后收敛。在通过其服务所有者重启已停止的 Gateway 之前，请检查修复结果。更新候选版本无法更改已在内存中的较旧更新程序。

如果受管 Gateway 在独立修复之前已经停止，修复会使其保持离线，并警告您必须运行 openclaw gateway start 才能将其启动。如果其服务定义指向不同的安装，修复则会报告该安装的修复命令。这些维护警告也会出现在 postUpdate.doctor.warnings 中；否则，成功的收尾会报告 status: "warning" 并以成功状态退出。

未触碰的、无标识的 2026.9.2 时代的更新准入会在超过 24 小时后自动恢复。Gateway 启动、openclaw update status 和 openclaw status 会将该行保留为已放弃的失败，原因为 legacy-driver-expired，并建议运行 openclaw update 重试。Control UI 在拒绝挂起的配置写入之前会刷新 Gateway 的恢复分类，因此过期的孤儿不会持续阻止设置或提供商登录。实时更新和待处理恢复仍受保护。此形态无需显式修复。

update repair 首先检查过期更新历史。当已安装的 Gateway 代际健康，且唯一剩余问题是非活动账本行时，修复会记录 failed / abandoned 并成功退出，无需 Doctor、维护或服务停止。openclaw status 和 Control UI 随后报告该已放弃运行为已对账，没有失败警告或重试提示；其历史失败记录保持完整。它还会在对账后 30 分钟内一次性确认 Gateway 已对账的行。后续修复调用使用完整最终化，因此历史恢复不会抑制插件收敛。成功修复会确认 Doctor 最新 100 条历史记录中所有未处理的已放弃运行，无论其年龄或是否存在较新更新。原始失败结果仍被记录，包括其目标构建未知的情况；确认后 Doctor 停止重复修复指令。当所有已记录的更新器进程可证明已死亡时，显式恢复不会等待 30 分钟（其 PID 已消失或其进程启动标识已改变）。无标识的行以及采用者未记录的运行仍需要超过 30 分钟的不活动；已记录的存活或不可检查的驱动会阻止放弃恢复。JSON 输出在 reconciledRuns 中识别已对账的运行 ID，其中 status: "ok"、mode: "repair" 和 restart: false。

修复还会确认一个未触碰的包安装：如果其更新因包管理器所有者未知而被拒绝，且已安装版本达到或超过解析目标。这包括错误地将该拒绝记录为更新失败的旧更新器。原始拒绝详情保留在历史中；修复会清除失败提示，无需 Doctor 维护或服务重启。已达到安装或最终化的运行仍需要正常修复。

新的 Doctor 子进程以现有的外部服务修复策略运行，因为更新器负责服务变更。它们保留操作员的 OPENCLAW_SERVICE_REPAIR_POLICY=external 选择，并保留 Gateway/state 协调器和 agent-database 租约检查。外部部署所有者仍负责停止和重启其 Gateway。

自动修复会完成其嵌入式 agent 回合，并在要求更新所有者运行 Doctor 或 update repair 之前释放该回合的数据库和进程资源。这可防止修复 agent 自身的凭据写入阻塞维护。其他存活的 agent 租约仍会阻塞修复。维护会保留原始 Gateway 激活意图，包括 --no-restart 和有意停止。仅成功维护命令本身不会验证原始症状。

在所属更新内部调用的修复，当其继承的运行 ID 和实时进程标识与该所有者匹配时，可以继续。独立修复会为其新运行记录相同的延续，并将该运行 ID 传递给其 Doctor 子进程。修复父进程使用 Doctor 的维护生命周期停止受管的 Gateway，然后在运行 Doctor 子进程之前释放其数据库锁。子进程在不停止或重启服务的情况下修复状态。父进程在收敛后恢复并验证同一服务，包括当某个 Doctor 子进程失败时。已停止的服务保持停止状态。在执行每个原生操作之前，都会重新验证服务所有权和调用运行。恢复失败会指明原因以及用于检查和重启 Gateway 的命令。正常更新最终处理仍会将激活权留给其外层更新器。

如果 Doctor 报告更新父进程必须停止受管的 Gateway，请等待该更新退出，然后运行 openclaw gateway stop，并在独立 shell 中使用相同的 profile 和状态/配置覆盖重试 openclaw update repair。在 macOS 上，stop 会卸载 LaunchAgent 并验证其进程已退出。成功停止后仍加载的服务或存活的 PID 属于服务关闭失败。如果 stop 无法卸载服务，请使用拒绝信息中打印的精确 launchctl bootout 命令，从拥有该服务的用户已登录的 macOS GUI 会话中执行。

一个无关更新，如果其驱动进程处于活动状态或无法检查，仍会阻止修复，即使已经长时间没有活动。手动 doctor --fix 也会拒绝在该更新处于活动状态时停止服务。拒绝信息会标识所属运行、阶段、驱动 PID、主机、开始时间和最后活动时间及其持续时间，以及观察到的存活状态（alive 或 not observed）。请等待该更新完成，或者在其主机上停止指定的驱动进程，并在其退出后重新运行 openclaw update repair。仅凭经过的非活动时间并不授权接管一个活动更新器。

显式的通道或能力变更以及已知的未完成核心后工作会使用完整最终处理。已记录的激活、重启、验证或最终处理步骤要求达到该收敛，即使 Gateway 已经协调了该运行。修复会检查较新的失败核心后历史以及活动行，包括失败原因为空的较早最终处理尝试；较早的过期行不能向较新的更新隐藏未完成的工作。如果有限历史检查不完整，修复也会使用完整最终处理。父进程会在 Doctor 进入维护之前停放其拥有的服务；Doctor 子进程不能从更新父进程处接管服务激活。 成功的完整最终处理随后会协调所选的过期行，并确认在修复准入时捕获的最近 100 条历史行中未确认的已放弃结果。这些结果不必是最新运行，也不必少于 30 分钟；时间限制仅适用于跳过完整最终处理。额外的历史结果需要完整最终处理，即使最新行符合轻量修复条件。历史失败及其详细信息保持完整；确认会清除它们的 Doctor 修复提示，而不是清除其失败状态。捕获历史窗口之外的行以及在修复期间准入的新运行不会被该调用确认。 收敛失败会保留所选行。如果任何所选运行在对账之前恢复，整个选择都会被保留。当行被选择用于恢复时，完整最终处理 JSON 会包含 reconciledRuns，列出该调用新确认的 ID，包括已终止的放弃行。带有非致命警告的成功收敛也会确认这些行。延迟维护会保留所选历史和待处理迁移义务。

对于完整最终处理，update repair 会运行 openclaw doctor --fix，重新加载修复后的配置和安装记录，同步活动更新通道所跟踪的插件，更新受管理的 npm 插件安装，修复缺失的已配置插件载荷，刷新插件注册表，并写入收敛后的安装记录元数据。 如果插件迁移仍处于延迟状态，最终处理会在释放安装记录所有权后运行另一个全新的 Doctor，即使没有插件包发生变化。这可以让一个已修正的本地插件在同一次修复运行中完成其待处理确认。当兼容性检查阻止发现时，Doctor 会保留插件的配置，因此修正插件不需要重新创建其允许列表或启用条目。 在更新后修复期间，版本跟随 OpenClaw 的已配置运行时插件会针对新安装的核心进行检查，即使更新器进程是在上一个版本上启动的。 它不会安装新的核心包，也不会请求更新激活。修复父进程会恢复其为维护而停止的服务，如上所述。 面向人类的输出以最终处理结果结尾，该结果区分完成、带警告完成和失败。

当修复发现已配置的 npm 插件载荷但无法恢复其安装记录时，它会从所选注册表源重新安装，使用活动通道或精确版本固定。这需要注册表访问权限；如果验证失败，修复会保留现有载荷，并且不会发布新的安装记录。 注册表验证以及任何所需的能力审查会在修复后的安装记录发布之前完成。

当捆绑插件迁移到外部包时，失败的迁移会报告替换载荷未安装，并保留底层错误。在重试 openclaw update repair 之前，请解决该错误。 Doctor 和更新修复会重新安装缺少包文件或报告缺少运行时条目的已配置载荷；空目录不算成功安装。回滚会在暂存文件清理后移除空的受管理 npm 项目。即使源检出也包含同一插件的捆绑发现副本，Doctor 也会保留外部伴随包及其安装记录。修复诊断必须标识已记录的包根目录；损坏的同 ID 源副本不会触发替换健康的受管理包。

With --json，标准输出包含一个 JSON 文档。Doctor 面板和其他诊断信息输出到标准错误，因此标准输出可直接解析。仅限插件的可用性、安装或加载失败会出现在 postUpdate.plugins.warnings；当必需检查通过时，最终化报告 status: "warning" 并成功退出。Doctor 维护准入拒绝在数据无风险时也以警告结束。修复会恢复其停止的任何服务，保留迁移为待处理状态，并指明下一个修复操作。修复写入开始后的错误、活动或未经验证的 Gateway、不可读状态、活动迁移写入、未完成的清理、无效配置以及失败的必需就绪检查仍会以非零退出。

已记录的待迁移警告在迁移所有者记录完成后停止出现。无关警告以及后续或重新引入的义务仍保持可见；原始更新历史得以保留。

在更新后或最终化工作失败且其子进程稳定后，OpenClaw 使用正常的启动和就绪预算探测已安装的 Gateway。更新历史和失败报告记录观察到的服务版本和就绪状态，包括前台 Gateway。因此，失败的最终化步骤可以报告 已验证的服务状态，同时保留其原始失败和修复指导。该观察不会重启 Gateway 或授予维护权限。失败的探测保留其特定诊断；仍在启动的 Gateway 保留该结果而不是被重启。如果命令清理仍不确定，运行保持打开并保留其恢复工件，而不是发布完成状态或启动另一个修复。

Doctor 修复使用与普通 Doctor lint 相同的已启用插件和默认检查选择。选择性启用的检查（包括受管理的 Codex 版本探测）不会在常规最终化期间运行。当通过 doctor --lint --only codex/managed-app-server 请求时，显式候选检查仍会运行。版本探测有五秒截止时间，在受支持的环境中终止其进程组，并在后代进程保留管道时限制输出排空。超时的探测不能仅因为其直接子进程成功退出而被接受。非致命 Doctor 警告出现在 postUpdate.doctor.warnings；当没有其他步骤失败时，最终化报告 status: "warning" 并成功退出。重启后，Codex 运行时就绪状态仍由其插件负责。

最终化（包括面向监督进程的 update finalize 命令）会立即在标准错误和更新运行账本中记录阶段开始和结束。预检准入、配置验证、配置备份和核心完成缓存预算会随共享 SQLite 数据库及其附属文件扩展，具有五分钟启动宽限和保守的磁盘吞吐量。修复 Doctor 及其包含的收敛阶段没有自动实际时钟截止时间。插件后配置和就绪检查在 Doctor 完成后共享一个从现有共享和发现的代理数据库族派生的预算，包括 WAL 增长。插件更新保留命令所有者的 20 分钟宽限；缺失插件修复保留其安装程序默认值。串行插件阶段和外层最终化进程不会增加相互竞争的默认截止时间。显式 --timeout 仍会覆盖每个阶段及其子命令。

阶段截止时间会产生退出码 1 以及包含 status: "failed"、stuckPhase、elapsedMs、error 和现有 phaseTimings 数组的 JSON。最终化器取消该阶段，阻止进一步写入，并最多等待相同预算使其工作稳定。修复会在报告失败并退出之前恢复并验证其停止的 Gateway。服务托管获取和恢复在阶段取消之外保留其自身的原生操作预算。账本记录一条警告，指明超时的阶段和预算。报告停滞更新时保留阶段诊断。

当新的 Doctor 在超时的阶段中运行时，doctorOutput 包含其 phase（pre-plugin 或 post-plugin）以及独立的 stdout 和 stderr 诊断。每个流报告 receivedBytes、lastOutputAgeMs（静默时为 null）以及脱敏后的 excerpt，上限为 256 个 UTF-8 字节。失败阶段的账本详情和标准错误在退出前保留相同的摘录。捕获限制为每个流 64 KiB；超过该上限会用 omitted: "capture-limit" 替换文本。不完整的私钥或脱敏错误也会省略流文本。较新的输出年龄表示已收到输出；它不能证明迁移已推进。输出和心跳不会延长阶段截止时间。这些诊断不能证明所有后代进程都已停止，并且不得用作回滚授权。

共享 CLI 释放器具有各自的五秒截止时间。失败诊断和任何交互式恢复会在十秒退出宽限开始之前完成。如果最终化器在该宽限之后仍然存活，标准错误和账本会记录活动资源类型和未完成的释放器名称，然后进程以记录的结局退出。保留的句柄不能无限期地扣留监督进程的结果。 两个停滞诊断还包括 childProcesses：最多八个后代进程，包含 pid、parentPid 和可执行文件名（command）。参数、环境变量值和可执行文件路径会被省略。childProcessesTruncated 表示存在被省略的条目；childProcessInspection: "unavailable" 表示无法读取进程列表。command 为 null 表示该进程的可执行文件名不可用。检查仅在停滞发生后运行，并最多为退出边界增加一秒。阶段失败 JSON 包含相同字段。报告被阻塞的子进程时，保留这些诊断和阶段回执。当其子进程可以在阶段预算内停止时，完成缓存刷新仍为尽力而为。超过总体截止时间的阶段仍会使最终化失败。

需要能力许可的插件工件，在未经交互式审查或显式 --accept-capabilities 的情况下不会被安装。单独使用 --yes 不会接受能力变更，JSON 模式也不会提示。未解决的审查会保留先前的插件负载，并以 PLUGIN_CAPABILITY_CONSENT_REQUIRED 结果出现在 postUpdate.plugins.warnings 中。当所需检查通过时，openclaw update 可以完成核心更新及请求的 Gateway 重启并返回 status: "ok"；update repair 在不请求更新激活的情况下报告 status: "warning"。两个命令都会成功退出。这也适用于捆绑插件移至外部包，或缺失的已配置插件尚无安装记录的情况；未经审查的替换件不会被安装。当可用且已启用的工件仍保持安装时，自动修复可将延迟替换报告为通知；该保留工件仍会经过负载验证。

如果核心包已发生更改，请在交互式终端中运行 openclaw update repair 以审查插件能力。审查更改后，自动化可以使用 openclaw update repair --accept-capabilities。接受仅适用于本次调用期间重新计算的每个工件的声明表面；它不会批准未来的能力新增。

跳过的旧版审计恢复¶

当旧版审计原始归档以追加之外的方式发生变化时，Doctor 会以 .quarantined-<date>-<id> 后缀将其保留在自身旁边。该警告会指明被隔离的路径，并解释预期的仅追加增长方式和观察到的变化。当空的原始归档没有检查点，但其已净化的伴随文件仍包含历史记录时，该原始归档也会被隔离。Doctor 会保留已净化的记录和现有的 SQLite 行，继续后续修复，并且不会在后续运行中重复该警告。隔离不会导入已更改的字节，也不会删除归档或备份。被隔离的原始归档保持本地状态，并被排除在可移植备份之外；已净化的伴随文件和保留的 SQLite 审计历史则正常备份。

当原始归档没有检查点且以不明确的空白字符开头，或无法获得另一个持久的原始归档检查点时，Doctor 可以将其他旧版审计源保留在原位。这些情况会产生带有警告的 skipped 迁移回执。其他修复会继续，更新最终化也可以在带有警告的情况下完成。不安全的恢复失败（例如无法恢复的中断归档）仍会停止 Doctor。

请保留报告的源、其已净化的伴随文件（例如，logs/config-audit.jsonl.migrated 旁边的 logs/config-audit.jsonl.migrated.raw），以及任何恢复日志或备份。在尝试恢复之前，请遵循备份指南，并在请求帮助时包含警告和归档文件名。不要删除或重写归档或检查点以抑制警告。

对于保留在原位的源，警告会在后续的 Doctor 或 openclaw update repair 运行中重复出现，直到归档得到解决。成功完成最终化并不表示这段历史审计数据已被导入。目前，当原始归档不可用时，没有受支持的仅净化导入方式：接受伴随文件作为恢复源需要显式的对账程序，以保留重复事件、保留的历史和检查点证据。

update cleanup¶

在确认升级和会话历史正常后，退役迁移恢复原件。从预览开始，预览可以在 Gateway 处于活动状态时运行：

openclaw update cleanup --dry-run
openclaw --profile work update cleanup --dry-run --json

清理操作针对选定的配置文件以及 OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH 覆盖项。它会显示该状态目录，且不会重定向到托管服务。请确认显示的目录就是您打算清理的安装。--dry-run 只读取配置和恢复元数据，不会打开数据库、获取维护锁、加载插件或创建状态。候选字节仍然需要身份验证；历史工件被单独列为需要验证。受保护和被阻止的工件包含原因代码。

在应用之前，请停止同一配置文件/状态目录的 Gateway，并等待其他 SQLite 维护命令完成。同时停止数据库读取者，包括反复运行 openclaw sessions --all-agents --json 的监视器，并保持它们停止直到清理退出。只读 SQLite 连接可能会创建或更改 WAL/SHM 侧车文件，即使会话内容未更改，也会使清理的目标检查失效。如果清理报告 Recovery destination database changed; preview cleanup again.，请停止这些读取者，重新预览，然后重试。清理需要独占的离线状态所有权，并且本身从不停止或重启服务。

openclaw update cleanup
openclaw update cleanup --yes --json

交互式确认默认为否。JSON 模式从不提示或授予许可；无人值守删除需要 --yes。许可不会覆盖所有权、文件身份或依赖检查。适用的标志（--dry-run、--yes 和 --json）可以在 cleanup 之前或之后使用；仅更新标志 --channel、--tag、--timeout、--no-restart 和 --accept-capabilities 会被拒绝。

只有具有完整导入证据且由所有者记录的恢复工件才有资格。未知或未导入的历史、格式错误的输入、轨迹、取证损坏的数据库、操作员备份和未清单化的工件仍受到保护。旧清单尽可能在离线状态下验证；缺少证据是保留工件的理由。清理没有自动过期策略。私有包、命令垫片和 Git 运行时备份仍归更新事务所有，并且不在本次迁移清理范围之内。更新历史中的中断条目不会阻止对其他符合条件的迁移归档进行清理。

JSON 结果包含 stateDir、status、artifacts 和 totals。每个工件报告其路径、运行 ID、逻辑字节、结果和原因。总计将候选项、需要验证、受保护、被阻止和已移除的字节分开。移除失败会以非零状态退出。保留恢复清单并重新运行清理，以完成已记录的中断工作；重试不会删除已重新创建的文件。已移除的逻辑字节不保证在克隆或快照文件系统中回收等量的物理空间。当无法检查某个路径时，如果可用，其逻辑大小来自已记录的工件元数据。清理在移除前记录持久化意图，并使用独占的无副本发布。失败会被报告；重试会协调已经完成的文件操作。清单文件在移除前同步；在受支持的情况下，父目录也会同步。Windows 不提供相同的父目录持久性保证。

Doctor restore 明确报告有意处置的原始文件和待清理项。更新和清理都不会创建自动的完整状态备份；这些恢复原始文件不是完整的升级前备份。有关备份覆盖范围，请参阅 更新前：创建经过验证的备份；有关恢复保留的原始文件，请参阅 Doctor 恢复。