跳转至

状态与历史

可用性检查以及每次更新留下的持久化记录。是 openclaw update 参考的一部分。

update status

显示当前活动的更新通道、git 标签/分支/SHA(仅限源代码检出)、更新可用性,以及当前活动或最近一次的更新报告。 在更新活动期间,表格会显示其阶段,而不是提示另一个更新,最后一行指向 openclaw update status。JSON 仍会单独包含 registry/Git availability,与 activeRun 分开。

Git 可用性检查(包括 Gateway 启动后的后台检查)只会刷新所选上游。它们不会导入其他远程分支或标签,不会修剪现有 refs,也不会更改浅层历史边界。全新的分离 Dev 检出可以在不先获取远程完整 ref 清单的情况下,发现其配置的 main 上游。本地上游无需获取;未知上游仍保持未知。所选上游自身缺失的历史仍可能被下载。当浅层历史没有合并基时,领先/落后计数仍不可用。

Gateway 会在 post-ready 启动工作稳定后初始化本地更新事实。本地 Git 发现使用受管理的 Gateway 启动允许时间(每条命令 45 秒,Windows 上为 90 秒),并在超时后按一秒退避重试一次。如果两次尝试都超时,它会记录一条初始化警告,并且 update.status RPC 会报告 schedule.install.git.status: "unavailable",原因为 "git-unavailable"。状态读取会复用该结果;显式的 Dev 检出刷新可以恢复它。没有 Git 元数据的包目录会跳过 Git 发现子进程。

重新连接的 Control UI 客户端共享 Gateway 重启通知快照的一次准备。更新生产者和更新运行监视器会在更新变化时刷新该快照;普通状态读取不会重新读取或最终化该通知。监视器还会等待分离更新器的迟到终结通知,最长 30 分钟,如果仍处于待定状态则记录警告。运行历史会继续独立报告已记录的结局。

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

字段缺失表示未知。 默认/dev 目标、显式 refs、不受支持的通道、脏检出以及不成功的检查不会产生该事实。 它描述的是针对所观察到的已配置通道的首选选择,而不是候选构建成功、降级批准、服务就绪或安全状态恢复。 显式更新调用可以选择不同的目标或安装方法。 较旧的已安装状态命令无法从候选代码中获取该观察结果。

对于已采用的不可变安装,安装投影仅在显式启用时包含 activationEnabled。activation 会报告保留操作的 operationId、phase、previousSha 和 candidateSha,以及可选的安全 failure 和精确保留的 recoveryCommand。 lastActivation 会记录历史验证(outcome、selectedSha 和 verifiedAtMs),包括可选的 Gateway version、buildId、pid 和 bootId。文本状态将成功标记为 accepted,将回滚标记为 restored;已恢复的前驱版本不算候选成功。较旧的回执可能省略 Gateway 字段。即使存在历史回执,待处理恢复仍保持独立。在 CLI JSON 中于 update.immutable 下读取这些内容,或在 Gateway update.status 中于 schedule.install.immutable 下读取。已准备的代或 starting 阶段不算激活成功。使用 openclaw update recover --root <installation-root> 来协调保留的操作。 一旦 Gateway 识别出已采用的不可变安装,普通 update.status 请求会刷新其原生激活事实;调用方无需 refreshCheckout: true 即可观察阶段变化。该安装的原生记录优先于外部更新管理器。

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

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

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

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

对于本地 Gateway,状态也会显示其上次关闭是否记录了安装替换,即使继任者已经启动。JSON 会以 lastGatewayInstallationReplacement 暴露记录的原因和完成时间。这是历史信息,不是当前健康判定或更新运行;手动通过包管理器替换不会创建 updater 历史。

openclaw update status
openclaw update status --json
openclaw update status --timeout 10
标志 默认值 描述
--json false 打印机器可读的状态 JSON。
--timeout <seconds> 300 检查的超时时间。

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

对于 extended-stable 软件包安装,状态会执行与前台更新相同的公开选择器和精确软件包验证。当已安装版本更新时,它可以报告 ahead of extended-stable。JSON 失败会包含 registry.reason(selector_missing、selector_query_failed、exact_package_mismatch 或 unsupported_git_channel)。

运行历史与报告

每个被接受的更新都有一个持久的 runId,包括从聊天、Control UI、CLI 和自动更新活动请求的更新。在具有现有运行时数据库的 profile 上进行的 dry-run 预览,以及在准入后被拒绝的更新,会保留带有原因的 skipped 或 failed 记录。全新 profile 的 dry-run 会保持数据库不存在,并且不记录运行。在准入前被拒绝的 CLI 调用不会改动状态。同一个 ID 会跟随分离的 updater 和重启后的 Gateway,因此重新连接不会丢失结果。Post-core finalization 子进程会向父进程报告,而不会创建单独的更新运行,包括当旧 updater 无法转发 run ID 时。

