跳转至

更新故障排除

失败的更新会在更新恢复稳定后进入内置 triage。在交互式终端中，OpenClaw 会显示所选代理、可用时已保存的 Prompt 路径，以及使用你自己的账户/Token，然后在启动 triage 前询问。只有明确的 Yes 才会继续。按 Enter、n、取消，或在 30 秒内未作答，都会跳过启动，并保留诊断信息和手动恢复命令。使用 openclaw triage --agent codex 选择另一个代理。使用 --yes、--json 或没有交互式终端时，符合条件的失败可以启动一次由其负责的自动修复；其他失败会保留诊断信息和交接命令。参见 自动恢复。原始更新失败和退出状态仍是权威依据；诊断不会将失败的更新变成成功的更新。

如果更新健康检查输出了完整的 lint 报告，但未在截止时间前退出，失败会将该完成状态与进程终止分开标识。已退出但输出管道仍保持打开的子进程会单独报告。如果没有完整的 lint 报告，截止时间不能证明检查已完成。当自动修复在开始修复回合前找不到可用的推理路由时，会被记录为已跳过；原始更新检查仍是报告的失败。

在 Control UI 中，失败的尝试会打开 Ask OpenClaw，并附带其记录的详细信息，要求它在重试前进行调查。连接丢失或验证超时会显示为未知结果。该标签页会记住最近 32 个已调查的尝试标识，并按其 Gateway 和配置文件限定范围。状态检查、在这些范围之间切换以及重新加载同一标签页，都不会自动再次发送这些调查。如果浏览器无法读取或保存该历史记录，失败详情仍会显示，但不会自动发起诊断请求。手动询问 OpenClaw，或在主机上运行 openclaw triage。如果 Gateway 或代理不可用，请在 Gateway 主机上使用 openclaw triage。自动诊断会保留你未发送的 composer 草稿，包括其对话会话必须重启时。

Control UI → 设置 → 更新 会保持最新记录的尝试可见，包括其时间、更新前/后标识、原因代码、失败步骤以及有界的诊断详情。当状态检查重新读取同一尝试时，版本或修订验证失败仍会保持可见。当预期版本或修订到达，或同一尝试报告其最终失败或取消时，未知验证结果会解决。更新的记录尝试也可以替换它。有意取消、已是当前版本的安装以及仍在进行中的更新不会启动 triage。

对于最终失败的尝试，报告更新失败 与 重试 和 Ask OpenClaw 是分开的。它会预览一份有界报告，其中包含 OpenClaw 版本、平台、更新目标、失败阶段、已脱敏的诊断信息以及已验证的回滚结果。报告不包含机密、Token、聊天内容、原始日志、私有绝对路径和恢复命令。在已识别的管理员确认该预览之前，不会提交任何内容。指定的管理员会收到一个预填的 issue，可在其浏览器中使用自己的 GitHub 账户进行审阅和提交。此路径永远不会调用主机的 GitHub CLI，包括用于身份验证或协调。连接 My GitHub 不会授予主机账户的发布权限。只有 Gateway 所有者或内部系统管理员才能授权现有的主机 GitHub CLI issue 流程。回退和待定结果会在本地保留已脱敏的报告；已确认的 issue 只保留其持久 issue URL。OpenClaw 首先使用当前活动的 github.com 账户发起一次静默的只读请求。如果缺少 CLI，或身份验证检查失败、不可用或超时，则会返回一个预填的 issue 链接，而不会开始创建 issue。在 Control UI 中，针对已记录尝试的中断准备工作可以在其本地预留过期后重试。一旦 issue 创建开始，超时、信号、非零退出码或没有经过验证的 issue URL 的格式错误响应，都会使该尝试保持待定状态，且没有重放链接，因为 issue 创建结果可能未知。该操作绑定到一个更新尝试标识，不能将该尝试提交两次；重新连接或刷新状态都不会自动报告它。CLI 报告错误会返回到显式操作菜单，并且永远不会代表用户启动诊断。

Control UI 修复仅使用类型化产品操作。当已连接的 UI 具备所需能力和范围时，它会优先使用经过身份验证的 Gateway 或原生操作，保留对破坏性操作的确认，并将终端命令作为次要的主机端回退。它永远不会解析本地化指导或执行任意命令字符串。

