可用性检查以及每次更新留下的持久记录。见 openclaw update 参考。¶

update status¶

显示当前更新渠道、git 标签/分支/SHA（仅限源码检出）、更新可用性，以及活动中或最近的更新报告。当更新正在进行时，表格显示其阶段，而不是提示另一个更新，并且最后一行指向 openclaw update status。JSON 仍会将 registry/Git 的 availability 与 activeRun 分开包含。

Git 可用性检查（包括 Gateway 启动后的后台检查）只刷新所选的上游。它们不会导入其他远程分支或标签，不会修剪现有引用，也不会更改浅历史（shallow-history）边界。全新的分离 HEAD Dev 检出可以无需先获取远程完整引用清单即可发现其配置的 main 上游。本地上游无需获取；未知上游仍然保持未知。所选上游自身缺失的历史仍可能被下载。当浅历史没有合并基础（merge base）时，领先/落后计数仍然不可用。

对于配置了 update.channel: "stable" 或 "beta" 的干净源码检出，update status --json 可以包含 update.git.preferredTarget，其中带有 channel、tag 和确切的提交 sha。这会使用更新程序的发布选择器，并获取到一个临时私有 Git 仓库中，同时保留已安装的引用和检出。所选标签在发布远程仓库中仍必须解析到该提交；仅保留在本地的标签不能算作新目标。

字段缺失表示未知。默认/dev 目标、显式引用、不受支持的渠道、脏检出和不成功的检查都不会产生此信息。它描述的是所观察到的已配置渠道的首选选择，而不是候选构建成功、降级批准、服务就绪或安全状态恢复。显式的 update 调用可以选择不同的目标或安装方法。较旧版本已安装的 status 命令无法从候选代码中获取此观察结果。

对于 Git 安装，update status --json 可以包含 update.git.artifacts。在原生验证器检查了观察到的源码提交、构建标记、运行时入口和 Control UI 资源之后，ready: true 会包含已安装构件的 version 和不可变的 buildId。ready: false 表示验证失败；字段缺失表示构件就绪状态未知。此观察结果并不确立远程目标的新鲜度、候选验证，或正在运行的 Gateway 的身份或健康状态，也不授权状态恢复。该版本优先使用记录的构建元数据，并在构建没有版本时回退到包版本，遵循 CLI 的版本优先级。

如果更新将工作移交给后台辅助进程，则该命令尚未完成更新。请按照其最后的 openclaw update status 命令检查进度和结果。openclaw gateway status --deep 检查的是 Gateway 健康状况，而不是更新进度。

Status 还会显示未完成的插件数据/设置升级及其修复命令，包括较旧的更新程序未在其运行历史中记录这些警告的情况。在更新进行期间，请先让更新完成，再遵循插件修复建议。现有插件数据和设置会保留到升级完成。JSON 将这些消息暴露为 migrationWarnings；当插件迁移完成时，这些消息会清除。如果无法读取迁移状态，migrationWarningsError 会报告该失败，同时可用性和运行历史仍然可见。

当 Gateway 可达时，status 还会读取其记录的渠道警告，而不会探测渠道服务。JSON 将这些暴露为 channelIssues。这包括在本地插件请求受信任运行时状态后渠道启动被阻止的情况，并带有来源和支持的安装补救措施。Gateway 不可用不会阻止可用性或运行历史输出。

对于本地 Gateway，status 还会在其上次关机记录到安装替换时显示该信息，即使后继者已经启动。JSON 将记录的原因和完成时间暴露为 lastGatewayInstallationReplacement。这是历史信息，不是当前健康判定或更新运行；手动通过包管理器替换不会创建更新器历史。

openclaw update status
openclaw update status --json
openclaw update status --timeout 10

显式超时替代默认值。本地安装发现会保留自己的检查预算。

对于 extended-stable 包安装，status 会执行与前台更新相同的公开选择器和精确包验证。当已安装版本更新时，它可以报告 ahead of extended-stable。JSON 失败信息包括 registry.reason（selector_missing、selector_query_failed、exact_package_mismatch 或 unsupported_git_channel）。

运行历史与报告¶