在现有 profile 上,更新历史准入会使用更新的步骤超时(默认 30 分钟,或 --timeout)等待数据库写入器。如果该等待超时,命令会成功退出,并带有延迟的 update-ledger-busy 结果和重试指引。它不会声称更新已完成,也不会创建运行;之前的历史仍然可见。dry-run 会在 notes 中报告不完整的预览。Repair 使用其现有 preflight 预算进行相同的准入。状态和后台历史工作保留更短的等待预算。隐藏的 Post-core finalization 在准入耗尽时返回非零退出码,并带有相同的延迟原因。其 Gateway 父进程会记录 skipped 结果,并保持 restart 待定,直到后续更新完成插件收敛。公开的 update、--dry-run 和 update repair 保留成功的延迟退出。此行为需要更新后的 CLI:先前安装的 updater 无法在自身历史准入完成前使用候选代码。

Triage 会保留原始更新报告。在 repair 期间启动的任何更新都会获得单独的 runId。

意外的自动更新活动失败会保留错误代码(如果存在)以及运行历史和 Gateway 日志中的脱敏诊断信息。状态和有界运行报告会在活动清除后显示原因。这需要更新后的 Gateway;旧运行无法恢复从未记录的原因。

被接受的 openclaw update --json 会包含 runId 和 run 记录。openclaw update status --json 在运行处于活动状态时包含 activeRun,在历史存在时包含 lastRun。自动更新活动会在其自身被接受的运行结束时停止显示为 applying,包括当托管交接在重启 Gateway 前失败时。Gateway 会对账确切的 campaign 运行,因此较新的无关运行不会让已完成的活动保持忙碌,也不会清除另一个活动 campaign。

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

如果未触碰的、无身份标识的 legacy 准入在超过 24 小时后仍停留在其初始 requested/in_progress 步骤,并且没有保留的恢复描述符,状态可以对账它。该行会以 reason legacy-driver-expired 作为 failed 保留在历史中。当该行是当前运行时,状态会显示重试指引。当另一个运行是当前运行时,状态会保留一条不带重试说明的历史通知,包括在后续成功更新之后。其他历史仍保持只读。

当活动行已不活动超过 30 分钟,且其记录的 driver 可验证地已死亡时,状态还会报告带有其 runId 和对账 rule 的 abandonedRun。对于这些行,状态仍保持只读:存储的行会保留在 activeRun 中,直到 Gateway 或显式 repair 提交结果。不属于 legacy-expiry 形态的无身份标识行不会自动对账。对于这些陈旧的无身份标识行,JSON 会包含带有 runId 和 guidance 的 staleRun;人类状态和 Doctor preflight 会报告“自 <time> 以来没有活动;如果没有更新正在运行,请运行 openclaw update repair 或启动新的 openclaw update”。

显式的新 openclaw update(包括 --dry-run)只有在它是唯一的活动运行、没有记录的 driver 身份标识,并且超过 30 分钟没有活动时,才会取代旧行。准入会原子地将该行结束为 failed,reason 为 superseded,并保留 reconcile:superseded 步骤,然后创建新运行。最近的行和带有记录身份标识的行会被保留。继承的更新延续和自动活动不会取代 legacy 历史。配置写入会保持暂停,直到活动行被对账。

OpenClaw 2026.9.2 可以在旧记录仍在运行时接受新的 CLI 更新; 过期记录不会阻止更新器准入。正常升级,然后如果状态仍显示 旧运行,请从更新后的安装中运行 openclaw update repair。参见 更新。

聊天完成通知会显示简短的结果和下一步操作。如需诊断 和恢复说明,请在 Control UI 中打开 Settings → Updates,或在终端中运行 openclaw update status。人类可读状态输出、Control UI 更新视图以及 openclaw status 更新行都会使用详细报告, 成功时也是如此。报告会显示已记录的事实;缺失的验证 事实表示该检查尚未被观察到。

如果恢复验证确认在更新失败后 Gateway 仍在提供服务, 终端和已保存的 Markdown 指导会指明该版本,并提示你在重试 openclaw update 之前先修复更新失败。更新仍保持失败状态; 服务健康状态不会授予重启或回滚的权限。重启安全性 和已迁移状态约束会单独保持可见。

