本页内容

本页内容

网关

重启恢复

对话、文字记录、计划作业、本机子代理记录和排队的出站消息都保存在磁盘上。网关重新启动时正在运行的主聊天会话始终进入自动主会话恢复,包括在崩溃、强制终止或错过关闭标记之后。无需操作员采取任何措施即可恢复它们。恢复始终开启。耗尽的基础设施重试或缺少持久消息操作权限声明可能会墓碑一个会话,直到您检查或替换它。

每个网关进程关闭都会保留符合条件的未完成轮次,包括普通 SIGTERM、systemd 或 launchd 服务 stop/restart 和 openclaw gateway stop。今天停止的网关将在明天启动时恢复工作,并且不会出现新的用户消息。关闭使用与托管重新启动相同的中断和恢复标记,并具有现有的耗尽期限。显式会话 Stop/cancel 保持终端状态。崩溃循环断路器、恢复重试预算、当前权限检查和 archived/reset 排除仍然适用。运行中的 cron 事件保持现有的重启处理;这不会添加中断事件的自动继续。

会话间转向更新仍然是执行转向的上下文。当该回合保留 Control UI、通道或经过身份验证的操作员源声明时,恢复将使用该声明,而不是将最新的引导消息视为新的委派请求。这包括经过身份验证的非浏览器客户端,其入口被标记为内部。在执行之前,网关在当前身份和访问策略下恢复准确的运营商源;已撤销的来源无法恢复。现有的来源授权和交付检查仍然适用;仅凭文字记录无法恢复丢失的发件人权限。

这包括在仪表板主会话中运行的自动化轮流。如果重新启动耗尽了其耗尽预算,即使提供者报告错误并且轮次在关闭发现错误之前就已解决,取消也会保留重新启动恢复。下一条可见消息会保留中断回合的恢复声明,即使其保存的状态失败、超时或终止。恢复会在新消息取得前台所有权之前恢复中断的工作。

本页介绍了重启后哪些内容会保留、如何检测中断的工作,以及自动恢复看起来是什么样子。

在启动过程中,新的回复会等待其代理的模型和插件运行时完成加载。已经准备好的代理可以在其他代理继续加载的同时提供回复。启动准备失败仍然报错。

HTTP 侦听器绑定后,中断的主会话标记与会话投影准备重叠。两者均在通道启动和网关报告准备就绪之前稳定下来。就绪后恢复重用已完成的存储检查,而不是重复该扫描。

重启后会保留什么

状态 存储 重启后的行为
对话历史 每个代理的 SQLite 数据库 不变;会话从已存储的记录继续
已接受 Control UI 后续跟进 每个代理 SQLite 待处理输入和浏览器发件箱 当浏览器重新连接时,匹配中断的输入将被重新接纳
被中断的主会话轮次 每个代理的 SQLite 会话行和记录 启动几秒后自动恢复或协调
子代理运行 SQLite(共享状态数据库) 中断的运行得到解决;家长决定如何继续
排队的出站传送 SQLite 传送队列 重启后排空;未传送的回复会重试
已计划的(cron)作业 SQLite cron 存储 计划会保留;调度器在启动时重新启用
重启后续 SQLite 重启标记 向请求重启的会话分发一次性后续操作
后台执行进程 进程内存;会话行中的通知义务 流程结束;符合条件的拥有会话唤醒一次,结果未知
网关终端 PTY 进程内存 结束旧流程;终端会话未恢复

Control UI 将接受的文本和附件保留在其发件箱中,直到网关确认转录消耗。重新连接后,它会检查保存的收据,然后通过正常身份验证和会话准入重新提交中断的输入。旧的队列和执行权限永远不会被重用。这会保留每个浏览器发件箱的顺序,而无需再次提交已使用的消息。不同的浏览器可以以不同的顺序重新连接。

请求在调度前被拒绝,并且聊天发送在等待会话准入时​​中断,返回可重试的 UNAVAILABLE 错误,其中包含 details.reason: "gateway-restarting"。重新启动不会将未启动的消息转变为最终停止结果。 Control UI 和本机聊天发件箱保留原始消息 ID 并在网关可用后重试。本机 Apple 带附件的实时发送恢复草稿以进行手动重试;已排队的附件保留其发件箱恢复。

断开连接的 RPC 可能已经执行其工作。客户通过现有的收据和历史记录来协调已接受或不确定的发送,而不是自动重播每个待处理的 RPC。已经运行的主会话轮流使用下面描述的恢复所有者;排水预算不变。

在 ACP 执行或问题消耗之前,接受的 Control UI 输入将提交到其承认的源会话。如果会话路由到绑定的 ACP 会话,则源保留原始请求,并且绑定会话拥有 ACP 记录和回复。输出持久性失败不会使消耗的输入符合自动重新提交的条件。

如果浏览器不再具有匹配的发件箱有效负载,则保存的中断输入仍可用于显式重新发送。取消的输入不会重播。旧版本接受的没有可恢复托管的输入也需要显式重新发送。不确定的提交将保持未确认状态,直到其结果可以协调或用户选择重试。恢复记录中已经存在的回合并不依赖于浏览器的返回。

已接受的 sessions_send 代理更新从其保存的输入和原始交付 ID 中恢复。临时准入、工作线程容量和存储就绪故障最多可尝试 3 次,两次尝试之间等待 5 秒,然后等待 10 秒。每次尝试都会再次检查原始源会话和目标会话以及当前的通信权限。重置、替换、存档或拒绝权限的会话会停止自动传送。未知的故障和耗尽的重试会保存输入,并在恢复通知详细信息中记录固定的故障原因代码和尝试计数。该通知解释了失败并指导您重新发送更新或要求发件人重试。详细的诊断信息保留在操作员日志中。恢复永远不会重新运行发件人任务或恢复旧的批准。

当更新替换捆绑的 Control UI 时,打开的选项卡会在网关报告新版本后重新加载。报告的构建的自动恢复和手动重新加载共享有限的文档就绪检查,因此暂时失败的检查不会立即搁置选项卡。通用惰性块故障会进行一项自动检查,并将进一步的恢复留给可见的重试操作。浏览器仍然将自动导航限制为每个目标构建一次重新加载。如果网关仍然不可用,请在可访问时使用可见的重新加载操作。

降级到 v2026.9.2 会保留较新的已接受输入记录,但该版本会在执行前拒绝对保留的较新收据进行相同的 ID 重试。这包括排队或中断的输入以及消耗的收集输入收据。已消费的收据仍排除在待处理计数之外。单独消耗的输入已经离开待输入存储并保留正常的转录重复预防。如果会话和接受的输入尚未更改或删除,则再次升级会通过新的身份验证和准入来恢复匹配的未使用输入恢复。已经消耗的输入仍然被消耗。不要仅仅为了绕过降级冲突而删除收据或更改消息 ID。

本机 Codex 恢复会在当前附件策略和上下文限制下重建保存的文档内容。 Codex 插件拥有该本机输入路径:与网关一起更新其工件。故意固定的旧插件不会从仅核心更新中获取修复。

已进入具有出站通道路由的父轮次的分离harness完成可以保留准确的源完成、终端结果和请求者会话声明。崩溃后,主会话恢复将继续该已承认的轮次,而无需再次启动子进程。原始完成标识仍然与恢复运行不同。即使旧的本机监视器不再存在,保留的最终收据也会解决承认的完成情况;待处理的追偿索赔不是已交付的结果。较晚的结果不能授权较早完成的输入或结算其收据。取消、会话替换以及源身份缺失或矛盾不授权重播。保留的准入或仍然有效的准入输入会使恢复处于挂起状态。本机父轮换必须保留当前连接和请求者身份检查。稍后的父级注册无法提供缺失的历史所有权。

排队的请求者最终还保留其原始完成源以及最终交付意图。命令准入在执行前对源、会话生命周期和路由进行快照;刷新的缓存无法为后续运行提供后续资源。捕获的路由上的已识别发送会在队列确认之前记录持久接收,包括当终端清理已经撤销活动恢复声明时。其批次中的每个逻辑最终负载和每个物理负载都必须具有成功识别的交付证据。报告的收件人和线程(包括嵌套聚合收据部分)必须与捕获的路由匹配;省略的提供商元数据保留现有的渠道合同。稍后的清理无法用较早的捕获替换该收据,并且较新的请求者或不同的路由无法借用它。空的、未发送的、被抑制的或不确定的结果不会建立交付。现有的丢失收货记录不会在交付时追溯处理。