每个被准入的更新都有一个持久的 runId，包括从聊天、Control UI、CLI 以及自动更新活动发起的更新。在已有运行时数据库的配置文件上，dry-run 预览以及准入后被拒绝的更新会保留一条带原因的跳过或失败记录。全新配置文件的 dry-run 不会创建数据库，也不记录任何运行。在准入前被拒绝的 CLI 调用不会改变状态。同一个 ID 会跟随分离式更新程序和重启后的 Gateway，因此重新连接不会丢失结果。后核心最终化子进程会向父进程报告，而不会创建单独的更新运行，即使在较旧的更新程序无法转发 run ID 时也是如此。

在已有配置文件上，更新历史准入会使用更新的步骤超时（默认 30 分钟，或 --timeout）等待数据库写入器。如果等待超时，命令会以延迟的 update-ledger-busy 结果和重试指导成功退出。它不会声称更新已完成，也不会创建运行；之前的历史仍然可见。dry-run 会在 notes 中报告不完整的预览。Repair 使用其现有的预检预算进行相同的准入。Status 和后台历史工作保留其较短的等待预算。

当准入资源耗尽时，隐藏的后核心最终化会以相同的延迟原因返回非零退出码。其 Gateway 父进程会记录跳过的结果，并将重启保持挂起状态，直到后续更新完成插件收敛。公开的 update、--dry-run 和 update repair 保留成功延迟退出的行为。此行为要求更新后的 CLI：先前安装的更新程序在其自身历史准入完成之前不能使用候选代码。

分类机制保留原始更新报告。修复期间启动的任何更新都会获得独立的 runId。

意外自动更新活动失败时，若存在错误代码，则会将其以及经过脱敏处理的诊断信息保留在运行历史和 Gateway 日志中。活动结束后，状态和受限运行报告会显示原因。这要求使用更新后的 Gateway；旧运行无法恢复从未记录的原因。

已受理的 openclaw update --json 包含 runId 和 run 记录。openclaw update status --json 在存在活动运行时会包含 activeRun，存在历史记录时会包含 lastRun。自动更新活动在其自身已受理的运行结束时不再显示为“正在应用”，包括受管交接在重启 Gateway 之前失败的情况。Gateway 会协调确切的更新活动运行，因此较新的无关运行不会让已完成的更新活动保持忙碌，也不会清除另一个正在进行的更新活动。

保留的 dry-run 预览仍可通过历史查询获得，但不会替换 lastRun，因此预览无法掩盖最后一次真实更新失败。如果历史记录无法读取或分类，状态仍会显示更新可用性和运行时发现。人类可读输出会说明运行状态不可用；JSON 包含 runStatusError 并省略运行字段。这并不意味着不存在活动或过去的运行，状态也不会修复无法读取的历史记录。

状态可以在超过 24 小时后协调一个未被接触过的、无身份的旧版受理记录，前提是它仍停留在初始的 requested/in_progress 步骤，并且没有保留的恢复描述符。该行会以 failed 状态保留在历史记录中，原因为 legacy-driver-expired。当该行是当前运行时，状态会显示重试指引。当另一个运行是当前运行时，状态会保留历史通知但不包含重试说明，即使在之后有成功更新也是如此。其他历史记录保持只读。

当活动行已不活跃超过 30 分钟，且其记录的驱动程序被证实已失效时，状态还会报告 abandonedRun 及其 runId 和协调 rule。对于这些行，状态保持只读：存储的行会一直保留在 activeRun 中，直到 Gateway 或显式修复提交结果。不符合旧版过期形态的无身份行不会自动协调。对于这些陈旧的无身份行，JSON 会包含 staleRun 及其 runId 和 guidance；人类可读状态和 Doctor 预检报告会显示“自 <time> 起无活动；如果没有更新正在运行，请运行 openclaw update repair 或启动新的 openclaw update。”

仅当旧行是唯一活动运行、没有记录驱动程序身份且超过 30 分钟无活动时，显式的新 openclaw update（包括 --dry-run）才会取代旧行。受理过程会以原子方式将该行标记为 failed，原因 superseded，并保留 reconcile:superseded 步骤，然后创建新运行。最近的行以及带有记录身份的行会被保留。继承的更新延续和自动更新活动不会取代旧版历史记录。配置写入将保持暂停，直到活动行被协调完成。