只有当已保存的观察值和期望值不一致时,未成功的身份检查才会被报告为版本或构建不匹配。缺失的身份证据 会被报告为不可用,包括那些更新器仅保存了 versionMatch: false 的旧运行。 Control UI 的版本徽章对不可用的身份 证据显示 Not verified,对观察到的版本或构建不匹配显示 Failed。这不会 更改已记录的更新结果。

对于失败的运行,人类可读状态和已审核的失败报告 还会尝试向已记录的 Gateway 端口发起只读健康请求。响应 会取代 Gateway 已停止的历史声明;它不会更改 失败的更新结果,也不会验证回滚安全性。已保存的恢复建议会被标记为 历史,并保留配置和迁移约束。如果当前健康状态无法 读取,报告会说明这一点。JSON 运行记录仍保持为原始历史事实。

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

失败的更新始终保留原因代码和失败事实,包括在第一个命令运行之前发生的失败。Git 失败会使用诸如 fetch-failed、 git-root-unresolved、unsupported_git_channel 和 snapshot-capacity-insufficient 之类的代码。当恢复仍拥有该运行时,拒绝会使用 update-recovery-pending;其他未分类的失败会使用 update-failed。 当私有诊断文本必须脱敏时,检查和代码仍保持可见。

npm 失败记录会按顺序保留前五行已清理的错误行。超过 200 个 UTF-8 字节的行会保留前缀,后跟一个空格和明确的 …[truncated] 标记,且在该预算内。失败的包基线扫描会记录 baseline-scan-failed,并附带扫描的原始原因,包括其身份 回退也失败的情况。带有成功回退的超时仍保持为警告。

恢复权限拒绝会指明对象角色和 basename,观察到的模式、 链接数和所有者 UID,以及所需的私有模式和文件链接数。 安装路径和文件内容会被省略。请保留恢复证据; 在未识别其所有者之前,不要删除链接或更改权限。这些 诊断需要更新后的已安装更新器;候选更新器无法将它们添加到 已在运行的旧更新器中。

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

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

可恢复的维护失败即使更新成功也会显示为已记录的警告。最终控制台摘要、已保存的 Markdown 报告以及人类可读的 update status 会显示每条已记录的警告。成功的运行会将警告放在 信息性诊断之前, 包括已禁用的自动数据库恢复以及被保留但未重新应用的本地更改,并附带其已记录的恢复路径。简短聊天 摘要仍受大小限制。每条维护警告都会指明被跳过的工作、 原因和修复命令。 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 独立于 checkout 发现,报告当前自动更新策略和任何活动 campaign。安装详情可能稍后到达;读取状态不会启动调度或清除活动 campaign。如果无法解析更新通道,schedule 保持缺失,而不是声称调度器空闲。

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

原生服务停止观察不会推进更新记录的阶段。如果 Control UI 无法读取最新进度,它会与最后记录的运行一起显示读取错误;使用 检查状态 重试,而不会启动另一个更新。

阶段为 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 诊断失败仍为警告,而被拒绝的配置写入和不完整的必需迁移仍为错误。历史运行无法恢复其更新器从未记录的事实。

如果候选检查通过信号退出,其失败步骤会保留 termination、signal 和脱敏的 stderrTail(最多 80 行,每行 512 个字符,总共 8,192 个字符,存在时保留致命头部)。报告会命名该检查,包括 Doctor 的 检查数据迁移,并在相邻插件警告之前显示原生诊断。终端和本地 Markdown 报告保留摘录;简短状态报告可能会截断它。JSON 历史保留有界摘录,经过审查的公开报告保留终止类别和已识别信号。此捕获需要更新后的更新器;候选无法恢复旧安装驱动程序已丢弃的诊断。

当前更新器会记录其进程身份,并在较长的构建、安装和最终化阶段期间每 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。

不符合 legacy-expiry 形状的历史无身份行需要显式 update repair 或由操作员启动的新 openclaw update。仅一个旧的 requested 行并不能证明其更新器已退出:2026.9.2 更新器可能仍在等待包管理器或注册表预检,然后才记录其第一个暂存步骤。在显式恢复其过期行之前,请停止未记录的旧更新器。参见 数据库模式。

该运行会记录 downtimeMs,从服务停止请求开始,直到验证 Gateway 正在运行。暂存、候选项验证和激活前修复不计入。验证记录包括服务 PID/端口、版本/构建身份、已结算的健康状态、插件激活错误、通道就绪状态以及 /readyz。

从 2026.9.3 开始,使用事务性更新器时,候选项的新进程会在实时数据库迁移后完成验证,并将最终结果写入同一运行。它会延续激活步骤;模式升级不会创建单独的报告,也不会让旧更新器重新打开较新的数据库。

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

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