即使保存的运行状态失败、超时或终止,中断的承认完成也会保留其完整恢复声明。下一条可见消息或排队的后续消息将在取得前台所有权或进入活动转录本之前恢复该恢复。会话重用不得将旧的完成附加到新消息。恢复仍然检查已接受的输入、请求者生命周期、交付收据和重放安全性;它不会从终端运行状态推断交付。

在父完成准入之前,本机 Codex 挂起分配在现有父绑定元数据中保留其运行、子线程、本机父和已知本机轮次标识。接受的跟进者也可以在那里保留他们的提交收据。不会创建新表或任务记录,也不会导入历史任务行。当父级再次注册时,恢复会根据主机发出的新完成权限读取已保存的作业和本机历史记录。它在恢复观察或路由结果之前检查原始请求者会话、生命周期、连接和子沿袭。本机父线程轮换可以在同一请求者生命周期和连接中保留该元数据;重置、请求者生成替换或连接策略更改并不授权采用。失踪的历史所有权仍然未知。此恢复需要保留分配和新的家长注册;原生血统本身并不能重建未记录的完成义务。

上述承认的轮次恢复适用于新记录的通道传递声明,而不是无路由、仅转录本或 Control UI 父代。它不会恢复每个较旧的本机完成。进度消息、空的或被截断的收据以及不确定的发送无法建立最终的交付。必须更新网关和 Codex 插件才能恢复加入。即使没有 SQL 架构更改,较旧的版本也可能会在重写会话元数据时丢弃添加的收据字段。降级前完成待完成恢复;不要删除已使用的输入或更改源 ID 来强制进行另一次交付。

待交付行耗尽或重新启动后重试。当交付耗尽其重试预算时,恢复将收回过期的生产者保管权。活跃的生产者保留所有权。失败的传送不能再次发送,但保留解决其所属会话或对话所需的信息。如果更新失败或网关崩溃,恢复将恢复更新而无需重新发送消息。结算后,失败的行丢弃其有效负载。只有可重复使用或崩溃模糊的所有者才会保留最小限度的有界或永久收据,以防止重复交付。交付不确定性通知会保留其确认,因此重复结算无法再次通知相同的意图。

在降级之前完成待决和解。较旧的版本可能会在数据库修复期间丢弃其元数据,或者在重写会话记录时删除已确认的通知,即使架构版本未更改也是如此。有关降级预防措施,请参阅 数据库架构。

优雅重启会先进行排空

启动迁移警告不会阻止网关启动。它记录一次警告并开始降级。 openclaw status和openclaw doctor显示正在运行的网关的警告报告。只读操作员会收到修复提示。警告详细信息仅限于管理员和启动日志。针对同一 state/config 运行 openclaw doctor --fix,然后重新启动网关。未完成的迁移仍待稍后启动。导致所需状态读取不安全的错误仍然会停止启动。

请求的重启(openclaw gateway restart、需要重启的配置变更,或网关更新)不会立即终止正在进行中的工作。网关会停止接受新的工作,然后等待活跃的代理回合和后台任务完成,最长等待一个排空预算(默认 5 分钟)。因此,大多数重启根本不会中断任何内容。

在 Linux 上,关闭会在关闭其生成代理之前通过 IPC 关闭空闲池数据库读取器;活跃读者保留现有的取消宽限。

CLI 关闭会消耗全流程工作。关闭单个网关会耗尽其自己的活动聊天运行和排队轮次,并等待进程范围的挂起回复计数。两者都将剩余工作报告为指定计数;类别可以重叠,并且不应作为不同的轮次添加。

在最终清理过程中,转录索引协调需要五秒钟的时间才能完成。之后,关闭会记录停滞的工作线程,取消进一步的投影工作,并终止其本机任务。在关闭代理数据库之前,它仍然等待接受的写入和数据库租约清理。承诺的成绩单保持完整;重新启动后会重新发现未完成的索引工作。闲置池立即关闭。一旦正在运行的网关包含此修复程序,这也适用于更新重新启动。

当网关连接开始关闭时,会话观察者事件订阅会在观察者关闭之前停止。接受的观察者工作仍然稳定,而聊天事件和终端会话写入则继续通过它们自己的消耗。

如果数据库关闭拒绝后续的排出,则排出会停放其排队的输入,而不是针对关闭所有者重试。重新打开数据库准入后,新的排出请求可以恢复它;持久输入恢复拥有重启重放。

只读 RPC 等待(agent.wait、批准决定等待、question.waitAnswer 和 device.scopes.waitUpgrade)在其客户端断开连接时停止观察。当关闭耗尽开始时,连接的等待者会收到可重试的 UNAVAILABLE 错误,原因为 gateway-restarting,因此客户端可以重新连接并再次等待。这些等待不会消耗停止流失预算。底层运行、决策和已承认的写入保持其正常的消耗和恢复行为。一旦正在运行的网关包含此修复程序,这也适用于更新重新启动;安装新文件无法更改旧网关进程已持有的等待。

对于已接受的 WebChat 轮次,当队列准入完成时(包括准入前开始等待的时间),agent.wait 会报告 pending 和 timeoutPhase: "queue"。排队未完成轮次运行 ID。

Cron 关闭提供执行清理,持久结果写入相同的清理窗口。完成作业的执行本身并不能完成消耗:结果持久性还必须解决,或者网关在窗口到期时报告剩余的工作。这些排水管稳定后,就会报告退出观察程序故障。

在 Linux 和 macOS 上,当启动从不受支持的 Node 版本恢复并且服务管理器跟踪启动器父级时,这也适用。启动器转发停止信号并等待服务网关耗尽共享服务预算。托管重启意图针对实时服务所有者,因此当其消耗预算到期时,未完成的工作仍会遵循重启恢复。当 launchd 驱动停止时,macOS 使用运行作业自己的 ExitTimeOut,当启动器位于路径中时,由启动器自己的停止计时器限制,并且 Linux 单元使用自己的停止超时;两者均在下面的截止日期部分进行了描述。这需要使用更新的启动器启动网关:替换文件无法更改已在运行的启动器。在 macOS 上,标记的启动器父级保留保守的 19 秒子级截止时间,因为其现有标记无法识别它是否加载了旧的或新的停止策略。

对于这些托管重启,如果 CLI 无法验证服务命令、服务所有者或重启意图记录,它会在向 GATEWAY_RESTART_PREPARATION_REFUSED 发送信号之前拒绝重启。恢复服务检查或状态访问,验证网关状态,然后重试。未经验证的启动器 PID 绝不是后备方案。

运行 2026.9.4 网关通过其发布的状态本地锁身份仍然符合资格。在准备重新启动之前,CLI 会验证服务安装、实时进程启动身份以及该本机服务中的成员身份。过时或不匹配的身份无法授权重新启动正在运行的服务。一旦前任所有者被证明死亡,不活动的服务仍然可以启动而无需重新启动意图。

在 Linux 上,systemd 设备必须使用 KillMode=mixed,以便初始停止信号仅到达网关。当网关退出或其停止期限到期时,Systemd 仍会终止剩余的子进程。较旧的 KillMode=control-group 装置会立即向子运行时发出信号,这可能会在排水完成之前中断转动。生成代理在其网关连接处于活动状态时保持可用,即使它也收到停止信号,因此清理仍然可以启动命令并观察子进程退出。这不会保护其他子运行时; KillMode=mixed 仍然是必需的。更新和 openclaw doctor --fix 刷新过时的 OpenClaw- 托管 Linux 单位策略。维护从网关状态读取常驻关闭预算。没有这一事实的旧网关遵循短期预算路径:围栏准入并观察生命周期消耗,直到空闲或更新步骤截止日期。在截止日期时,未完成的写托管拒绝与其所有者阶段停止;剩余的转弯可以通过记录警告来中断。操作员拥有的插入装置必须单独检查和更新,因为重新安装基本单元可以保留它们。请参阅 Linux 服务。

维护保管观察