OpenClaw 2026.9.2 可以在旧行仍在运行时受理新的 CLI 更新；陈旧的行不会阻塞更新程序受理。请正常升级，然后如果状态仍显示旧运行，请在更新后的安装中运行 openclaw update repair。参见 更新。

人类可读输出、聊天补全通知、Control UI 更新视图以及 openclaw status 更新行都使用同一份报告，包括成功时也是如此。报告显示已记录的事实；某个验证事实缺失意味着该项检查尚未被观察到。

仅当保存的观测值与期望值不一致时，身份检查失败才会报告为版本或构建不匹配。缺失身份证据会报告为不可用，包括那些更新程序仅保存了 versionMatch: false 的旧运行。Control UI 的版本徽章对于不可用的身份证据显示 未验证，对于观测到的版本或构建不匹配显示 失败。这不会改变已记录的更新结果。

对于失败的运行，人类可读状态、完成通知和已审阅的失败报告还会向记录的 Gateway 端口发起只读健康检查请求。收到响应将取代历史上关于 Gateway 已停止的说法；这不会改变失败的更新结果，也不会验证回滚安全性。保存的恢复建议会被标记为历史性建议，以保留配置和迁移约束。如果无法读取当前健康状况，报告会如实说明。JSON 运行记录仍然是原始历史事实。

当更新程序观察到特定检查、Doctor 发现、包管理器错误、服务检查原因或插件失败时，失败的步骤会包含受限的 failureFacts。每条事实注明检查名称和原因代码，并可选地包含受影响的配置键、插件 ID 以及一行最多 200 个字符的诊断信息。这些事实会保留在运行账本中，并出现在本地摘要和已审阅的 GitHub 失败报告中。机密和私有路径在记录前会被脱敏；公开报告包含可识别的错误原因，而不是任意的命令或用户文本，并显示配置键族而非操作员定义的名称。只有经目录确认的公开检查 ID 和插件 ID 才会被包含；未知 ID 和代码在本地保持完整，在公开时被脱敏。旧运行无法恢复其更新程序未记录的事实。现有的历史记录和报告大小限制仍然适用。

npm 失败记录会按顺序保留前五条经过清理的错误行。超过 200 个 UTF-8 字节的行会在该预算内保留一个前缀，后跟一个空格和显式的 …[truncated] 标记。失败的软件包基线扫描会记录 baseline-scan-failed，并包含扫描的原始原因，包括其身份回退也失败的情况。超时但回退成功仍属于警告。

当受管服务交接无法启动或转移所有权时，Gateway 会在失败的 requested 步骤上记录拒绝原因。状态会在原因代码之后包含记录的诊断信息；聊天和失败报告使用相同的事实。公开报告会保留可识别的交接诊断信息，包括在找不到已安装更新程序时运行 openclaw doctor 的说明。一旦 Gateway 运行的是更新后的代码，此行为即适用；较旧的报告无法恢复缺失的事实。

失败的最终化步骤会在开始报告失败之前记录其原因代码。独立最终化还会记录包安装或 Git 安装类型。对于包安装，它会记录无需包回滚，因为最终化不会替换核心包；这并不声称 Doctor 保持了配置或状态不变，也不声称 Gateway 健康已得到验证。失败报告包含来自失败步骤保留的诊断信息中的可识别错误代码和原因，包括进程退出代码旁的内容（例如，exit 1 (EACCES; Permission denied)）。任意日志文本保持私有；没有可识别诊断的步骤仅显示其退出代码。

可恢复的维护失败即使更新成功也会作为已记录的警告出现。每条警告指明被跳过的工作、原因和修复命令。Doctor 还会将最近一次运行的警告显示为历史观察结果：后续的修复可能已经解决了这些警告。现有的报告和历史大小限制仍然适用。

前台更新器在必需的最终化工作及其本地执行器落定后发布其最终结果。迟到的所有权或释放失败会返回错误，而不是发布先前确定的成功。现有终端历史不会被覆盖。

执行器接纳、落定或报告发布的意外失败还会在提供交互式失败报告之前记录最后到达的阶段、脱敏后的错误，以及是否需要或尝试过回滚。如果所有权丢失或待处理的恢复阻止了安全的历史写入，该命令会报告恢复待处理，并为其所属更新器保留现有历史，而不是启动交互式故障分类。