在 Control UI 中恢复

  1. 当 Gateway 已重启、断开连接或未报告最终结果时，选择 检查状态。这会读取 update.status；它不会启动另一个更新。在检查待定期间，恢复控件保持禁用状态，被拒绝的请求会作为错误显示在页面或更新对话框中。对话框在等待时显示 正在检查状态…，在成功读取后显示 状态已刷新。，即使记录的失败没有变化。如果 Gateway 已断开连接，请在检查或重试前重新连接。
  2. 打开 查看详情，并处理记录的失败步骤。诊断文本用于显示时有界且已脱敏；需要更多上下文时，请使用 Gateway 日志。
  3. 只有在原因解决后，才选择 重试更新。Control UI 使用正常的已确认更新流程，并说明在 Gateway 重启期间，正在运行的会话会被中断。

这些控件要求已连接的 Gateway、对相应类型化 Gateway 方法的支持以及管理员范围。当这些条件不满足时，请在 Gateway 主机上使用 CLI 回退。

Doctor 无法在最终化期间进入维护

finalize:doctor 可能会在 Gateway 仍拥有所选状态目录时报告 Doctor could not enter maintenance。正在启动的 Gateway 和健康的正在提供服务的 Gateway 会在其整个进程生命周期内保留该所有权；等待就绪不会释放锁。

当没有数据面临风险时，维护准入拒绝会以记录的警告结束更新，包括来自未知或非服务持有者的争用。Repair 会在报告该警告之前恢复其停止的受管服务。Doctor 和插件维护保持待定。解决报告的所有权或可用性问题，然后运行 openclaw update repair。检查 openclaw update status --json 和 openclaw gateway status --deep，以查看待处理迁移、记录的警告以及当前健康状态。

不要删除锁文件以强制进入。已终止的进程会释放物理锁，租约所有者会回收可证明已死的身份。维护警告永远不会授权并发修复或丢弃恢复备份。活动迁移写入、不可读状态、不完整迁移以及未确认的子进程清理会保留其故障和恢复指导。

在 Windows 上，windows-task-inspection-failed 表示 OpenClaw 无法查询 Task Scheduler 以验证服务不存在。检查 Task Scheduler 可用性和服务账户的查询权限，然后运行 openclaw gateway status --deep，再重试。安装失败和更新报告包含安全失败类别，并在可用时包含数字 errno、十六进制 HRESULT、退出代码或超时预算。这些事实出现在恢复指导之前，以便有界报告保留它们。报告问题时保留这些事实；任务定义和原始原生输出被排除。

Node 和全局安装权限

对于 node-runtime-preflight，将消息中指定的运行时升级到同时满足候选版本的完整引擎范围和更新器支持的 Node 范围的版本。建议的版本是该交集内最低的支持版本。按照检测到的运行时管理器（nvm、fnm、Volta 或系统 Node）的恢复步骤操作。下一步会使用所选 Node，通过原始安装的绝对 openclaw.mjs 启动器运行 update。它不依赖在版本管理器切换后 openclaw 仍位于 PATH 上，也不建议将全局安装到未检查的前缀中。Extended-stable 恢复使用 --channel extended-stable，以便解析器选择受支持的月度版本；其他包通道使用 --tag 保留已检查的版本。恢复中包含显式通道切换，因为运行时拒绝发生在该偏好被保存之前。如果已经处于最新状态的服务被停止，或其定义无法刷新，请让部署所有者在该定义中选择受支持的 Node，然后再重试。切换 shell 运行时不会更改服务固定的 Node 路径。

保持相同的服务账户、配置文件和状态/配置覆盖项。恢复会还原记录的服务选择器，包括你的 shell 中不存在的覆盖项；不包含凭据。普通更新调用会在安装前重新检查所选 npm 前缀和受管服务，并保留原始包所有者。其正常的运行时选择、服务刷新、重启和验证检查适用。容器会使用相同的状态/配置挂载重新部署目标镜像。

global-install-foreign-destination 表示包事务的目标是外部的，或无法确定其所有权。该检查使用解析后的安装目标：当 nvm、fnm、Homebrew Node 或操作员的 npm 前缀更改在 shell 中选择了不同的前缀时，现有的 npm-global 安装会保留其自身前缀。该 shell 前缀下的无关安装不会阻止对原始安装的更新。pnpm 全局安装保留其 pnpm 所有者，并且不使用此 npm 目标检查。

