> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 重启恢复

重启 Gateway 网关不会丢失智能体状态。对话、转录记录、
定时任务、后台任务记录和排队中的出站消息都存储
在磁盘上；轮次中途被中断的工作会在 Gateway 网关恢复运行后被检测到并
自动恢复。恢复功能始终启用，通常无需手动干预。
反复失败的恢复会受到限制，并可能隔离某个会话，直到你检查或替换它。

本页介绍重启后会保留哪些内容、如何检测中断的工作，
以及自动恢复的具体过程。

## 重启后保留的内容

| 状态         | 存储位置                 | 重启后的行为                  |
| ---------- | -------------------- | ----------------------- |
| 对话历史记录     | 每智能体 SQLite 数据库      | 保持不变；会话从已存储的转录记录继续      |
| 中断的主会话轮次   | 每智能体 SQLite 会话行和转录记录 | 启动几秒后自动恢复或协调处理          |
| 子智能体运行     | SQLite（共享状态数据库）      | 启动时恢复注册表；恢复中断的运行        |
| 后台任务       | SQLite（共享状态数据库）      | 启动时协调处理；恢复孤立运行或将其标记为已丢失 |
| 排队中的出站递送   | SQLite 递送队列          | 重启后排空；重试未递送的回复          |
| 定时（cron）任务 | SQLite cron 存储       | 调度计划会保留；调度器在启动时重新启用     |
| 重启后继续      | SQLite 重启哨兵          | 向请求重启的会话分派一次性后续轮次       |

## 优雅重启会先排空任务

请求的重启（`openclaw gateway restart`、需要
重启的配置更改或 Gateway 网关更新）不会立即终止正在进行的工作。
Gateway 网关会停止接受新工作，然后等待活跃的智能体轮次和
后台任务完成，最长不超过排空预算（默认为 5 分钟）。因此，大多数
重启根本不会中断任何工作。

只有无法在排空预算内完成的工作（或因强制重启或崩溃而中断的任何运行）
才会被中止——而在此之前，每个
受影响的会话都会被标记为需要恢复。

## 如何检测中断的工作

三种互补机制会标记轮次未完成的会话：

* \*\*轮次准入时：\*\*对于现有主会话中的普通文本轮次，
  Gateway 网关会追加用户消息、将会话标记为正在运行，并在模型或
  `before_agent_reply` 钩子执行之前，通过一次 SQLite 事务记录
  其恢复递送声明。Control UI 会在返回
  `started` 确认之前执行此操作；渠道分派则在准备好的轮次
  接管智能体运行时执行此操作。
  命令、附件、每轮次覆盖项、待处理递送、先前的中止提示、
  插件拥有的会话以及带有执行钩子的轮次会继续使用各自的
  专用准入路径。
  如果安装了 `before_agent_reply` 钩子，准入还会记录其阶段。
  恢复绝不会重放在调用途中中断的钩子。未处理的钩子
  完成后，其检查点会记录该结果，但只要该钩子仍处于活动状态，
  恢复仍会采取失败关闭策略：检查点无法证明重启后加载的是相同的
  插件代码和配置。已处理的文本结果和
  静默结果会分别设置检查点，以便进行确定性结算。
  旧版本写入的持久恢复声明没有来源所有权
  标记，因此在升级期间也会接受相同的失败关闭钩子检查。
* \*\*关闭时：\*\*在重启排空期间，每个存在活跃运行的会话
  都会在运行被中止前，在会话存储中加上恢复标记。
* \*\*启动时：\*\*Gateway 网关会扫描会话存储，查找仍
  声称正在运行、但在新进程中没有活动所有者的会话。这可以捕获
  未执行任何关闭代码的严重崩溃和进程终止。同时还会清理过期的转录记录锁
  文件。

## 自动恢复

启动几秒后，Gateway 网关会重新分派每个已标记的会话，
并附带一条合成的系统消息，告知智能体其上一个轮次
因重启而中断，并要求它从现有转录记录继续。如果
最终回复已经生成但尚未递送，其文本会一并提供，
以便智能体直接递送，而不是重新执行工作。

启动协调处理会采用指数退避，最多重试三次瞬态故障。
此外，每个中断的主会话周期都有
三个计费自动分派尝试的持久预算，该预算会跨
Gateway 网关重启保留。OpenClaw 会在分派前计入一次尝试；如果
Gateway 网关在接受请求前明确拒绝请求，则退还此次尝试；如果
分派后的结果不确定，则保留计费，以避免重放工作。
已拥有该会话的前台工作会阻止自动恢复进入，
直到该工作完成。

持久预算耗尽后，会为该会话设置墓碑，而不是
让它无限循环。检查失败的会话，并使用 `/new` 或 `/reset` 启动
替代会话。`openclaw doctor --fix` 可以修复与墓碑
冲突的过期中止标志，但不会重新启用该恢复周期。

每次重试都会复用同一个持久分派标识符，因此不明确的连接
故障无法重复启动同一次恢复。已完成和无法恢复的 Control
UI 轮次也会保留有界的持久幂等性墓碑，使
重新连接的发件箱能够将其清除，而无需重新执行请求。