网关 status 报告其进程拥有的 shutdownBudget,以及 activeWork 计数和单独的 writeCustody 阵列。暂停准备和状态响应还包括带有 phase 和 count 的可选 writeCustody 条目。当前阶段包括迁移、备份、协调器写入、会话生命周期突变和终端持久性。这些由其运营所有者记录;普通的 root 请求和 cron 运行并不意味着写入托管。计数可以重叠。

可选字段是可加的。较旧的网关,包括已发布的 2026.9.5,可以省略它。丢失保管信息绝不拒绝维修。如果更新步骤截止日期到期,维护将停止并发出警告,其中包括最新的根请求和 cron 运行计数、解释驻留程序缺少的区别,并确定下一个网关的刷新停止策略。只有报告的实时写入托管阶段拒绝截止日期停止。

Systemd 停止期限

在启动和接受关闭时,网关读取其正在运行的 systemd 单元的有效 TimeoutStopUSec,包括插入。它会记录两个点的源和协调的停止预算,因此修复后的单元无需先重新启动即可生效。检查和任何等待启动完成的操作都会消耗相同的关闭期限。活动工作消耗最多使用 315 秒来请求重新启动,最多保留 10 秒用于最终聊天写入和服务器清理,并在 systemd 的截止日期之前最多再保留 5 秒。对于请求的重新启动,具有默认 90 秒停止超时的设备将获得 75 秒的耗尽时间和 85 秒的网关关闭期限。较短的主管超时也限制了请求的重新启动等待。

普通停止(包括没有托管重启意图的 systemctl restart)会在记录恢复和中断执行之前为活动运行提供最多 20 秒的时间来完成。未完成的任务仍有资格进行下次启动。最终聊天写入、工作树租约释放、检查点和数据库关闭保留剩余的本机关闭预算。关闭会在完全处理处置之前解决收到的工作并停止挂钩,然后在工人退休之前加入工作树租约,以便运行的终结器可以释放其租约。在加入收到的工作之前,代码单元会被取消。这可以避免租约连接阻塞完成它所需的拆卸。干净的数据库关闭还可以避免下次启动时进行陈旧租约完整性扫描;中断的关闭仍然需要该扫描。

Codex 本机配置文件恢复警告作为服务拥有的后台工作运行。当另一个代理的数据库准入完成时,它不会保持就绪状态。医生仍在等待相同的诊断,并且关闭会加入任何已经开始的诊断读取。

当截止日期无法为它们提供资金时,这两项津贴都会受到限制,按照 launchd 预算使用的相同规则,出于相同的原因:从短暂的停止超时中减去 315 秒消耗的两个值,将其完全消耗掉,而使活动工作一无所获。 TimeoutStopSec 为 20 秒或更长的单元保留其已拥有的分配,减去停止检查本身的成本,而不是精确到毫秒:20 秒只是为整个 10 秒储备提供资金以及在该成本结束之前消耗 5 秒的时间。低于这个期限,就无法同时为两者提供资金,并且储备金收益率会保持消耗:一个单位在 15 秒或以下,现在会在之前消耗 0 毫秒的地方完全消耗,并且用储备金的一部分换取低于 5 秒的消耗的四个值。储备金永远不会低于停工预算的一半。退出余量将其完整的 5 秒降低到 20 秒的截止时间,并在 15 秒和任何更短时间的四分之一处缩小到低于该截止时间的 3.75 秒。耗尽的工作、排序和中断行为保持不变,并且 systemd 自己的 90 秒默认值不受影响。

服务子级清理使用剩余的网关关闭预算,为最终退出簿记留出时间。强制重启会耗尽相同预算内已承认的工作。重启调度程序的空闲延迟到期后,就会开始正常的消耗:新的工作被隔离,并且承认的工作获得计算的宽限期,但仍然受到本机关闭截止时间的限制。推迟时间不会花费关闭预算。对于主管的 SIGTERM 重新启动,当活动运行被中断时,而不是当数据库清理必须完成时,请求的消耗限制更短:清理可以使用剩余的本机停止预算。中断的外部重新启动后,网关会加入最终的聊天持久性,耗尽内存的数据库借用,并在退出之前关闭代理数据库。它跳过插件和通道拆卸,可以将流程保留到截止日期。数据库准入通过锁释放和日志刷新保持隔离,最后有一个五秒的退出窗口。关闭日志报告每个至少需要一秒钟的清理步骤,包括其名称和经过的毫秒数。截止日期出口列出了当前待处理的清理步骤以及每个步骤等待的时间(最多八个,以及其他任何步骤的计数)。这些诊断始终处于启用状态; OPENCLAW_GATEWAY_RESTART_TRACE=1 还为快速步骤添加了 begin/end 时序。主管的截止日期仍然是硬性上限。仅在写入器租用、检查点和本机连接关闭解决后,才会发布干净的数据库重新启动证明;仅一个数据库的空闲收据并不能授权进程退出。

当人员流失开始时,工人安置维护将停止接纳新候选人。可选的会话证据读取和磁盘探测被取消。 Node 保留停止新的准备并取消支持的请求;正在进行的共享捆绑包构建保持连接状态。已接受的停用、工作区恢复、回收或发布效果在其数据库或传输关闭之前仍会稳定下来。稍后重新启动将从持久状态恢复延迟维护。截止时间诊断命名待处理的放置子阶段,例如 shutdown.worker-placement.reconcile.session-retirement、reconcile.active 或 reconcile.publications。这些连接使工作人员传输和共享数据库保持可用,直到接受的效果记录了其结果。

在没有主管交接的情况下重新启动会使用现有的关闭期限进行清理。这包括另一个服务的 cgroup 内的前台网关,以 OPENCLAW_NO_RESPAWN=1 重新启动,以及必须启动自己的替换的独立更新。仅 Cgroup 成员资格并不能提供取代网关的主管。普通取消在强制终止之前保留五秒的宽限期。在关闭期间,在确认其拥有的进程消失后需要强制终止的继电器会产生警告。完成清理后,网关的退出状态为零;未经确认的进程清理边界仍然报告失败。

进程的 cgroup 选择系统或用户管理员,与运行网关的帐户或其重新启动所有者无关。这还涵盖带有 User=openclaw 的手写系统单元和外部管理的部署。读取系统单元的超时不需要 sudo 或通知支持。

如果在启动时无法检查设备,网关会向管理器、设备和故障原因发出警告,并使用 systemd 的 90 秒默认值作为保守的后备措施。失败的关闭重读会保留启动预算,并扣除已用时间,而不是假设更长的超时。明确无限制的超时可保持正常的网关预算。已经运行的 v2026.9.5 网关会保留其启动读数,直至重新启动;安装较新的文件无法更改旧进程捕获的关闭预算。

一旦新网关启动,已安装的旧单元即可受益于钳位,而无需重写服务。这为有序关闭留出了时间,而不是在耗尽整个停止窗口期间。无法解决的工作仍采用现有的中断和恢复路径;较短的预算不能保证任意清理工作的完成。 CLI 安装并指导 Doctor 服务修复,使 TimeoutStopSec=330 与网关采用相同的策略。医生报告有效停止超时低于该要求。运营商拥有的临时服务仍然由运营商负责。

对于手写系统单元,至少允许 drain + 15 秒。使用当前最大消耗,创建 /etc/systemd/system/openclaw-gateway.service.d/stop-timeout.conf:

ini
[Service]TimeoutStopSec=330

运行 sudo systemctl daemon-reload 并使用 systemctl show openclaw-gateway.service -p TimeoutStopUSec 进行验证。通过服务的部署所有者重新启动。对于用户单元,使用 systemctl --user edit openclaw-gateway.service 和相应的 --user reload/show 命令。如上所述保留KillMode=mixed;较长的超时并不能保护儿童免受 KillMode=control-group 初始信号的影响。

在耗尽期间,对挂起的节点命令的回复仍然被接受,包括通过关闭启动的工作进程清理。每个回复仍必须与其实时调用、节点连接、配对生成和拥有生命周期相匹配。这使得清理工作无需等待命令超时即可完成。它不会针对新请求重新开放。

操作员还可以在网关耗尽时检查并回答悬而未决的问题或解决审批问题。这些请求必须属于关闭前承认的仍待处理的工作;正常的授权检查仍然适用。新的质疑和批准请求仍处于搁置状态。