实际目标必须为空，或其规范包路径必须与正在运行的安装或所选受管服务匹配，并且任何现有启动器都指向该包内部。无法访问或不可读的目标会在暂存前停止更新；未知目标永远不会被视为空。恢复检查访问权限或所选包布局。请部署所有者验证不可读布局并显式选择预期安装。保存的结果和公开失败报告会指明目标前缀、包、启动器、正在运行的安装以及分类后的所有权原因。公开路径会将你的主目录替换为 ~，并隐去其他主目录用户名。openclaw update status 和 Doctor 会保留警告和恢复步骤。解析到同一安装的符号链接前缀会被接受；仅拼写不同不会使目标成为外部目标。将运行时切换回来，并通过保留的绝对启动器重试。或者，在目标所有者同意的情况下，当可用时使用打印出的 gateway install --force 命令，为预期服务显式选择该安装，然后更新。这会更改服务绑定；它不是覆盖其他部署包的权限。受保护的服务定义改用部署所有者说明；--force 无法替换密封挂载。试运行返回相同的拒绝。记录的尝试会保留在更新历史中，并由 Doctor 显示。如果当前活动的 CLI 和服务指向不同的安装，请按照 Gateway 服务恢复 选择预期安装，同时保留其状态和服务账户。在暂存前拒绝的旧版更新器无法加载候选版本的改进诊断；在重试更新前解决其前缀不匹配问题。

如果范围不重叠，请安装受支持的 Node 并选择兼容的 OpenClaw 目标；该候选版本无法通过此更新器在受支持的 Node 版本上运行。参见 Node.js。

对于 global-install-permission-denied，请检查所提示的目录及其所有者。如果你拥有该目录，消息会给出一个限定范围的 chmod u+rwx 命令。对于管理员所有的 npm 前缀，应让该账户执行包更新，或授予预期更新者写权限。保留 Gateway 现有的状态和配置；使用 sudo 调用整个更新程序可能会选择不同的 home 目录和服务账户。不要递归更改共享系统前缀的所有权。个人安装则可以改用用户可写的 npm 前缀。

准入后发现的权限错误具有相同的原因。如果激活已经开始，报告中的回滚和服务恢复约束仍然适用。在容器内，同样的下一步操作也会指示你拉取或构建目标 OpenClaw 镜像，并使用相同的状态/配置挂载重新部署。在运行中的容器内进行的包更改不会持久保留。

系统级 systemd 服务

当调用账户对安装目录具有写权限时，系统级 Gateway 服务不会阻止包更新。openclaw update --yes 和 Gateway 更新操作都会更新包，并记录一条包含确切操作员重启命令的警告，例如 sudo systemctl restart openclaw-gateway.service。更新程序不会停止或重启系统服务，也绝不会调用 sudo。运行中的 Gateway 在检测到其安装已被替换时可能会退出；请在更新后重启该 unit。使用结果中打印的 unit 名称（包括任何实例名称），然后检查 openclaw gateway status --deep。

如果同一个 Gateway unit 同时存在于用户和系统作用域中，更新将保留这些系统级限制。名称不同的 Gateway 不会造成这种冲突。安装替换后的重启会等待辅助程序确认更新程序和清理工作均已完结；仅一个被中断的辅助程序本身并不允许重启。中断后手动重启之前，请检查任何仍存活的更新程序。

即使更新程序以 root 身份运行，重启仍由操作员管理：受管更新交接负责用户级服务的监督和恢复，而不负责系统服务的生命周期。当待处理的 Doctor 或插件维护无法与当前 Gateway 安全并行运行时，会记录为一条警告。在解决所报告的维护状况后，运行 openclaw update repair。

如果安装目录不可写，更新会在包变更之前停止，并报出 managed-service-handoff-failed，同时打印确切的包更新和重启命令。让拥有安装目录的账户运行这些命令，同时保留 Gateway 的服务账户、状态和配置。不要在其他的 home 目录下运行整个更新程序，也不要递归更改共享系统前缀的所有权。

已安装的更新程序如果报告 Managed update handoff requires a user-scope systemd unit，会在加载候选版本之前拒绝执行。候选版本无法修复这一准入判定。使用一次手动包管理器流程，然后重启所指定的系统 unit；后续更新即可使用修复后的更新程序。

大型 agent 集群上的 2026.9.4 发布

