> ## 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.

# 重新啟動復原

重新啟動閘道不會遺失代理程式狀態。對話、逐字稿、排程工作、背景任務記錄和排隊中的外送訊息全都儲存在磁碟上，而在回合進行途中遭中斷的工作，會在閘道恢復運作後自動偵測並繼續執行。復原功能一律啟用，通常不需要手動介入。若復原重複失敗，嘗試次數會受到限制，並可能隔離某個工作階段，直到你檢查或替換它為止。

本頁說明哪些內容會在重新啟動後保留、如何偵測中斷的工作，以及自動繼續執行的運作方式。

## 重新啟動後保留的內容

| 狀態         | 儲存位置                      | 重新啟動時的行為               |
| ---------- | ------------------------- | ---------------------- |
| 對話歷史記錄     | 各代理程式的 SQLite 資料庫         | 不受影響；工作階段會從已儲存的逐字稿繼續   |
| 中斷的主工作階段回合 | 各代理程式的 SQLite 工作階段資料列和逐字稿 | 啟動數秒後自動繼續執行或調和         |
| 子代理程式執行    | SQLite（共用狀態資料庫）           | 啟動時還原登錄資料；繼續執行中斷的作業    |
| 背景任務       | SQLite（共用狀態資料庫）           | 啟動時調和；復原孤立的作業或將其標記為遺失  |
| 排隊中的外送     | SQLite 傳遞佇列               | 重新啟動後清空佇列；重試尚未送達的回覆    |
| 已排程（排程）工作  | SQLite 排程儲存區              | 排程會保留；排程器在啟動時重新啟用      |
| 重新啟動接續處理   | SQLite 重新啟動哨兵             | 將一次性後續處理分派給要求重新啟動的工作階段 |

## 正常重新啟動會先等待工作完成

要求重新啟動（`openclaw gateway restart`、需要重新啟動的設定變更，或閘道更新）時，不會立即終止進行中的工作。閘道會停止接受新工作，接著等待作用中的代理程式回合和背景任務完成，最長以等待完成時限為準（預設為 5 分鐘）。因此，大多數重新啟動完全不會中斷任何工作。

只有無法在等待完成時限內結束的工作（或因強制重新啟動或當機而中斷的任何作業）才會中止，而在此之前，每個受影響的工作階段都會標記為需要復原。

## 如何偵測中斷的工作

以下三種互補機制會標記回合未完成的工作階段：

* \*\*接受回合時：\*\*對現有主工作階段中的一般文字回合，閘道會附加使用者訊息、將工作階段標記為執行中，並在模型或 `before_agent_reply` 掛鉤執行前，於單一 SQLite 交易中記錄其復原傳遞宣告。Control UI 會在傳回 `started` 確認前執行此操作；頻道分派則會在準備好的回合採用代理程式作業時執行。
  命令、附件、單回合覆寫、待處理傳遞、先前的中止提示、外掛擁有的工作階段，以及具有執行掛鉤的回合，仍會使用其專用的接受路徑。
  如果已安裝 `before_agent_reply` 掛鉤，接受程序也會記錄其階段。
  復原絕不會重播在呼叫途中遭中斷的掛鉤。未處理的掛鉤完成後，其檢查點會記錄該結果，但只要該掛鉤仍處於作用中，復原仍會採取失敗即關閉策略：檢查點無法證明重新啟動後載入的是相同的外掛程式碼和設定。已處理的文字結果和無聲結果會分別建立檢查點，以確保確定性的結算。
  舊版寫入的持久復原宣告沒有來源擁有權標記，因此在升級期間也會接受相同的失敗即關閉掛鉤檢查。
* \*\*關機時：\*\*在重新啟動的等待完成期間，每個有作用中作業的工作階段都會在作業中止前，於工作階段儲存區中加上復原標記。
* \*\*啟動時：\*\*閘道會掃描工作階段儲存區，找出仍宣告為執行中、但在新處理程序中沒有有效擁有者的工作階段。這可涵蓋未執行任何關機程式碼的嚴重當機和強制終止情況。同時也會清理過期的逐字稿鎖定檔案。

## 自動繼續執行

啟動幾秒後，閘道會以合成的系統訊息重新分派每個已標記的工作階段，告知代理程式其上一個回合因重新啟動而中斷，並要求從現有逐字稿繼續。如果最終回覆已產生但尚未送達，其文字也會包含在內，讓代理程式直接傳遞，而不必重做工作。

啟動調和會以指數退避方式重試暫時性失敗，最多三次。另外，每個中斷的主工作階段週期都有三次計費自動分派嘗試的持久額度，並會跨閘道重新啟動保留。OpenClaw 會在分派前計入一次嘗試；若閘道在接受前明確拒絕要求，則退還該次嘗試；若分派後的結果不確定，則保留該次計費，以避免重播工作。已擁有該工作階段的前景工作會阻止自動復原，直到該工作結束為止。

持久額度用盡後，工作階段會被設為墓碑，而不會無限循環。請檢查失敗的工作階段，並使用 `/new` 或 `/reset` 啟動替代工作階段。`openclaw doctor --fix` 可以修復與墓碑衝突的過期中止旗標，但不會重新啟用該復原週期。

每次重試都會重複使用同一個持久分派識別碼，因此不明確的連線失敗無法啟動相同的復原兩次。已完成及無法繼續執行的 Control UI 回合也會保留有界限的持久冪等墓碑，讓重新連線的寄件匣不必重新執行要求即可將其移除。