激活有一个由更新现有阶段预算派生出的总体截止期限。如果该期限到期，更新器会取消其拥有的工作，并在该预算内等待其子进程落定，然后将 update-activation-timeout 记录为失败结果。尚未停止的子进程会保留其所有权和恢复状态。请检查 openclaw update status 和 openclaw doctor，并在运行 openclaw update repair 之前等待所属更新器及其子进程停止。该超时并不授权回滚或删除保留的更新状态。如果迁移或待处理的恢复阻止了安全的历史写入，更新器会报告该超时，并保留该状态以供其所属运行时进行对账。

成功的安装验证并不表示过时的包备份已被删除。如果包所有者确认仅有过时备份清理尚未完成，则 JSON、历史记录和人工可读报告会包含一条带有保留路径和后续指导的警告。未经验证的恢复、不可读的备份状态和未知的完成失败仍属于错误。在手动删除过时备份之前，请检查保留的路径；未解决的恢复材料不符合此清理条件。

具有 operator.admin 权限的 Gateway 客户端可以检查历史记录：

openclaw gateway call update.runs.list --params '{"limit":10}'
openclaw gateway call update.runs.get --params '{"runId":"<run-id>"}'

update.runs.list 返回 { runs }；limit 默认为 20，上限为 100。update.runs.get 返回 { run }，当 ID 未知时 run 为 null。update.status 保留其现有字段，并添加可选的 activeRun 和 lastRun 记录。当运行处于活动状态时，Gateway 会广播 update.run.changed，其中包含 runId、phase、status 和 updatedAtMs。重新连接并读取该行，以恢复重启期间错过的更改。

Gateway 的 update.status 报告当前自动更新策略和任何实时 campaign，独立于检出发现。安装细节可能稍后到达；读取状态不会启动调度或清除进行中的 campaign。如果无法解析更新通道，schedule 将保持缺失，而不会声称调度器处于空闲状态。

当历史请求需要只读快照时，Gateway 会异步准备该快照，以便其他请求可以继续。该快照保留源数据库及其 sidecar 文件。Gateway 的 update.status 在可用时通过已打开的数据库读取其两条运行记录，从而避免每次轮询时复制整个数据库。冷状态读取会准备一个私有快照。启用诊断时，持续时间至少为一秒的状态请求会记录 sentinel 刷新、检出刷新、安装身份、对账、历史和响应的阶段耗时。

原生服务停止观察不会推进更新记录的阶段。如果 Control UI 无法读取最新进度，它会将读取错误与最后记录的一次运行一起显示；使用 Check status 重试，而不会启动另一次更新。

阶段为 requested、staging、validating、activating、restarting、verifying 和 finished。状态为 running、succeeded、failed、rolled-back 或 skipped。较旧的更新器记录也可能包含 repairing 和推理修复尝试。当前的推理修复属于失败后分类，不会重写更新结果。阶段耗时、修复尝试和验证事实仅在观察到时才会被包含。聊天报告限制为 1,500 个字符；update.runs.get 保留有界记录以供详细检查。

如果就绪宽限期结束时稳定的 Gateway 仍在启动中，该运行以 skipped 完成，原因代码为 gateway-readiness-unverified。这意味着安装已完成、就绪状态未得到确认，并且保留了恢复备份。finishedAtMs 记录观察结束的时间；confirmedAtMs 保持为 null。警告日志保留已耗用的宽限期和最后的服务/HTTP 观察结果。不承诺在后台继续确认就绪性。请使用 openclaw gateway status --deep 检查当前健康状况；之后的健康状态不会重写这一历史结果。在宽限期内变为就绪的 Gateway 会在达到就绪时记录 succeeded 和 confirmedAtMs。

独立最终化和修复会在 Doctor 运行之前记录已安装的目标版本。失败的 Doctor 步骤会保留观察到的子进程退出代码，以及有界的、脱敏后的失败原因；被终止的子进程可能具有 null 退出代码。状态和失败报告使用这些相同的已记录事实。已安装版本并不能证明当前正在为请求提供服务的版本。可选的 Doctor 诊断失败仍为警告，而被拒绝的配置写入和不完整的必需迁移仍为错误。历史运行无法恢复其更新器从未记录的事实。