已发布的 2026.9.4 更新程序在快照准备和候选版本检查之间共用同一个五分钟截止时间。其失败日志的末尾会合并这些检查的输出：即使失败的步骤是 lint，Doctor complete. 也可能属于前一个修复阶段。最后一行日志中的已用时间衡量整个预演过程；步骤持续时间衡量单个检查。需要一份完整的 lint JSON 报告才能确定 lint 在终止之前已完成。

已发布的 OpenClaw 2026.9.4 在其 HTTP 监听器绑定之后，可能会花费数分钟准备模型目录和聊天元数据。在一个无更新、经过插桩的 480-agent 对照组中，HTTP 探测在 944 秒的观察期内一直未得到响应；随后 Gateway 在 947.5 秒时记录了 ready。停止该实例最终需要依赖 systemd 现有的 5 分 30 秒停止限制。这些是对单个合成测试装置的测量结果，并非预期的启动预算。

第二个未插桩的 480-agent 对照组首先通过了带签名的 Gateway 握手、服务构建和健康 RPC 检查，然后在没有任何更新的情况下失去了 HTTP 响应能力。就绪后 25 分钟的对照观察完成；抽样到的失败持续了 24 分钟，随后最后一项三分钟服务检查也失败了。原始 PID 和安装仍然保留。共享 schema 17、所有 481 个处于 schema 19 的物理 agent 数据库，以及配置字节均保持不变；捕获到的状态维护租约均为空。

主线程消耗了接近一个 CPU 核心。日志显示了既有的计划审查尝试、集群范围的完整性检查，以及内存插件启动清理错误。这独立于更新，复现了一个已发布的 Gateway 集群准备/后台维护可用性问题。其确切的 JavaScript 热循环仍未完成性能分析，而最初的更新失败运行缺乏排除额外状态或恢复缺陷所需的活状态证据。保留的包、PID 或 serviceRestartSafe: true 并不能证明先前的 Gateway 正在提供服务。参见调查报告。

在恢复之前，请保留更新报告和已验证的备份。保持相同的服务账户、profile、包管理器和安装前缀。在进行手动替换之前，让该安装目录的所有者停止 Gateway 和其他写入者。当已安装的更新程序无法完成时，请使用手动包管理器流程，选择与保留状态兼容的确切目标版本，然后在启动其 Gateway 之前运行该目标版本的 openclaw doctor --fix。如果保留的二进制文件无法读取当前状态，请遵循备份恢复；更改 schema 标记或删除租约行并不能逆转迁移。

通过经过身份验证的 Gateway RPC 验证实际服务版本/构建，并在宣布恢复或移除备份之前检查 /readyz。plain-start 控制未验证这些恢复步骤，也未确认重启同一个 2026.9.4 集群能够解决更新失败状态。

等待 2026.9.6 的无头节点

运行已发布 2026.9.6 并使用默认插件的无头节点会准备自动更新，但永远不会激活它。即使没有命令在运行，其日志也会显示 node auto-update <version> is ready; waiting for active work to finish。该版本捆绑的 File Transfer 插件不会报告其空闲状态，并且正在运行的节点会在任何较新代码加载之前做出空闲判断，因此后续版本无法自动修复此问题。

通过正常工作流程更新一次节点，然后重启它：

openclaw update
openclaw node restart

对于前台节点，请停止 openclaw node run 并重新启动它。 后续版本会在调用之间将 File Transfer 命令报告为空闲，因此后续的自动节点更新可以正常激活。

插件修复警告

post-update-plugins / plugin-convergence 伴随 post-plugin-doctor-execution-failed 可以描述包已安装后 Doctor 子进程失败。更新后的收敛记录将该执行失败记录为警告，保留其退出原因和可用的插件诊断信息，并继续执行配置验证、就绪检查和 Gateway 激活。 openclaw update status 会显示该警告，即使更新成功。后续的失败报告会将其保留在单独的 Warnings 部分中。

抛出异常的插件配置修复钩子会保持该插件的输入不变，并在其警告中指明该插件。修复插件，然后运行 openclaw doctor --fix 或 openclaw update repair。 活动或未经验证的 Gateway，以及明确的状态迁移或配置写入拒绝，仍然会阻塞。无法确认其已关闭的 Doctor 子进程也是如此：它可能仍会写入状态。 保留备份，并在重试前解决该特定拒绝。