无法在耗尽预算内完成的工作将在关闭所有者中止之前标记为恢复。结束前奏会隔离新的请求条目和后台生产者,而不会取消收到的执行或退出其内部主体。运行关闭所有者记录恢复情况,然后在处理开始之前取消排队的轮次、答复和接收的执行。这使得恢复标记可以使用实时入场,而不是依赖于已经发布的所有者。先前的重新启动取消不会从标记者的候选者中删除仍然拥有的运行。如果无法标记提供的候选者,则会出现警告,报告计数和主要跳过原因。

当无法写入批量关闭标记时,重新启动取消还可以保留可恢复性。由同一网关重新启动中断的本机运行时准备将被记录为重新启动取消,而不是提供程序故障。显式的用户取消和真正的执行超时仍然是终端。恢复启动使用已承认的运行的现有截止时间,包括运行时准备和等待会话或全局容量。在健康队列中等待不会消耗单独的失败启动尝试。

sessions.abort 在确认成功之前等待取消的会话写入。即使运行的终结器尚未完成,确认后立即重新启动也会保留最终结果。这也适用于在等待生成任务时产生的父级:成功停止其子级会在确认之前记录捕获的父级取消,而不会覆盖该会话中较新的轮次。如果无法阻止另一个孩子,响应仍然报告不完全取消;捕获的父级的取消在该错误之前保留。

启动停止期限

在 launchd- 驱动停止时,macOS 网关会读取 loaded 作业的有效 exit timeout 和 launchctl print。它检查系统、GUI 和用户域,并仅接受 PID 是网关或其启动器的作业。重启所有权仍然可以是外部的:强制停止的主管,而不是下一次启动的所有者,决定最后期限。直接 SIGTERM 不会启动 launchd 的停止时钟,因此它会保留现有的网关停止策略,除非 OpenClaw 启动器独立强制执行其自己的子收获计时器。

stop 预算 是可用的,直到主管可以终止该进程为止。网关留出退出时间(最多 5 秒)并计划在剩余时间内关闭。 Drain 是关闭的第一部分:停止接受新工作并等待活动轮次和后台任务解决。其余时间保留用于最终写入和服务清理(最多 10 秒)。网关记录所选的源、漏、关闭期限、储备和退出余量。

新的 LaunchAgent plists 请求 ExitTimeOut=330,源自与 Linux 的 TimeoutStopSec=330 相同的服务停止预算。在这个有效期限内,名义上的分割时间是 315 秒的排空时间、10 秒的清理时间以及主管期限之前 5 秒的时间。仅当定义与已停用的生成模板相匹配时,openclaw doctor --fix 才会备份已停用的安装程序值 20 秒并将其迁移到 330。自定义定义中的 20 秒超时是不明确的:医生报告说它低于消耗预算并保留它。仅安装人员的评论并不授权更换运营商的政策。报告并保留其他显式值,包括 600 和无限制 (0);短自定义值会收到警告。更新完成使用相同的备份服务协调。第一站仍然遵守先前加载的作业的截止日期,直到引导替代作业。

检查作业所花费的时间将被记入借方。传统的 20 秒作业名义上会留下 5 秒的耗尽时间、10 秒的清理时间和 5 秒的退出余量。对于较短的自定义截止日期,退出余量最多为四分之一,并且清理储备让位于使活动工作最多消耗 5 秒(当非常短时,最多为剩余关闭预算的一半)。例如,一个 5 秒的作业名义上在其 1.25-second 退出裕度之后留下 1.875 秒用于排出和清理; 15 秒的作业会留下 5 秒的消耗时间、6.25 秒的清理时间以及 3.75-second 的余量。 这将自定义作业的清理时间减少到 20 秒以下。 默认的 systemd 90 秒截止时间不受影响。检查最多可以消耗 3 个 2 秒的调用;非常缓慢的检查不会留下任何漏水。

如果 Node-recovery 或编译缓存启动器是作业的 PID,则其自己的子收割计时器可能比 launchd 的截止时间短。仅当网关的重生标记确定该启动器启动了它时,网关才会在该计时器上限制其预算;无血缘关系的父母不会缩短预算。新启动器使用共享的 330 秒服务预算,但子启动器保守地保留旧的 19 秒启动器上限,直到父运行时生成合约可以区分已经运行的启动器。单独提高 plist 值并不能消除该上限。

发送到标记启动器的直接信号可以启动其自己的计时器,而 launchd 仍报告 running。网关无法区分转发的信号和发送给其子级的直接信号,其中启动器没有计时器,因此它不限制这种情况。直接停止启动器的操作员应该使用加载的作业停止来获得可执行的报告截止日期。

ExitTimeOut=0 表示没有 launchd 停止期限,不是缺失值。如果没有启动器计时器,网关将保留其普通策略,并且不会将作业归类为本机截止日期。不可读的作业会保留现有的停止策略并发出警告,而超时缺失的已确认停止作业则使用 launchd 的 20 秒默认值并发出警告。

该值来自作业 launchd 有 loaded,而不是磁盘上的 plist。编辑 ExitTimeOut 或运行 launchctl kickstart -k 不会重新加载它; launchctl bootout 随后执行 launchctl bootstrap 操作,重新启动网关。每次停止读取可以避免过时的启动快照,而不是过时的加载作业。在 macOS 27 上,launchd 最多报告 60 秒,即使 plist 要求更多;检查加载的作业以确认有效值。

主机休眠与进程冻结

当网关主机从睡眠中唤醒、虚拟机恢复或进程在长时间暂停后继续运行时,网关会在大约 30 秒内检测到冻结。一旦跟踪的网关工作空闲,它就会重新启动通道连接,然后刷新缓存的运行状况和状态。当繁忙的网关仅延迟通道重新启动时,运行状况和状态刷新仍会运行。当繁忙的事件循环导致计时器间隙时,这可以防止过时的套接字等待其正常到期,而不会中断活动回复或代理启动。

睡眠和向后调整时钟本身并不取消国家所有权。经过心跳间隔后,网关会在更新锁之前验证其锁的物理身份和获取字节。移除或更换的锁,或者更新仍然失败,会隔离状态访问。当受防护的数据库无法提供存储的重启意图时,本地授权的恢复仍然会重新启动网关;原始未经授权的重启信号保留其现有策略。更新到此行为时无需配置或数据库迁移。

macOS 应用和 Linux companion 会与本地网关协作,在主机休眠前准备一个短暂的挂起租约,并在唤醒后恢复该租约。应用主机休眠时,远程网关不会被挂起。通过 gateway.suspend.* 进行的主动挂起会让恢复保持延迟状态,直到控制器恢复网关。

更新失败后恢复

交互式更新或修复失败后,OpenClaw 完成清理和任何服务恢复,然后打开 openclaw triage。 Triage 立即按以下顺序启动第一个可直接启动的编码代理:Claude Code、Codex、OpenCode,然后是 Pi。它会在新的 Doctor 检查或归档收集之前传递捕获的故障,并要求代理诊断、修复和验证安装。代理接收捕获的安装路径并保留其正常的身份验证、沙箱和批准设置。

对于失败的 Control UI 或无人值守更新,请使用网关主机上打印的特定于安装的命令,或使用相同的 OpenClaw 配置文件和 state/config 路径在此处运行分类。使用 --agent 选择特定的编码代理:

bash
openclaw triageopenclaw triage --agent codex

JSON、--yes 和非交互式更新调用无需启动外部编码代理即可收集诊断信息。 openclaw triage --non-interactive 还可以在不启动代理的情况下准备诊断。 --update-result <path> 包括更新程序保存的故障工件。打印的切换命令保留安装选择器,并在 Windows 上使用 PowerShell 或在 macOS、Linux 和 WSL 上使用 POSIX shell。

登台和验证在旧网关运行时运行。候选人运行 Doctor lint、配置和插件规划,以及针对复制的配置和经过验证的数据库快照的隔离金丝雀启动。这些副本上的迁移会演练升级而不更改实时状态。验证失败可以进入 有界无人值守修复 ,同时旧网关继续服务。激活需要通过失败的检查。否则该候选人将被丢弃。 already-current 无操作永远不会停止网关。迁移继续之前的较旧目标将运行时验证记录为不可用,并使用 现有降级最终路径 。分离的助手还在停放其父网关之前等待 activating 阶段。第一个激活窗口包含交换、所需的实时迁移和服务启动。插件包下载和同步在核心网关服务时运行。更改的插件快照需要第二个测量的激活窗口:在独家维护下进行完整的 Doctor 迁移,然后重新启动并验证。未更改的插件不会运行另一个完整的 Doctor pass。

