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。