仅通过消息工具发送的回复会使用第二种持久关联。在终结性的
同一对话发送到达渠道之前，Gateway 网关会在确切的会话和来源轮次上
记录一个未解决的递送意图。确认提供商
成功后，该意图会解析为持久的已递送回执；确认失败后则会将其清除。
恢复可以直接完成已递送回执，而无需重新运行工具。如果崩溃
导致提供商结果未知，恢复会采取失败关闭策略，而不是重放
外部效果。

已递送的回复还会连同其来源
消息 ID 镜像到转录记录中。终结性镜像使用独立的回执键，因此使用
相同提供商幂等键的进度发送不会掩盖终结标记。来自
旧轮次的进度发送和回执无法完成当前轮次。只有
持久的渠道入口声明才能恢复消息操作权限。恢复后的
运行会保留原始来源递送模式和来源关联，包括
请求者身份以及任何同渠道/线程限制，因此即使
恢复期间再次重启，同一回执仍然具有权威性。无法重建渠道权限的
仅消息工具轮次会采取
失败关闭策略，并收到一次性的重新发送通知。

恢复前，Gateway 网关会检查转录记录尾部是否可以安全地
从中继续。如果不能（例如，轮次终止于过期的待处理
审批），则不会盲目重新运行该会话；智能体会改为发布一条简短
通知，请用户重新发送最后一个请求。对于 WebChat，该通知会
直接写入会话历史记录，以便重新连接后仍然可见。

OpenClaw 还可以重建中断的只读[代码模式](/zh-CN/tools/code-mode)
工作。代码模式会将这些运行标记为重启安全，并在具有副作用的
目录工具或插件命名空间执行前拒绝它们。如果重启发生在
`wait` 控制项上，新 Gateway 网关会根据其转录记录重建轮次，
并强制重建后的执行保持重启安全，即使
模型省略或清除了该标志。主机会将整个重建
轮次限制为经过审计的只读核心工具和明确可安全重放的插件工具，
即使重启后禁用了代码模式也是如此。具有副作用的工作
仍会由重新发送通知进行保护，而不会冒重复写入的风险。

### 子智能体

子智能体运行会持久化到共享 SQLite 状态数据库中，因此
子智能体注册表可以跨进程保留。启动时会恢复注册表，并使用原始任务上下文
恢复中断的子智能体会话。
有两项安全阀：

* 超过 2 小时前中断的运行会被完成处理，而不是恢复，因此
  停机一整夜的 Gateway 网关不会重新唤起过期工作。
* 反复恢复失败的会话会被设置为卡死墓碑，使
  恢复无法无限循环。

### 后台任务

[后台任务注册表](/zh-CN/automation/tasks)以 SQLite 为后端，
并会在启动时和定期周期中进行协调处理：恢复已完成运行记录的
持久结果；所属进程已消失的运行会在
宽限期后标记为已丢失，而不是永远挂起。

### 智能体请求的重启

当智能体自身触发重启（应用配置更改、更新
Gateway 网关或显式请求重启）时，会在进程退出前将重启哨兵写入
SQLite。启动后，Gateway 网关会将结果发回
原始聊天，并分派一个一次性继续轮次，使
智能体恰好从中断处继续，并保持在同一渠道和线程中。

哨兵的类型化 SQLite 列是重启处理的权威来源；
其 `payload_json` 值仅用于重放/调试影子。运行时读取、写入
和清除 SQLite 状态，不使用文件回退。在存储切换期间，
启动时以及通过 Doctor 会运行有界状态迁移，以保留
更新后旧进程留下的、经过验证的 `restart-sentinel.json`。
迁移会验证类型化行并删除源文件，然后再继续正常的
重启处理。

## 安全阀和可观测性

* \*\*崩溃循环断路器：\*\*5 分钟内发生 3 次非正常启动会触发断路器，
  在下次启动时阻止自动启动辅助服务，从而避免崩溃中的 Gateway 网关
  放大自身问题。非正常启动时间窗口清空后，它会恢复。
* \*\*主会话尝试预算：\*\*每个中断周期有三次计费自动分派尝试；
  预算耗尽后会为该会话设置墓碑，直到它被
  检查并替换。
* \*\*指标：\*\*恢复活动通过
  [Prometheus](/zh-CN/gateway/prometheus) 导出为 `openclaw_session_recovery_total` 和
  `openclaw_session_recovery_age_seconds`。
* \*\*日志：\*\*恢复决策记录在
  `main-session-restart-recovery` 和 `subagent-interrupted-resume`
  子系统下。

## 不会恢复的内容

* 因已有其他所有者负责处理而排除在主会话恢复之外的会话：
  子智能体会话（由子智能体恢复处理）、cron 会话（调度器会按计划
  重新运行）以及 ACP 管理的会话（由连接的 IDE
  或客户端负责恢复）。
* 转录记录尾部无法安全继续的会话；这些会话会收到
  上述重新发送通知，而不是静默重新运行。
* 从未准入的工作：在排空窗口期间到达的消息
  会被拒绝并返回明确的重启错误，而不是静默排入
  即将终止的进程。
* 独立的嵌入式轮次无法接管存在待处理
  重启恢复的主会话，因为它们不共享 Gateway 网关的生命周期所有者。
  请通过 Gateway 网关运行该轮次，或在那里使用 `/new` 或 `/reset` 重置它。