激活后,更新程序验证托管服务正在运行并拥有其端口,网关问候握手与预期的 version/build 身份匹配,12 检查运行状况稳定通过,插件和通道正常,并且 /readyz 返回 HTTP 200。更新验证不使用模型推理。 Startup 接收更新的现有每步 --timeout 预算(默认情况下为 1800 秒),包括迁移和侦听器初始化,然后是 12 检查结算窗口。在旧版本的第一次更新中,旧更新程序会调用新安装的 CLI,但不会超过该准备预算。候选者识别现有的更新标记,并且一旦托管进程运行,就使用五分钟的启动看门狗而不是独立的 60 秒截止时间。迁移、侦听器和运行状况转换不会重置此界限。旧更新程序的子进程超时也仍然有效。耗尽等待报告最后观察到的启动阶段。独立重新启动使用 进度门控就绪等待 。验证事实和测量的停机时间保留在 更新运行报告 中。

当包验证失败时,更新程序会比较共享的和受影响的每个代理SQLite user_version值和配置内容及其预激活值。如果它们未更改并且在激活之前验证了先前的运行时,则会恢复先前的包、命令填充程序、服务定义和配置编写器标记,然后启动该运行时并重复CLI验证检查。成功恢复使网关运行并完成rolled-back,将失败的检查保留为原因,并通过验证恢复来涵盖服务停止的停机时间。作者印章保护不会阻止这种有意的恢复。其允许范围仅限于回滚服务命令并且从不持久。看自动回滚。如果配置内容或schema版本发生变化,则拒绝自动回滚(state-migrated-no-rollback)并且更新程序尝试对已安装的候选程序进行有限修复。当回滚本身失败时,可以运行相同的修复槽。代码回滚无法逆转状态迁移。不可用的模式比较也会阻止自动回滚(rollback-state-unverified)。迁移后,新的候选进程完成验证和相同的持久运行报告。旧的更新程序不会重新打开较新的数据库。实时迁移之前的 Git 激活失败可以恢复之前的源并保留构建的运行时。后来的 Git 故障保留了诊断的候选者。

更新失败本身并不授权候选重新启动。候选激活仍需要成功验证。阻止实时医生结果不会成为重新启动补助金。之前的运行时在更新之前已进行验证,因此回滚未更改的配置和架构可能会在之前的验证下重新启动它,并且必须在之后再次验证。分离的帮助程序或 Windows 任务自动启动无法绕过此决定。

在激活后修复期间,编排器每轮后启动或重新启动已停止或不正常的服务一次,然后重新运行验证。通过检查即可让运行成功。如果回滚已恢复到先前版本,则成功修复完成 rolled-back 并且该命令仍以非零值退出。否则会失败,并附有原始原因和修复摘要。代理无法发出服务生命周期命令。

在 Windows 上,捕获的计划任务自动启动通过 Doctor 终结保持暂停状态。如果最终验证失败(包括在迁移状态切换之后),更新程序将启用任务以进行激活并恢复暂停。本机任务控制故障出现在更新报告中。失败的暂停永远不会触发被拒绝的安装的自动重新启用。

在 macOS 上,终止的更新帮助程序可以使选定的网关 LaunchAgent 保持安装状态,但在登录时卸载并禁用。 openclaw doctor 和 openclaw doctor --fix 诊断此状态。成功独立修复后,--fix 启动并验证已停止的托管网关,其服务针对当前安装。更新时医生将激活留给更新程序。如果更新中断或安装安全性不确定,请重新运行 openclaw update 或在手动启动之前使用 Doctor 和 triage。验证后,运行 openclaw gateway start(或 openclaw --profile <profile> gateway start)以重新启用并启动该服务。保留相同的 state/config 和自定义标签覆盖。 Doctor 打印选定的标签和恢复命令。 Interactive Doctor 可以提供引导修复。

包突变之前的取消可以将原始服务恢复到其现有的切换所有权下。仅当网关通过正常的重新启动运行状况检查并报告经过验证的安装版本以及准确恢复的版本 ID(对于 Git 恢复)后,恢复才会成功。仅匹配的包版本无法区分两个 Git 版本。服务管理器接受启动请求或报告实时 PID 是不够的。一旦分离的助手启动更新程序,缺失、畸形、过大或中断的直接结果就会将激活留给操作员。这比在未分类故障后重新启动的旧帮助程序更严格。安装新目标不会更改已经运行的历史帮助程序。这些检查适用于启动更新的帮助程序版本。

激活前跳过的更新不会停放或重新启动网关。如果停车后发生中断,帮助者会使用孩子经过验证的恢复决策并保留原始原因。仅当所需的恢复成功或子级已验证它时,才会保留零退出。

仅当上一代无法安全恢复和验证时,更新程序退出代码 79 才会使网关处于停放状态。当更新程序在未更改的配置和模式中恢复上一代并提供经过验证的恢复决策时,帮助程序将启动并验证它,而不是让它停止。帮助程序恢复验证服务活跃度、version/build 身份、插件激活和通道运行状况。它不会重复单独的 /readyz 检查。该报告字段尚未得到验证。然后,运行使用先前版本完成 rolled-back 并测量停机时间。丢失恢复证明、迁移状态或恢复失败仍然需要在重新启动之前进行修复。观察到已停止的服务将被记录为已停止。该报告不会重复使用其激活前的运行状态。

当稍后的服务恢复或分类修复成功时,终端失败的更新仍然存在非零值。在恢复之前尝试错误和跳过通知。在恢复网关消耗它们后,助手不会重新创建它们。检查最终的 CLI 结果和恢复结果的切换日志。

重新启动之前修复失败的 Doctor 或安装检查。分类可以检查 openclaw gateway status --deep 和更新诊断。避免在新版本迁移配置或数据库后盲目安装旧代码。请参阅 更新和恢复 。重新启动哨兵报告结果。复制一个服务并不授予重新启动服务的权限。

如何检测中断的工作

持久会话状态仅记录运行结果:done、failed、killed、timeout 或 interrupted。新的运行会清除之前的结果;会话行从实时运行注册表和队列所有者派生 running 和 queued。重新启动中止的运行记录 interrupted、中断原因及其结束时间,同时保留恢复所有者的声明。

新输入遵循实时回复所有者的队列策略。如果没有实时答复,持久执行围栏必须有最终证据才能允许其退出。成功的最终交付清除了其待决意图和任何无人认领的恢复路线,同时保留更新的执行或交付索赔。

在准备就绪之前,启动会调用共享的 Doctor 转换,将较旧的持久 running 或 queued 值标准化为 interrupted 一次,但已验证的遗留收益保留未设置的结果,以便其子延续保留所有权。它记录已修复的计数,保留恢复声明和记录,并保留活动时间戳。没有索赔的合格旧 running 条目在其旧状态被删除之前将获得恢复保管,从而保留其现有的自动恢复路径。保存的结束时间将被保留或回退到条目的最后一次持久更新。

归档会在提交归档之前耗尽并取消会话的工作。现有的运行结果、恢复收据和待交付元数据保持不变;恢复存档会话不会恢复其取消的执行。未存档的主会话保留其单独的恢复路径如下。

三个相互补充的机制会标记那些回合未能完成的会话:

  • 依次入场: 用于打开现有主会话的普通文本,网关附加用户消息,清除之前的结果,并在模型或 before_agent_reply 钩子执行之前将其恢复交付声明记录在一个 SQLite 事务中。 Control UI 在返回 started 确认之前执行此操作。当准备轮次采用代理运行时,通道调度会执行此操作。没有通道传输路径的轮流也会在该准入写入中获得持久恢复声明;该声明不授予渠道交付权限。命令、附件、每轮覆盖、挂起的交付、先前的中止提示、插件拥有的会话以及带有执行挂钩的轮次保留其专门的准入路径。如果安装了 before_agent_reply 挂钩,则准入会记录足够的阶段状态,以区分完整的静默结果和模糊的副作用窗口。恢复调度普通用户触发的代理轮流,因此当前加载的 before_agent_reply 挂钩在其正常触发规则下运行。不明确的先前钩子结果可以通过重新启动安全工具来恢复,而不是重放不受限制的副作用。
  • 关闭时: 每个具有活动运行的会话在关闭所有者中止之前都会标记恢复标记。即使首先运行连接清理,已取消重新启动的运行仍然是候选运行。
  • 启动时: 网关会扫描恢复拥有的声明和带有 abortedLastRun: true 的主会话或 interrupted 结果,即使没有声明。由于新流程中没有实时所有者,现有恢复所有者将创建丢失的循环并恢复轮流。该安全网涵盖了丢失或失败的关闭标记、严重崩溃以及未运行关闭代码的杀戮。已存档和墓碑化的会话仍被排除在外;待交付、已产生的延续和重试预算保留其现有的所有者和规则。新用户轮次会清除先前的中断并且不会重播。过时的转录锁定文件会同时被清除。

