2026-05-08 OpenClaw 会话状态检查点 与 网关重启恢复：无头租用的 Apple Silicon 云 Mac（香港 / 东京 / 首尔 / 新加坡 / 美国）

运维终于把 健康探测 跑稳——结果 npm 升级时 launchctl 重启了网关，Slack 里全是「机器人忘光了」。其实模型没忘；是 持久化边界 变了，因为 OPENCLAW_STATE_DIR 没做快照，或清理脚本删掉了 CI 产物旁的 scratch。在香港、东京、首尔、新加坡、美国租用的 Mac mini M4 上，解决办法是流程：把会话残留当作与签名密钥同级的 数据面状态。本 2026-05-08 指南说明检查点目录如何与 launchd 环境 交互、如何用合成流量演练恢复，以及如何串联 结构化日志、KeepAlive 分诊、网关升级与回滚 以及 文件传输插件策略 的信号，让重启变得无聊。

网关重启为何仍让值班措手不及

OpenClaw 同时追求 快速迭代 与 持久自动化。当 npm 安装后脚本改全局、工程师与 CI 共用同一用户 SSH 登入时，网关进程可能干净重启却加载 不同 的环境语义。没有检查点纪律，你会丢失的不只是聊天记录，还有 webhook 去重缓存与工具白名单。把预期持久化写进与 launchctl 标签同一 README。

OPENCLAW_STATE_DIR 的分层

按层思考：

• 会话线索 — 重连后期望保留的对话脚手架。
• 工具缓存 — 需要在短暂网关停顿后仍存活的有限元数据。
• Webhook 记账 — 防止重复履约的去重键。

可行时为各层单独挂载或设置 ACL，避免 CI 清理向上扫到助手状态。与 并行 CI 车道 的隔离建议一致，当两种负载共享 UID 时尤须如此。

launchd：ThrottleInterval、退出码、重生

launchd 可能在人类察觉前就把网关拉起——尤其 KeepAlive 很激进时。请结合 重生分诊：记录退出码、确认 ThrottleInterval 压住紧崩循环、保证 StandardOutPath 接住 stderr 分流。改 plist 后务必先跑 健康探测 里的 curl 就绪矩阵再宣布恢复。

维护窗口前的检查点手册

1. 冻结 npm/Mint 钉并导出依赖树。
2. 快照 OPENCLAW_STATE_DIR（tar 或可用时的 APFS 快照）。
3. 通知 webhook 提供方：重放测试期可能出现重复投递。
4. 重启 网关用 launchctl kickstart——别随手 kill -9。
5. 验证 合成入站事件后去重键是否回填。

公开每步耗时，方便财务比较「多租一台见证节点」与「更长事故 MTTR」。

故障模式矩阵

现象	可能原因	缓解
重启后客户收到重复邮件	去重缓存被清空	可重放 webhook id + 外部台账
升级后工具被拒绝	策略文件未迁移	按插件文档版本化白名单
重启后 RSS 偏高	技能包加载了两次	比对 npm ls 树与 tarball 备份

插件与文件传输邻域

2026-05-07 文件传输插件 增加了必须在重启后仍成立的文件系统语义：若许可只活在临时环境变量里，重启会静默收紧访问。把策略文件放在状态目录下并用 Git 或密封配置追踪。再结合 分块读取纪律，避免恢复的会话一上来就拉巨量文件。

结构化日志与关联 ID

网关每条日志应带 会话 id、网关代数计数、重启 nonce， Grafana 才能把前后窗口分开。入站激增时结合 反向代理指引 对齐 nginx 边缘。

八步恢复手册

1. 用进程启动时间对比心跳漂移发现重启。
2. 比对状态目录 tarball 哈希与实时目录。
3. 对 staging 信道跑合成 CLI 对话。
4. 用幂等 token 重放 webhook 样本。
5. 确认插件策略仍拒绝非预期根目录。
6. 若怀疑损坏则前滚 npm 钉。
7. 用重启 nonce 记录时间线。
8. 复盘是否要见证节点缩短 MTTR。

SLO 表

信号	阈值	动作
会话恢复失败	重连中 > 0.5%	冻结发布；审计 plist 环境
去重冲突	任意 副作用重复	重放台账完整性校验
检查点 tarball 龄	> 36 小时 陈旧	自动化夜间快照作业

常见问题

问题	实操答案（2026-05-08）
支持 ZFS/APFS 快照吗？	若租赁允许——与提供商协调；否则 tarball 上传到对象存储。
检查点要跨区同步吗？	否——会话保持区域化；复制配置，不复制在线对话缓存。

为何 Mac mini M4 适合有状态网关

统一内存与高速 NVMe 让事故中对检查点快照和 tarball diff 成为可能——压力下对比 GB 级状态树时，可预期硬件好过嘈杂邻居。预算讨论对齐 区域定价；新人上手见 帮助文档，GUI 授权不可避免时辅以 VNC。