僅使用訊息工具的回覆會採用第二組持久關聯。終端的同一對話傳送抵達頻道前，閘道會在確切的工作階段和來源回合上記錄未解決的傳遞意圖。確認提供者成功後，該意圖會解析為持久的已送達收據；確認失敗則會清除它。復原可以完成已有送達收據的工作，而不必重新執行工具。如果當機導致提供者結果不明，復原會採取失敗即關閉策略，而不會重播外部效果。

已送達的回覆也會連同其來源訊息 ID 鏡像寫入逐字稿。終端鏡像會使用不同的收據金鑰，因此使用相同提供者冪等金鑰的進度傳送不會掩蓋終端標記。先前回合的進度傳送和收據無法完成目前回合。只有持久的頻道輸入宣告可以還原訊息動作權限。繼續執行的作業會保留原始來源傳遞模式和來源關聯，包括要求者身分及任何相同頻道／討論串限制，因此即使復原期間再次重新啟動，相同的收據仍具權威性。若僅使用訊息工具的回合無法重建頻道權限，則會採取失敗即關閉策略，並收到一次性的重新傳送通知。

繼續執行前，閘道會檢查逐字稿尾端是否能安全地接續。如果不能（例如回合結束於過期的待核准狀態），就不會盲目重新執行該工作階段；代理程式會改為發送簡短通知，要求使用者重新傳送上一個要求。對 WebChat 而言，該通知會直接寫入工作階段歷史記錄，以便重新連線後仍然可見。

OpenClaw 也能重建中斷的唯讀 [Code Mode](/zh-TW/tools/code-mode) 工作。Code Mode 會將這些作業標記為重新啟動安全，並在具副作用的目錄工具或外掛命名空間執行前拒絕它們。如果重新啟動發生於 `wait` 控制項，新閘道會從逐字稿重建回合，並強制重建後的執行維持重新啟動安全，即使模型省略或清除該旗標也一樣。主機會將整個重建回合篩選為經稽核的唯讀核心工具，以及明確可安全重播的外掛工具，即使重新啟動後停用了 Code Mode 也一樣。具副作用的工作仍由重新傳送通知保護，避免冒險造成重複寫入。

### 子代理程式

子代理程式作業會持久儲存在共用 SQLite 狀態資料庫中，因此子代理程式登錄資料可跨處理程序保留。啟動時會還原登錄資料，並以原始任務內容繼續執行中斷的子代理程式工作階段。適用以下兩項安全機制：

* 超過 2 小時前中斷的作業會結束，而不會繼續執行，因此停機一整晚的閘道不會重新喚起過期工作。
* 重複復原失敗的工作階段會因卡死而設為墓碑，避免復原無限循環。

### 背景任務

[背景任務登錄資料](/zh-TW/automation/tasks)以 SQLite 為後端，並會在啟動時及定期進行調和：已完成作業所記錄的持久結果會復原，而擁有處理程序已消失的作業會在寬限期後標記為遺失，而不會永遠停滯。

### 代理程式要求的重新啟動

當代理程式本身觸發重新啟動時（套用設定變更、更新閘道，或明確要求重新啟動），會在處理程序結束前將重新啟動哨兵寫入 SQLite。啟動後，閘道會將結果發回原始聊天，並分派一次性的接續回合，讓代理程式在相同頻道和討論串上，從完全相同的位置繼續工作。

哨兵的具型別 SQLite 欄位是重新啟動處理的權威來源；其 `payload_json` 值僅是重播／偵錯用的影子資料。執行階段會直接讀取、寫入和清除 SQLite 狀態，不使用檔案備援。在儲存系統轉換期間，會在啟動時及透過 Doctor 執行有界限的狀態遷移，以保留更新後由舊處理程序留下且已驗證的 `restart-sentinel.json`。
遷移程序會驗證具型別的資料列並移除來源檔案，之後才繼續一般的重新啟動處理。

## 安全機制和可觀測性

* \*\*當機循環斷路器：\*\*在 5 分鐘內發生 3 次非正常啟動，會觸發斷路器，在下一次啟動時抑制自動啟動的附屬服務，避免不斷當機的閘道放大問題。非正常啟動的時間窗結束後，就會恢復正常。
* \*\*主工作階段嘗試額度：\*\*每個中斷週期有三次計費自動分派嘗試；額度用盡後，該工作階段會設為墓碑，直到完成檢查並替換為止。
* \*\*指標：\*\*復原活動會透過 [Prometheus](/zh-TW/gateway/prometheus) 匯出為 `openclaw_session_recovery_total` 和 `openclaw_session_recovery_age_seconds`。
* \*\*記錄：\*\*復原決策會記錄在 `main-session-restart-recovery` 和 `subagent-interrupted-resume` 子系統下。

## 不會繼續執行的內容

* 因已有其他擁有者處理而排除於主工作階段復原之外的工作階段：子代理程式工作階段（由子代理程式復原處理）、排程工作階段（排程器會按排程重新執行），以及由 ACP 管理的工作階段（由已連線的 IDE 或用戶端負責繼續執行）。
* 逐字稿尾端無法安全接續的工作階段；這類工作階段會收到上述重新傳送通知，而不會無聲地重新執行。
* 從未被接受的工作：在等待完成期間抵達的訊息會收到明確的重新啟動錯誤並遭拒絕，而不會無聲地排入即將終止的處理程序。
* 獨立的嵌入式回合無法接管有待處理重新啟動復原的主工作階段，因為它們不共用閘道的生命週期擁有者。請透過閘道執行該回合，或在閘道中使用 `/new` 或 `/reset` 重設它。