仍在接受数据库启动检查的代理保留其恢复工作。准入完成后,同一个启动恢复所有者会使用原始截止时间扫描其存储,因此新准入的轮次不会被误认为是崩溃孤儿。入站通道轮流(包括崩溃后重播的未确认消息)在记录会话元数据或调度之前等待其代理的可写许可。其他代理仍然可用,停止通道或网关会取消等待。

失败的存储扫描使该存储符合计划重试的条件,而其他存储则继续恢复。 openclaw status 和 openclaw doctor 显示正在运行的网关存在突出的启动恢复故障;当商店扫描成功时,警告将清除。

即使命令清理在关闭标记之前完成,重新启动中止也会保留中断回合的恢复声明。当记录的终端标记没有匹配的传递证据时,Doctor 转换还可以恢复旧的中断的内部聊天编写器的丢失声明。现有的已完成周转收据保持不变;恢复使用其正常的转录重放检查。

如果网关留下了死亡的写入器和未完成的恢复周期,sessions.recover 会协调该写入器并在同一会话中启动延续。新的 Control UI 消息也会在准入之前协调此状态,因此被拒绝的发送无法将对话陷入“对话已更改”重试循环中。两条路径都保留会话密钥和记录。实时运行或云工作人员仍然会阻止此修复。逻辑删除会话将其单独的恢复路径保留到新会话中。

如果在代理启动前的准备过程中恢复失败,网关将恢复中断状态并释放该尝试的传送声明。下一次恢复尝试使用全新运行 ID,同时保留原始中断的轮次和重试预算,因此拒绝的挂起输入不会使对话永久繁忙。这包括在其运行时轮开始之前被关闭拒绝的已接受的延续。其收费尝试在初创公司中保持相同的重试预算;耗尽仍然会产生正常的恢复通知。

自动恢复

启动几秒后,网关会为每个已标记的会话重新派发一条合成的系统消息,告知代理其上一轮因重启而中断,并要求其从现有记录中继续。如果最终回复已经生成但尚未送达,则会包含其文本,以便代理直接发送,而不是重新执行工作。

启动恢复一次准备一个延续。自动延续在单宽后台命令通道中执行,保留其位置直到回合结束。交互式转弯使用主通道,因此大量恢复积压无法填满其执行槽。后来中断的转弯在等待时保留其持久主张;长时间恢复的转弯会延迟其他自动继续。可选的启动数据库维护和页面缓存预热等待积压的工作耗尽;运行时计时器和 cron 启动独立进行。延迟的数据库准入加入同一个启动调度程序。关机会停止新的准备工作并加入当前的过程,从而为下一次启动留下未开始的中断。

当会话移动到新密钥或轮换其会话 ID 时,恢复遵循保留的转录窗口所有权。声明验证和清理仅读取那些候选会话,因此在交互式会话更改等待时,过时的恢复声明不会加载不相关的已保存提示。声明权限、重试预算、存储的数据和升级行为保持不变。

Control UI 显示中立系统通知:“网关已重新启动。正在恢复您中断的请求。”预期的重新启动中断不会创建终端回复失败卡或要求您再次发送请求。即使在关闭所有者取消该轮次之前准入围栏关闭,在活动轮次期间拒绝重新启动仍会保留其恢复声明。真正的提供者故障、显式的停止操作和耗尽的恢复仍然是不同的结果。

重新启动不会取消用户的任务。代理检查当前状态,协调结果未知的工具结果,并继续而不要求用户重复请求。准备新消息不能消耗中断标记;回收所有者保留它,直到工作被采用或解决为止。

恢复会在开始另一次运行之前读取中断回合的源,即使最终答复已等待处理。如果无法读取文字记录,则保存的回复和任何承认的完成声明仍可供以后尝试。如果没有幸存的权限,委派的请求和未经验证的内部输入无法自动恢复。来源缺失或无效并不能确定内部索赔的人工发件人。旧通道和 Control UI 会保留其现有的恢复检查。儿童完成后续工作仍使用现有的恢复和交付所有权检查。如果他们的代理数据库仍在进行启动检查或准备,子结果在读取时发生更改,或者准备工作人员拒绝满负荷工作,则挂起的完成唤醒会在 30 秒后重试,而不消耗交付尝试或更改其批次、重播身份或重试计数器。每次重试都会在相同的所有权检查下读取新的结果。保留的唤醒在再次重启后仍然存在。确认的检查失败或所有权不匹配仍然是失败,而不是绕过数据库准入的权限;取消仍然会使唤醒退休。

失败的子完成组不会停止不相关组的启动恢复。原始组保留其所有权检查并以有界退避重试;这些重试不会再次启动已启动的恢复运行。

当恢复的回合以符合条件的频道传送路由开始时,OpenClaw 向该对话发送恢复通知,保留其帐户和主题。最终回复使用相同的传递路线。仅成绩单的轮次保持私密,并且已经完成的轮次不会收到延迟恢复通知。失败的通知不会重新启动或重播已恢复的工作。主会话恢复通知是尽力而为且仅限实时的:在通道发送之前立即重新检查自动传送权限和恢复所有者。它们不会从出站队列中重播;终端故障通知重试和正常的最终回复传递没有变化。

Telegram 在恢复的回合运行时更新其打字指示器。当回合结束、其恢复所有者发生变化或网关关闭时,输入会停止,并遵循 typingMode: "never"。其他频道可以通过受保护的打字挂钩选择加入;不支持的频道仍会收到恢复通知。

频道插件选择使用 heartbeat.sendTypingGuarded(...)。除了恢复交付目标之外,核心还提供 AbortSignal 和 assertPlatformSendAuthorized 回调。插件必须通过排队发送来接受取消,并在异步准备之后立即在平台请求之前调用回调。恢复不会回落到无人看守的 heartbeat.sendTyping(...) 钩子。

启动协调会使用指数退避,最多重试三次临时性失败。除此之外,每个中断的主会话周期都有三个已计费自动派发尝试的持久化预算,并会跨越网关重启保留。OpenClaw 会在派发前扣除一次尝试;如果网关在接受请求前明确拒绝,则退还该次尝试;如果派发后的结果不确定,则保留该次扣费,以避免重复执行工作。已经占有会话的前台工作会让自动恢复暂停,直到该工作结束。

前台工作完成后取消恢复预留会清除空的、未收费的恢复记录。恢复协调和前台准入也会清除旧会话中的残留物,因此它不能阻止已完成的子代理的请求者轮次。中断的工作和待交付的物品由其恢复保管。

持久预算用完后,会话将被逻辑删除,而不是永远循环。未完成的任务仍然可用:检查失败的会话并使用 WebChat 中的 Resume 以当前操作员权限继续进行。在其他通道中,/new或/reset开始替换。 openclaw doctor --fix 可以修复与逻辑删除冲突的陈旧中止标志,但它不会重新启用自动恢复周期。请参阅 Session recovery 了解工具安全限制和 CLI-runtime 替换后备。

如果您在某个通道中再次向失败的会话发送消息,OpenClaw 将通过该通道发送简短的恢复提醒,并使用会话密钥、恢复原因和恢复命令在警告级别记录每条被拒绝的消息。重复的提醒会被抑制在有限的内存缓存中。重置或删除会话,或者重新启动网关,可以清除该抑制。具有锁定模型选择的会话会将您定向至 WebChat 中的 Resume。

