一次 Gateway 重启演练复盘：AI Agent 为什么不能手写恢复状态
说明：本文由 OpenClaw 助手根据一次真实配置与排障过程辅助整理，内容经过人工确认。
这篇笔记记录一次很小、但很典型的 Agent 工程事故：我们想让 AI Agent 自己重启 Gateway，并在重启完成后回到原会话通知用户。第一次尝试失败了，原因不是“服务不会重启”，而是我们把一个带恢复语义的系统动作，拆成了几个脆弱的手工步骤。
最终得到的结论很简单：
需要带用户回流通知的 Gateway 重启，必须走 Gateway 进程内写路径；不要手写恢复状态文件。
背景：重启不是一个普通运维动作
在长期运行的 AI Agent 系统里，Gateway 通常不只是一个服务进程。它还承载了用户消息入口、工具调用、会话路由、后台任务和投递通道。
因此，“重启 Gateway”至少要回答三个问题：
- 服务有没有真的重启成功？
- 重启前的用户意图有没有被可靠保存？
- 重启后 Agent 能不能回到正确会话，主动告诉用户“我回来了”？
这次演练的目标很简单：让 Agent 自己触发 Gateway 重启，重启完成后回到同一个用户会话，并发出约定暗号。
看起来只是一个 restart，实际暴露出的是 Agent 系统里一个重要边界：恢复状态不能靠临时手写，必须走系统内建的 durable handoff 路径。
第一次尝试：看似合理，实际绕开了系统语义
第一次演练时，我采用了一个直觉上很容易想到的方案：
- 在本地写入一个 restart sentinel 文件，记录“重启后要通知用户”的内容。
- 通过 shell 触发 Gateway restart。
- 等 Gateway 启动后，由启动恢复逻辑读取 sentinel 并发送通知。
这个方案表面上符合流程：先保存恢复意图，再重启，再恢复通知。
但问题在于：它绕开了 Gateway 自己的 restart 封装。
最终结果是，用户没有收到暗号。
失败现象：不是通知失败，而是重启根本没发生
演练后，当前聊天仍然可用，但预期的“重启完成”通知没有出现。
排查后看到几个关键信号：
- restart sentinel 文件仍然残留，说明没有被启动恢复逻辑消费。
- Gateway 进程没有换过，说明所谓的 restart 实际没有发生。
- shell 日志显示 restart 命令失败，原因是子 shell 环境里找不到对应命令。
也就是说，失败点不是“重启后通知投递失败”，而是更早：Gateway 根本没有按预期重启。
这也解释了为什么 sentinel 没被消费：消费动作发生在 Gateway 启动恢复阶段；如果没有真实重启，就不会进入这条链路。
根因：把一个系统级动作拆成了手工步骤
这次失败的根因不是某一个命令写错这么简单，而是设计路径选错了。
我把一个本应该由 Gateway 内部完成的系统级动作，拆成了外部手工步骤：
- 手写 sentinel。
- 手动触发 restart。
- 假设启动恢复逻辑会接住。
这带来三个问题。
第一，状态写入和重启动作不是原子语义。
sentinel 写成功不代表 restart 一定发生。如果 restart 失败，就会留下一个过期 sentinel。之后某次真实重启可能误消费这个旧状态，发出过期通知。
第二，shell restart 只表达“重启服务”，不表达“带着当前会话的 continuation 语义重启”。
对 Agent 来说，关键不是服务生命周期本身，而是重启后能否回到正确 session、正确 channel、正确用户上下文。
第三，绕开封装后，失败清理责任变得模糊。
如果 Gateway 自己的 restart 工具负责写 sentinel，那么它也可以在 restart emit 被拒绝或失败时做回滚或清理。外部手写文件则没有这个保护。
正确路径：让 Gateway 进程内逻辑生成恢复状态
正确做法是：不要手写 restart sentinel。
需要 Gateway 重启并保留恢复通知时，应优先使用内部 Gateway 工具的 restart 动作，由 Gateway 进程内路径生成 sentinel，并附带必要的会话恢复信息。
语义上，它需要包含三类信息：
- sessionKey：重启后应该回到哪个会话。
- note：重启完成后给用户看的摘要或通知。
- continuationMessage：重启后让 Agent 继续执行的一次性指令。
这和单纯运行一个服务重启命令不一样。
服务重启命令只关心进程生命周期；Gateway restart 工具关心的是“带恢复语义的重启”。
如果内部 gateway tool 不可用怎么办？
实际系统里还会遇到一个现实问题：内部 gateway tool 可能因为工具策略或 owner 权限没有暴露给当前 Agent run。
这次演练中就遇到了类似情况：
- 工具 allowlist 里一开始没有 gateway。
- 当前发送者也需要被 owner allowlist 识别。
因此在 gateway tool 不可用时，可以使用一个 fallback：通过 Gateway RPC 的 config.patch 走 Gateway 进程内配置写入路径。
这个方案的核心不是“为了改配置而改配置”，而是借助 Gateway 进程内的 restart-required config 写路径，让 sentinel 仍然由 Gateway 自己生成，而不是外部手写。
fallback 的大致流程是：
- 通过 Gateway RPC 发起一个会触发 restart planning 的 config.patch。
- 请求里带上 sessionKey、delivery context、note 等恢复信息。
- 确认 sentinel 已由 Gateway 写入。
- 如果 restart 因 active operations、pending replies 或 embedded run 被 defer，必要时再用 service restart 推动真实重启。
- Gateway 启动后消费 sentinel，并回流到目标会话。
这次最终成功的链路就是这个 fallback：config.patch 成功生成 sentinel，随后真实重启后 sentinel 被消费，用户收到了约定暗号。
最终规则
这次复盘后，可以把规则收敛成一句话：
需要带用户恢复通知的 Gateway 重启，必须走 Gateway 进程内写路径，不要手写 sentinel。
优先级如下：
- 首选：内部 gateway tool 的 restart 动作。
- 备选：Gateway RPC config.patch 触发 restart-required 写路径。
- 不推荐：直接 shell 执行 service restart。
- 禁止：手写 restart-sentinel 文件再赌启动恢复逻辑会处理。
其中，直接 shell restart 不是完全不能用，而是不应该作为“带 Agent continuation 语义的 restart”首选。它最多只能作为已经生成 durable handoff 后，推动服务生命周期变化的最后一步。
工程教训
1. 恢复状态必须 durable，但 durable 不等于随便落盘
把状态写进文件只是 durable 的一种表象。
真正可靠的 durable handoff 还需要回答：
- 谁有权写？
- 写入和后续动作是不是同一条系统语义？
- 失败时谁负责清理？
- 重启后如何保证只消费一次？
- 如何验证它被正确消费？
如果只是外部手写一个文件，很容易制造“看似可靠，实际悬空”的状态。
2. Agent 工具不是命令行的简单包装
在 Agent 系统里，一个工具调用通常不只是执行某个命令。
它还隐含了权限、上下文、审计、回滚、投递路由、session 绑定等语义。
因此，不能只看“这个 shell 命令最终也能重启服务”，就认为它等价于 gateway restart tool。
二者的目标不同：
- shell restart：让进程重启。
- gateway restart tool：让系统带着恢复意图安全重启。
3. 重启链路要验证完整闭环，而不是只看命令返回
一次完整验证至少应该覆盖：
- restart 是否真实发生。
- sentinel 是否生成。
- sentinel 是否被消费。
- Gateway 是否恢复 healthy。
- 消息是否投递到正确会话。
- 是否有 stale sentinel 残留。
只看“restart 命令执行了”是不够的。
4. fallback 也要走系统边界，不要绕开系统边界
fallback 的价值不是“随便找个办法达到目的”，而是在主路径不可用时，仍然尽量保持系统语义完整。
这次 config.patch fallback 的关键点就在于：它仍然发生在 Gateway 进程内，仍然复用了 Gateway 的配置写入和 restart planning 机制。
这比外部手写 sentinel 安全得多。
一张流程图
结论
这次演练把一个容易忽略的问题暴露得很清楚：
在 AI Agent 系统里，重启不是单纯的进程操作，而是一次跨进程、跨会话、跨投递通道的状态交接。
如果只追求“把服务重启起来”，shell 命令足够。
但如果目标是“Agent 重启后还能回来继续完成用户意图”，就必须把恢复状态交给系统内建路径来管理。
所以最终原则是：
不要手写恢复状态；让拥有上下文、权限和生命周期语义的系统组件来写。