Doctor 的已配置插件修复和载荷验证警告不会阻塞 Gateway 就绪。如果受跟踪插件的载荷不可用，则将其标记为不可用，并保留其配置和待迁移输入。 这包括更新期间的主机链接修复失败。 openclaw update status --json 会列出待处理的插件迁移警告，Doctor 会报告受影响的插件和修复命令。运行 openclaw update repair， 然后在恢复对插件源的访问后运行 openclaw doctor --fix 以重试。

缺失的已配置 plugins.load.paths 是可用性警告。 更新会继续，Gateway 可以使用可用插件变为就绪。 更新报告和 Doctor lint 使用 configured-plugin-path-unavailable 标识不可用的路径。 权限、I/O 和其他文件系统检查失败会使用不同的 configured-plugin-path-inspection-failed 警告，并附带原始错误代码和消息。对于权限错误，请修复报告路径上的权限，然后 运行 openclaw doctor --fix；对于其他失败，请先解决报告的文件系统问题。这两种警告都会保留未检查的配置，并让更新继续。

加载路径可以包含多个插件或覆盖捆绑插件，因此发现机制无法推断哪些设置属于其缺失的载荷。Doctor 会保留未检查的插件设置、通道设置、模型选择和加载路径条目，而不是将其视为过期或应用另一个插件的修复。 恢复该路径或更正其 plugins.load.paths 条目，然后运行 openclaw doctor --fix 以恢复检查和修复。其他发现错误保留其现有诊断信息。

通过 ClawHub 安装的官方版本绑定运行时插件会使用其声明的 ClawHub 源用于新的核心发布队列。已发布的 2026.9.4 目录为 Codex 遗漏了该源；修正已在 main 分支的 #148518 中。

缺失的临时插件捕获

包含 openclaw-plugin-build- 的 ENOENT 路径可以标识缺失的运行时源捕获，即使已安装的插件文件仍然存在。 重新加载或替换该插件会将不可用的恢复快照报告为警告，并在正常清理后加载已安装的替换项。 运行 openclaw plugins reload <id>，或者如果其已安装载荷也需要修复，则重新安装该插件。如果替换失败，则无法恢复缺失的先前代码；健康插件会保留其可用的恢复快照。

较旧版本在尝试复制同一缺失捕获时，可能会拒绝启用、卸载和重新安装。重试前，请通过其服务所有者重启 Gateway，或升级主机。参见 插件源生命周期。

持续写入下的数据库快照

较旧的更新器可能会报告数据库在 10 次尝试后“未稳定”，而 Gateway 仍在持续写入。当前更新模式检查和演练使用一致的 SQLite 在线备份。演练进度会在更新账本中记录复制的页数、字节数和经过时间。

这无法向后移植到已安装的 2026.9.5 驱动程序。对于该升级步骤，请通过其服务所有者停止服务，从另一个终端运行 openclaw update，然后启动服务。在 Linux 用户服务上，使用 systemctl --user stop openclaw-gateway.service 停止它。如果服务关闭本身挂起，请将其视为单独的关闭问题；不要启动第二个更新器。

来自 2026.9.5 和 2026.9.6 的快照解析错误

从 2026.9.5 或 2026.9.6 开始的更新可能会停止，并出现类似 Update state snapshot failed (exit): Assigning to rvalue (308:4) 的消息。已安装的更新器无法解析插件依赖项中向 import.meta.url 赋值的有效 JavaScript，例如 @jsquash/png 或 @jsquash/avif。修复位于目标版本中，但已安装的更新器会在目标启动之前运行此检查。为这一次更新禁用该插件：

openclaw plugins disable <id>
openclaw update
openclaw plugins enable <id>

从修复版本及更高版本开始，更新会正常检查这些插件。

大型 model-catalog 临时目录

旧版本可能在 openclaw-model-catalog-* 目录中保留多个完整的插件副本。仅扫描顶层 openclaw-plugin-build-* 路径会遗漏这些嵌套副本。当前的 catalog 工作进程会复用所选的运行时快照进行 provider 发现，并在临时目录树的所有者退役时将其移除。

升级主机，然后运行 openclaw doctor 检查遗留快照。在 Linux 和 macOS 上，openclaw doctor --fix 仅在维护期间且没有其他 OpenClaw 进程运行时删除整个遗留目录树。不要根据快照的年龄或是否出现在打开文件或内存映射列表中来删除它们：空闲的所有者可能仍然需要它们。现代快照使用 SQLite 托管来证明已退役。参见 插件源生命周期。