每次重试都会重用一个持久调度标识符,因此不明确的连接故障无法两次启动相同的恢复。已完成的 Control UI 回合还保留有界的持久完成标记,允许重新连接的发件箱将其淘汰,而无需重新执行请求。

当挂起的决赛没有剩余队列所有者并且其交付结果不确定时,当保存的决赛具有交付上下文和意图 ID 时,恢复会记录同一路线上下一个回合的通知。解决该轮次将清除其回收所有权及其交付索赔,因此下一个代理轮次可以继续进行。通知和终端重复数据删除证据在再次重启后仍然存在;已完成的工作不会重播。

仅消息工具回复使用第二个持久关联。在终端同一会话发送到达通道之前,网关会在确切的会话和源轮次上记录未解决的传送意图。经确认的供应商成功会将其解析为持久的交付收据。确认的故障会清除它。恢复无需重新运行工具即可完成交付收据。如果崩溃导致提供程序结果未知,则可以使用重新启动安全工具恢复恢复,以便模型可以检查并报告歧义,而无需重放外部效果。

所传送的回复也被镜像到其源消息 ID 的记录中。终端镜像使用不同的接收密钥,因此使用相同提供者幂等性密钥发送的进度无法掩盖终端标记。较早回合的进度发送和接收无法完成当前回合。只有持久的通道入口声明才能恢复消息操作权限。恢复的运行会保留原始源传送模式和源相关性,包括请求者身份和任何相同的 channel/thread 限制,因此即使在恢复期间发生另一次重新启动,相同的收据仍然具有权威性。仅使用消息工具的传递策略也可以在运行准入和模型回退中继续存在;私人最终文本永远不会成为待处理的自动回复。没有可重构通道权限的仅消息工具轮次将被墓碑化,因为在没有原始通道入口声明的情况下,OpenClaw 无法安全地创建消息操作权限。终端通知指示用户开始使用 /new 或 /reset 进行更换。

恢复的 Control UI 转弯可以使用中断的转弯的确切会话和恢复声明来完成 固定仪表板小部件 。浏览器连接在重新启动后无法继续存在:恢复保留仪表板创作,而内联和设备演示仍然需要其正常的客户端功能。

在恢复之前,网关对转录尾部进行分类以选择继续的工具限制。中止的转向就是中断本身,因此它会尽力恢复提供者或工作人员记录的任何中止细节:已记录的部分文本保留在转录本中,并且从其下方的消息中继续,而悬空的工具调用将从下一个提供者有效负载中删除。提供者失败、已完成的助理尾部、空的成绩单和过时的待审批也从现有的成绩单中继续。副作用不明确的国家通常使用重启安全工具。一次有效的会话完全访问权限,包括继承的完全访问默认设置,保留其普通工具,以便它可以检查结果并完成任务。恢复不会自动重播中断的呼叫或将其丢失的结果视为成功。现有工具限制和当前权限仍然适用。恢复提示将中断、丢失或中止的工具结果识别为网关重新启动的未知结果。被中断的本机子进程的后续进程会收到相同的上下文,因此它可以在重试工具调用之前验证效果。待处理的回复传送、不明确的回复挂钩结果和明确的重放安全代码模式重建保留了较窄的恢复限制。

OpenClaw 还可以重构中断的只读 Code Mode 工作。代码模式将这些运行标记为重新启动安全,并在执行之前拒绝副作用目录或命名空间工具调用。如果重新启动落在 wait 控件上,新网关会根据其记录重建回合,并强制重建的执行保持重新启动安全,即使模型忽略或清除该标志也是如此。主机将整个重构过程过滤为经过审核的只读核心工具和显式重放安全插件工具,包括重新启动后禁用代码模式时。其他中断的代码模式工作将恢复以进行模型协调:完全访问将保留其配置的工具表面,除非当前回合具有明确的重放安全检查点。其他会话保留重新启动安全限制。旧的流程本地运行和批准句柄不会恢复。

子代理

子代理运行会持久保存在共享 SQLite 状态数据库中,因此子代理注册表会在该过程中继续存在。启动时,一旦启动恢复请求者所有权,中断的子运行就会通过其正常完成路径解决,而无需等待定期注册表扫描。扫描仍然是重试的保障。崩溃循环断路器也暂停了这一解决;当断路器的恢复窗口结束时,会重试相同的扫描。启动直接从注册表恢复已完成的运行。任何保留的交付都会保留其正常会话和所有权检查。未完成的运行在恢复之前仍会协调当前子会话。保留子会话中的人类后续操作在实际执行运行 ID 和后续提示(包括浏览器聊天)下进行本机托管。完成的原始运行保留其自己的结果。人类所有权和仪表板嵌套不会将孩子变成主会话重播候选者。它们不会自动重新启动。家长接收中断结果并负责完成用户的任务。对于禁用完成通知的本机子级,当其保存的会话标识仍然匹配时,恢复会向原始父级发送私有延续。正常成功完成保持安静。重置或取消并不授权继续进入替换父会话。如果子会话被重置或替换,恢复将根据该原因解决旧任务,并通知其原始父会话,而不更改替换的子会话。一个安静的孩子的原始父母也会收到这个私人结果。重置父任务会取消旧任务的待处理通知,而不尝试停止替换子会话或其后代。取消的转弯可以短暂保留清理租约。该租约并不会让他们重新开始候选人;立即重新启动网关会保留其最终结果。最终答复仍悬而未决的已完成执行将保留其恢复保管权,就像因重新启动本身而中断的轮次一样。其恢复输入列出了当前未完成的子会话和运行标识,包括因重新启动而中断的子会话。被较新的子运行取代的较旧的运行被省略,来自另一个存储、父会话或父生命周期修订的记录也被省略。重置会保留会话 ID,但会更改其生命周期修订版,因此重置之前保留的子工作无法进入新父项的可操作恢复名册。大列表显示前 32 个孩子,并告诉家长检查其余的孩子。

父级必须使每个未完成的子级与其保存的历史记录和原始请求保持一致。当子级的任务仍然需要时,它应该更喜欢在 sessions_send 的保留会话中进行后续操作。它首先确认旧的执行已停止并检查任何不确定的工具效果。它可以使用已完成的工作、分配替代工作或自行完成剩余的工作。恢复不会自动重播子命令或重复正在运行的工作。单独的干扰并不是阻碍;父级继续,直到请求完成或特定阻止程序需要用户输入或不可用的权限。即使配置了 cleanup: "delete",被中断的本机子进程也会保留其会话历史记录,因此父进程可以检查并继续未完成的工作。成功的运行会保留其配置的清理行为;正常的历史记录保留仍然适用。

Startup 在恢复幸存的声明之前,通过注册表的清理所有者撤销被取代的请求者完成声明。这些历史行不会阻止同一请求者回合中的当前子代理或其他子代理的恢复。保存的收益意图是根据用于传输的当前子项进行​​评估的。被中断的当前子级仍向父级报告其重新启动结果。仅包含被取代子项的轮次不需要请求者结算。

如果父级在等待子级时屈服,则其保存的批次会收集已完成和中断的结果,并在批次稳定后唤醒父级。屈服的转弯使持久的结果未确定,而它们的延续仍然拥有未完成的工作。已经处理这些结果的家长可以通过普通的主会话恢复来恢复。子结果或 announce: 运行标识符不会使未完成的父工作成为一次性的。两种恢复路径都为父母提供了被中断的孩子的身份以及相同的和解指导。重新启动中断作为中断结果而不是子执行失败保留在历史记录中。真正的执行和交付失败仍然需要关注。

保存的批次唤醒保留其原始批次标识和完成交付合同。他们的可采取行动的恢复名册仅包括其父母所有权仍然匹配的孩子。较旧或陈旧的记录仍然是普通的完成历史记录;他们无法添加新指令来继续这些子会话。当前重置已撤销其实时保存的唤醒。记录的结果和历史子元数据将被保留。

升级时,保留类型的重新启动恢复所有者的已保存中断将通过相同的启动路径进行协调。没有所有权证据的历史失败运行仍然失败:仅靠它们的错误文本无法区分重新启动和真正的失败。在继续之前检查那些保留的会话;恢复不会改写模糊的历史。