当前更新器会记录其进程标识，并在较长的构建、安装和最终化阶段期间每 30 秒刷新一次台账。每当 Doctor 子进程正在修复状态时，这些写入会暂停：最终化阶段会为修复 Doctor（包括插件后 Doctor）暂停它们，安装阶段会为激活 Doctor 步骤暂停它们。这些阶段会记录其开始和完成；已记录的驱动进程标识会在其最后活动时间戳保持不变期间保护正在运行的更新。Gateway 会在启动时以及跟踪活动更新时检查被放弃的运行。当无法恢复已验证的完成状态时，如果超过 30 分钟没有步骤或心跳活动，且已记录的驱动进程可验证已死亡，Gateway 可将运行结束为 failed，原因为 abandoned，并添加一个指明该规则的 reconcile:abandoned 步骤。存活、不可读或来自外部主机的驱动进程会阻止协调。每个辅助进程或最终化子进程都会记录自身标识，并保留较早的驱动进程，因为分离的子进程可能比其父进程存活更久。如果进程标识记录不可用，更新会带有一条警告继续，并且该运行需要显式恢复。已知的父进程标识仍受保护，并且该运行的自动协调保持禁用。心跳写入错误每个驱动进程运行仅警告一次，并且不会中断正在运行的构建、安装或最终化阶段。

更新后的候选会在核心后处理完成后、将完成交还给已安装更新器之前，记录其已安装版本和构建标识。如果更新器在重启验证期间退出，Gateway 或 Doctor 可以在新的检查确认已安装和正在提供服务的构建与该已记录目标匹配且 Gateway 已就绪后，将运行结束为 succeeded。这也允许纠正匹配的 abandoned 结果，并将协调记录在历史中。存活或不可观察的驱动进程、保留的恢复工作，以及已记录的修复、失败或回滚证据仍受保护。

中断的完成检查在设置、服务和端口检查、健康稳定以及最终标识检查之间共享一个 50.5 秒的截止时间。报告和警告日志会记录稳定、超时（含经过时间和阶段）或未验证的观察。超时是警告，并使运行仍可在后续协调；重复诊断不会重置其放弃计时器。没有记录已完成托管服务重启的运行会跳过探测并记录该跳过。新的服务状态读取不能永久排除托管运行。如果原生探测清理在截止时间时仍待处理，完成状态保持未知。后续清理确认会保留原始超时；清理失败会记录这两个事实，并在报告和警告日志中指明失败。未知清理从不记录成功。恢复前检查 openclaw update status；重复诊断不会延长放弃计时器。

较早的中断运行可能缺少该检查所需的目标构建标识。Doctor 会指明被放弃的运行并解释为何无法将其结算；仅版本编号匹配是不够的。检查该运行记录的步骤，并在需要恢复时使用 openclaw update repair。

历史中无标识的行，若不属于传统过期形态，需要显式 update repair 或由操作员新启动的 openclaw update。仅一条旧的 requested 行不能证明其更新器已退出：2026.9.2 更新器在记录其第一个暂存步骤之前，可能仍在等待包管理器或注册表预检。在显式恢复其过期行之前，先停止未记录的旧更新器。参见 数据库架构。

运行从服务停止请求开始，直到 Gateway 验证为运行状态，记录 downtimeMs。暂存、候选验证和激活前修复被排除。验证记录包括服务 PID/端口、版本/构建标识、已稳定的健康状态、插件激活错误、通道就绪状态以及 /readyz。

对于 2026.9.3 及之后的事务性更新器，来自候选的新进程会在实时数据库迁移后完成验证，并将最终结果写入同一运行。它会延续激活步骤；架构升级不会创建单独的报告，也不会让旧更新器重新打开较新的数据库。

2026.9.2 更新器保留其自身的完成路径。对于共享状态迁移，候选会应用架构内容，但会延迟版本发布，直到每个受影响的终态运行至少已有五分钟，或每个仍在运行的行已超过 30 分钟未变化。Doctor 会报告该延迟；新的 Gateway 已经使用迁移后的内容，并在截止时间后发布版本。待处理的代理数据库迁移、缺失的状态元数据以及失败的内容迁移仍会产生 update-schema-bump-unfenced，并附带 手动更新命令。参见 数据库架构 了解确切的发布规则，以及停滞的旧 CLI 最终报告所面临的剩余风险。