运行 node dist/index.js 的无关 Node 服务不计为 OpenClaw 所有者。Doctor 根据其安装的包标识解析通用入口点，并遵循 OpenClaw 服务标记。如果无法对活动的 PID 进行分类，Doctor 会保留快照并报告该 PID 以及检查失败原因（包括缺失或不可读的包清单）；这仍然是维护警告，不会导致更新失败。解决所报告的检查问题后，重试 openclaw doctor --fix。在 macOS 上，来自另一个 UID 所属进程的不可读参数不会阻止清理；Doctor 在调试级别记录一次该排除项。来自同一 UID 或未知 UID 的不可读参数仍会保留遗留快照。Doctor 也会保留由另一个 UID 拥有的遗留快照根目录，包括在特权运行时。受管理的原生快照使用其记录的托管信息和已安装索引引用，而非主机进程清点，这与启动清理时的做法一致。Windows 主机范围的遗留快照清理仍仅报告而不清理。

原因代码

  • dirty、no-upstream：重试前先修复源代码签出（checkout）。
  • runtime-artifact-publication：受影响的 Gateway 正在运行，或无法离线验证。检查 openclaw gateway status --deep，通过其服务所有者停止它，然后重试。在 macOS 上，已加载的 LaunchAgent 即使被禁用也可能重新生成，并且暂时没有 PID；openclaw gateway stop 可将其卸载。
  • update-ledger-busy：另一个进程持有了状态数据库的写入锁，超出了更新步骤的预算时间。命令成功退出，未登记任何运行，并保留了之前的完整历史。等 Gateway 的写入稳定后重试。更新命令的 JSON 输出包含延迟说明；openclaw update status --json 显示上一次记录到的运行。如果核心更新后所需的最终化被延迟，其子进程将以非零状态退出，这样现有的父进程就不会误以为插件收敛已完成。更新后的 Gateway 会记录跳过的原因且不会重启；重试更新会再次执行最终化，包括核心已是最新版本的情况。
  • plugin-target-unavailable：已启用的配置 npm 插件对于所选核心没有可解析的目标，或者无法读取其注册表元数据。在提供服务的 Gateway 停止或核心包更改之前，拒绝信息会标明插件、包目标和注册表错误。在发布或注册表恢复后重试，使用 openclaw update --tag <older-version>，或禁用受影响的插件后重试。如果核心版本未知，请选择确切的注册表版本。Extended-stable 不接受 --tag；稍后重试或显式切换频道。--dry-run 执行相同的可用性检查。
  • preflight-insufficient-space：请释放包含预检暂存区（POSIX 上为签出目录的 .artifacts 区域）和包管理器存储所在文件系统的可用空间，然后重试。更新程序在确认 ENOSPC 后会停止，而不是尝试更旧的提交；它不会删除共享的包管理器存储。有关暂存位置和旧版已发布更新程序的限制，请参见 Git 签出流程。
  • deps-install-failed、build-failed、ui-build-failed：检查失败的步骤，修复依赖或构建错误，然后重试。
  • global-install-failed：包管理器安装、暂存、验证或启动器替换以非零状态退出。更新程序随后尝试回滚。生成报告中的 Rollback outcome 行和 openclaw update status 会记录之前的安装是否已恢复以及是否可以安全重启。openclaw gateway status --deep 显示正在提供服务的版本；在假设旧版本正在运行之前，请确认两者。生成的失败报告会隐去包管理器自身的错误行；失败步骤的有限长度 stderr 尾部会保留在持久运行记录以及状态目录下 logs/support/ 中保存的更新失败上下文中。两个原因属于已发布的 2026.9.3 和 2026.9.4 更新程序，后续版本无法修复已安装的更新程序：在 macOS 上，当更新程序的 umask 与已安装启动器的权限不同时，会出现 Package rollback launcher backup changed；在繁忙主机或慢速磁盘上，30 秒的基线包指纹超时会被报告为包树已更改。使用相同的已安装更新程序重试会重复这些问题。使用手动包管理器流程安装目标版本一次，运行 openclaw doctor --fix，然后重启 Gateway。此手动安装会绕过已安装的更新程序一次。目前还没有任何已发布版本同时包含这两个修复：只有安装了包含 #145282 和 #144758 的、晚于 2026.9.4 的版本后，openclaw update 才会通过已修复的更新程序运行。其他原因会显示包管理器的错误：EACCES、EPERM 或前缀不匹配意味着全局前缀是自定义的，或调用用户没有写入权限；修复所有者和权限，然后重试。如果包安装不完整，请重新运行安装程序。
  • 从 2026.9.4 更新时，在 candidate gateway canary 处接近 300 秒出现 runtime-verification-failed：已安装的更新程序在快照和候选检查之间共享该截止时间，即使使用了更大的 --timeout 也是如此。实际经历的失败时长并不仅仅是 Gateway 启动时间。使用相同的手动包管理器流程，然后运行 openclaw doctor --fix 并重启 Gateway。参见 #144858 和 #154381。
  • doctor-failed：在 Gateway 主机上运行 openclaw doctor，解决其发现的问题，然后重试。有关检查清单和 --fix 行为，请参见 Doctor。
  • restart-disabled、restart-unavailable：在重试前恢复受支持的监督程序，或启用 Gateway 重启。
  • restart-unhealthy、restart-revision-mismatch、restart-revision-unavailable：在重试前检查 Gateway 服务健康状态及其安装根目录。
  • managed-service-handoff-*：首先检查状态。如果交接停止，请在 Gateway 主机上使用 CLI 以保留完整的诊断输出。