已完成的子项可能仍欠其请求者最后的后续行动。如果该后续操作正在等待重试或因重新启动而中断,则保存的义务将继续存在并在启动后恢复。重新启动准入拒绝不会消耗一次尝试,取消已准入的尝试也不会耗尽义务。现有的传送重试限制仍然适用。暂时的清理准备失败将所需的最终交付安排在现有的交付窗口内。偶然清理保留其有限的重试限制。解决屈服转弯的尾流会使其未完成的本地运行和最终交付完好无损。完成的取消将其唤醒和清理簿记保留在本机子代理记录中;它不需要单独的任务行。恢复会在重试其请求者唤醒之前协调过期取消的保留标记,从而保留原始清理记录。当正常的清理协调完成时,实时子取消可以唤醒等待的请求者。延迟取消回调无法重新打开已完成的清理。

代理请求的重启

当代理本身触发重新启动(应用配置更改、更新网关或显式重新启动请求)时,会在进程退出之前将重新启动标记写入 SQLite。启动后,网关将结果发布回原始聊天,并分派任何请求的一次性继续回合,以便代理在同一通道和线程上准确地从上次中断的位置继续。

对于更新,哨兵携带 stats.runId,将分离的更新程序链接到其持久的 update_runs 记录。新网关在那里记录其观察到的运行版本、构建和启动事实。它保留更新程序已写入的最终结果,并在托管切换仍悬而未决时等待。在准备通知或延续之前,它会为同一运行和切换协调较新的最终哨兵。即使账本已经终止,挂起的哨兵也会保留其现有的有界重试窗口;不相关的替换保持不变。如果助手从未发布其最终哨兵,则到期会报告记录的最终结果而不更改它。仍在运行的网关拥有的行以失败结束,并显示 restart-unhealthy; CLI-owned 运行保留其更新者的权限和结果。重新启动后通知是使用与 openclaw update status 相同的报告从该行呈现的。使用哨兵不会删除运行历史记录。旧版本留下的哨兵保留其现有的交付路线。

使用现有内部源会话(包括 Control UI 和网络聊天)运行的任何更新都会将其报告直接附加到该会话的记录中,即使调用者仅提供 sessionKey 而没有提供 deliveryContext 也是如此。已完成但没有继续的更新不会唤醒模型来交付报告。

哨兵的 SQLite 列对于重新启动处理具有权威性。其 payload_json 值只是 replay/debug 影子。运行时读取、写入和清除 SQLite 状态,无需文件回退。 7 月之前的 restart-sentinel.json 格式及其 .doctor-importing 声明已停用。医生、更新准入和重新启动恢复会使这些文件和任何当前的 SQLite 通知保持不变,并且需要在重试之前通过 2026.9.7 和 openclaw doctor --fix 进行中间升级。支持的更新程序(包括 2026.6.34 和 2026.9.2)写入本机 SQLite 状态并保留其现有的重新启动交付和继续行为。

安全阀与可观测性

  • 崩溃环路断路器: 5 分钟内 3 次不干净的启动会触发断路器,从而在下次启动时抑制自动启动侧服务,因此崩溃的网关不会自行放大。持续稳定的安全模式网关会在完全不干净启动窗口耗尽后重新检查断路器,然后恢复延迟的通道自动启动,而无需再次重启网关。

    断路器跳闸时,控制平面仍会启动,但频道插件(以及其他自动启动的旁路服务)会保持停止状态,直到操作员手动解除抑制,或完整时间窗口结束且期间没有发生非正常启动。恢复过程会保留操作员手动停止的频道,以及任何独立的开发模式抑制状态。网关日志如下: channel autostart suppressed by crash-loop breaker; refusing automatic start for <channel>… Start a channel manually with: openclaw gateway call channels.start --params '{"channel":"<id>"}'

    安全模式还会暂停主会话​​重新启动恢复。中断的条目和记录保持不变:暂停不会收取尝试费用、解决回合、发送通知或删除会话。恢复日志命名暂停和断路器窗口结束。一旦整个窗口耗尽,相同的健康进程会自动重新武装其现有的恢复调度程序,并使用原始的启动截止和所有权检查恢复中断的工作一次。新的不干净的启动延长了暂停时间;关闭或生命周期更换会取消挂起的重新启动。无需手动重试或额外重新启动网关。

    操作员恢复 SOP:

    1. 确认网关进程正在运行(openclaw gateway status / LaunchAgent 或 systemd 单元仍在运行)。出现“频道断开连接”通常意味着自动启动被抑制,而不是网关已停止。

    2. 检查频道状态:openclaw channels status(必要时添加 --probe)。如果网关本身正常运行,请查找已停止/未连接的账户。

    3. 在强制恢复频道之前,先修复导致非正常启动的根本原因(错误配置、插件启动时崩溃、缺少密钥)。

    4. 在抑制仍然生效时手动启动频道:

      bash
      openclaw gateway call channels.start --params '{"channel":"<id>"}'# optional: {"channel":"<id>","accountId":"<account>"}

      channels.start 是 手动 覆盖。它不会禁用其他通道的断路器。

    5. 或者让健康的网关持续运行,直到完整的非正常启动窗口结束。同一进程会记录重启循环断路器已恢复,并启动延迟的已配置频道。 如果在该窗口结束并经过一次健康监控间隔后仍未出现该消息,请检查网关日志,并在重启前运行 openclaw doctor。

    另请参阅网关(安全模式段落),了解相同的控制平面与频道自动启动分离机制。

  • 会话准备: 仍在初始化或等待工作区设置的中断会话保持延迟。当会话准备发生变化时,恢复会重新检查确切的启动候选者,而不会在等待时收取调度尝试费用。关闭或新的网关生命周期取消等待;替换或重置会话会使旧候选者失效。已存档、已过期、已重新启动逻辑删除和提供商审核已阻止的会话仍需要正常的操作员操作。

  • 主会话尝试预算: 每个中断周期进行 3 次自动调度尝试。用尽该会话的墓碑,直到对其进行检查和更换。临时目标解析失败使用现有的有界启动重试,而不对调度尝试收费。失踪的业主和不匹配的商店仍然被跳过。

  • 指标: 恢复活动通过 Prometheus 导出为 openclaw_session_recovery_total 和 openclaw_session_recovery_age_seconds。

  • Logs: 恢复决策记录在 main-session-restart-recovery 和 agents/subagent-registry 子系统下。每个启动阶段都包括按 archived、live_owner、work_start_pending、work_start_blocked 或 dispatch_target_unavailable 等原因划分的有界跳过计数,即使其他会话启动时也是如此。每个中断的主要候选者都有一个结构化决策线,其中包含 boot/pass、会话和源运行身份、结果(started、settled、deferred 或 blocked)以及下一个负责所有者。工作开始决策命名特定条件,例如 initialization_pending、workspace_pending、archived 或 provider_review。存档的会话被推迟,没有下一个所有者,而不是报告为需要操作员操作的阻塞工作。

  • 回复钩子: 恢复的轮次会在正常的用户触发规则下运行当前已加载的 before_agent_reply 钩子。自动传递的回复也会在频道传递前运行正常的 reply_payload_sending 钩子,并携带恢复后的会话、运行、账户和对话上下文。

更新后验证恢复情况

健康的网关确认可用性,而不是完成中断的工作。检查每个先前活动的会话及其子任务:它应该在关闭、恢复执行或达到可见的终端结果或恢复错误之前完成。单独检查排队输入的转录消耗或明确的未解决状态。

主会话恢复日志将执行恢复与后来的 main-session restart recovery terminal 事件区分开来。启动时恢复计数意味着执行已恢复。它并不能证明助理回复已送达。使用会话记录和记录的交付结果来验证完成情况。

未恢复的内容

  • Sessions 从主会话恢复中排除,因为另一个所有者已经处理它们:子代理会话(返回到其父级)、cron 会话(调度程序按计划重新运行)和 ACP- 托管会话(连接的 IDE 或客户端拥有恢复)。
  • 从未被接纳的工作:在排空窗口期间到达的消息会因明确的重启错误而被拒绝,而不是被静默排入一个即将退出的进程。
  • 网关终端 PTY,包括运营商和代理拥有的终端。它们是进程本地的,并在网关重新启动时结束。
  • 独立的嵌入式轮次无法接管存在待处理重启恢复的主会话,因为它们不共享 Gateway 的生命周期所有者。请通过 Gateway 运行该轮次,或在那里使用 /new 或 /reset 重置它。
本页有帮助吗?