未知原因代码仍会显示。重试前请检查 Gateway 日志。

保留的旧版会话历史

当 Doctor 能够验证导入的 SQLite 状态并保留原始文件时，旧版 sessions.json 中的无效条目以及格式错误的 JSONL 转录不会导致更新失败。Doctor 会跳过没有有效会话 ID 的条目，并导入可读的转录前缀。它会在迁移报告中，以及在 openclaw update status --json 中，将文件和原因作为警告报告，包括由无法自行记录 Doctor 警告的旧版本启动的更新。

在插件迁移待处理期间，原始文件会保留在原位置，并带有已验证的导入回执。重复的 Doctor 修复会保留当前 SQLite 中的编辑和删除。插件迁移完成后，损坏的原始文件仍会保留在受保护的迁移归档中，以便手动恢复；更新清理不能将其作为已完全导入的历史丢弃。

请保留指定文件以及更新前的备份。使用 openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json 检查它们。不要覆盖与回执绑定的原始文件来修复它们。已更改或新出现的转录可能包含 SQLite 中不存在的历史，并仍会阻止就绪状态。请检查 openclaw update status --json，停止 Gateway，并在重试前运行 openclaw doctor --session-sqlite recover --session-sqlite-all-agents。参见 会话恢复。

CLI 回退

请在 Gateway 主机上运行这些命令，而不是在只是打开了 Control UI 的计算机上运行：

openclaw update status --json
openclaw triage

使用 openclaw update --dry-run 预览新的尝试。如果包更新在安装开始后失败，请按照 更新 中的安装程序恢复步骤操作。

如果已安装的 CLI 已损坏，或者文件系统无法写入诊断信息，自动 triage 会报告该失败并保留原始更新错误。修复已安装的命令，然后运行 openclaw triage。即使 Gateway 无法启动，受管理的更新也会保留其分离的辅助日志；记录的结果指向可用的诊断信息或失败的收集尝试。重启通知会总结诊断结果。保存的工件路径以及精确的、特定于安装的恢复命令仍保留在主机命令输出或受管理更新辅助日志中，而不是发送到代理或通道的通知中。

如果更新器在 Gateway 停止后崩溃或被终止，除非更新器已完成并验证恢复，否则 Gateway 会保持停止状态。检查 openclaw gateway status --deep，修复报告的依赖项或安装故障，然后重新运行 openclaw update。失败的 Git 依赖项安装会在允许自动重启之前恢复并重建之前的运行时。经过验证恢复后的重启仍会检查已安装的配置、服务所有权和 Gateway 健康状态。

回滚边界

不要将恢复状态作为对更新失败的第一响应。首先重新安装已知良好的代码，同时保留当前状态。只有当旧代码无法读取当前配置或数据库时，才恢复经过验证的更新前状态快照。参见 回滚。

支持诊断

收集以下信息，但不要发布凭据、原始配置或未脱敏的进程输出：

  • OpenClaw 版本和安装类型；
  • 来自“设置 → 更新”的更新时间戳、目标、阶段和原因代码；
  • 查看详情 显示的受限故障详情；
  • openclaw update status --json；
  • openclaw gateway status --deep --json；
  • 相关的已脱敏 Gateway 日志行。

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