OpenClaw自動化指南：Cron、Heartbeat、Tasks、Hooks與故障恢復

OpenClaw自動化指南：Cron、Heartbeat、Tasks、Hooks與故障恢復

OpenClaw自動化要先區分「什麼時候觸發」和「工作如何被執行」。Cron負責精確排程與隔離任務，Heartbeat則是由Cron Scheduler承載的主Session週期回合，用來定期檢查是否有值得通知使用者的變化；Detached Tasks保存長時間工作紀錄，Hooks處理Gateway、Session與工具生命週期事件。可靠自動化還需要冪等鍵、最小權限、Run Log、失敗通知、人工核准和外部狀態查詢，否則Agent只會準時重複錯誤。本文聚焦自動化，OpenClaw歷史、架構、一人公司、Hermes比較與xAI OAuth由其他五篇承接。

• Cron適合精確時間、一次性提醒、報表與隔離背景工作。
• Heartbeat是主Session的週期性Agent Turn，底層由Cron Scheduler維持。
• Heartbeat不等於Detached Task，也不應手動修改系統生成的Heartbeat Cron Job。
• Hooks適合Gateway啟動、Session事件與工具前後的確定性處理。
• 所有寫入流程都要處理重複執行、Timeout後狀態不明與部分成功。
• 付款、合約、刪除、公開發布與權限變更應保留人工Gate。

文章實體化：OpenClaw自動化指南：Cron、Heartbeat、Tasks、Hooks與故障恢復

本文以「OpenClaw自動化指南：Cron、Heartbeat、Tasks、Hooks與故障恢復」為主線，補回模型／工具、輸入輸出、版本、成本、測試與使用邊界，讓技術名詞回到可執行的工作流程。

• 核心元件：把標題中的模型、工具、格式、企業或協定對應到實際輸入、輸出與依賴。
• 驗證方法：記錄版本、資料、環境、基準、錯誤案例與人工檢查，避免只引用功能宣稱。
• 治理邊界：說明權限、資料保存、成本、失敗回復與何時需要人工介入。

涉及版本、價格、企業資料或 API 行為時，以文章原始資料與供應商／公司最新文件核對。

OpenClaw自動化元件如何分工

Cron如何運作

Cron由Gateway內建Scheduler管理。Gateway持續運行時，排程器會依時間建立執行，保存Job、Run History、Session與投遞結果。

• 支援一次性時間、固定間隔和Cron Expression。
• 應明確設定時區，不依賴主機預設時區。
• 可建立隔離Session，避免背景工作污染主要對話。
• 可將結果送回Channel或以Webhook投遞。
• Run Log預設會按大小和保留行數清理。
• 完成的隔離Cron Session可依Retention設定自動清除。

Cron設定需要注意什麼

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 4,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

並行上限要依模型額度、Tool Rate Limit、資料庫與Review能力設定。把maxConcurrentRuns開大，只會同時放大錯誤、成本與外部服務壓力。

Heartbeat到底是什麼

Heartbeat是排程的主Session Agent Turn。它會讓Agent定期讀取主Session脈絡和HEARTBEAT.md，判斷是否有需要主動提醒使用者的事情。

目前Gateway會為每個啟用Heartbeat的Agent建立一個系統管理的Cron Job。使用者應修改agents.*.heartbeat設定，不應直接編輯系統生成的Heartbeat Job。

Heartbeat適合哪些工作

• 檢查收件匣是否有需要注意的訊息。
• 查看日曆和即將到期的工作。
• 確認等待中的Approval或Blocker。
• 整理近期Channel中的重要變化。
• 沒有重要事情時保持安靜，不重複通知。

HEARTBEAT.md應非常短。每次週期都會被讀取，過長清單會持續消耗Token，也會讓Agent把所有例行資訊都當成需要通知的事件。

Cron和Heartbeat如何選

Detached Tasks負責什麼

Detached Task回答「一項脫離目前對話的工作現在在哪個狀態」。它可保存Queued、Running、Succeeded、Failed、Timed Out、Cancelled或Lost等結果，也能連回執行Session與Artifact。

Task本身不是排程器。Cron決定何時啟動，Agent或ACP執行工作，Task Record則提供可觀察性與稽核。

Hooks適合處理哪些事件

• Gateway啟動後檢查必要服務。
• Session開始時載入或驗證工作狀態。
• 工具呼叫前檢查命令、路徑或收件人。
• 工具完成後保存Audit、測試與結果摘要。
• 設定變更時通知或阻擋不安全修改。
• 任務完成時驗證Artifact是否存在。

Hook具有程式執行能力，也屬於供應鏈與權限表面。腳本需要固定版本、Code Review、Timeout、Secrets限制與失敗策略。

一個可靠Cron Task應包含什麼

job:
  id: daily-content-audit
  schedule: "0 8 * * *"
  timezone: Asia/Taipei
  goal: 掃描昨日更新文章並產生異常報告
  input_source: wordpress
  allowed_actions:
    - read_posts
    - check_links
    - create_report
  prohibited_actions:
    - update_posts
    - publish_content
    - delete_content
  output: markdown_report
  delivery: slack
  timeout: 20m
  max_retries: 2
  idempotency_key: daily-content-audit:{date}
  on_failure: notify_content_ops

避免重複寫入的控制方法

• 每次Run使用唯一Job ID、Run ID與目標Resource ID。
• 寫入前先讀取外部系統目前狀態。
• Timeout後不能直接假設失敗。
• 使用Idempotency Key、唯一約束或Compare-and-swap。
• 一個Run只允許一次主要外部寫入。
• 重試前確認前一次是否已部分或完全成功。

失敗類型如何分流

寫入型自動化的人工Gate

• 寄送郵件前顯示Recipient、Subject與Attachment。
• 發布內容前顯示Post ID、Title、Status與主要變更。
• 付款前顯示金額、收款人、幣別和用途。
• 刪除前顯示精確Resource與可恢復性。
• 權限變更前顯示Actor、Scope與有效期限。
• 核准後若內容有實質變更，必須重新批准。

OpenClaw Doctor如何協助故障排查

openclaw doctor可以檢查設定、Workspace與部分Runtime問題。Heartbeat的系統Cron遺失或過期時，官方文件指出可使用openclaw doctor --fix重新建立相關狀態。

1. 確認Gateway是否運行。
2. 檢查Cron是否啟用與下一次執行時間。
3. 核對主機時間和Task時區。
4. 查看Job Run History與Session。
5. 確認模型、Tools、Credential與Rate Limit。
6. 分開檢查Task和Delivery。
7. 修正後先手動Run，再恢復排程。

六篇內容如何分工

• 發展史：改名、基金會與專案獨立性。
• 架構：Gateway、Bindings、Workspace與Sandbox。
• 本篇：Cron、Heartbeat、Tasks、Hooks、冪等與故障回復。
• 一人公司：Control Tower與營運鏈。
• Hermes比較：Gateway與長任務分工。
• xAI OAuth：PKCE、SSH與Token安全。

讀者常問

Heartbeat可以取代Cron嗎？

不能完全取代。Heartbeat適合主Session巡檢；精確時間、一次性提醒、隔離工作和Webhook應使用Cron。

Heartbeat會建立背景Task嗎？

Heartbeat是主Session Agent Turn，通常不建立Detached Task Record；底層排程仍由Cron Scheduler維持。

排程可以直接發布文章嗎？

技術上可以，正式流程建議先產生Draft或Diff，再由人確認精確Post與變更。

Background Task會自動重試嗎？

Task主要保存狀態；重試由Cron、工作流或上層策略決定，應依錯誤類型限制次數。

資料來源

• OpenClaw Heartbeat
• Gateway Configuration
• Configuration Reference

OpenClaw自動化的成熟度，不看排程數量，而看每次執行是否能被限制、追蹤、驗證、停止與安全重跑。Cron負責準時，Heartbeat負責持續注意；真正讓系統可靠的，是冪等、外部狀態與清楚的人類責任。

延伸觀察｜從細節回看核心脈絡

自動化與代理整合應遵循最小權限、明確人工確認、可追溯日誌與受控測試；憑證只用環境變數保存，勿寫入指令、內容或紀錄。

增量：自動化排程要先設計失敗，再設計成功

Cron、Heartbeat、Tasks 與 Hooks 的觸發時機不同；無論選哪一種，都要先定義任務是否可重複、逾時怎麼處理、失敗要通知誰、是否能安全重跑，以及輸入資料如何避免被重複消費。沒有 idempotency 的自動化，跑得越勤可能製造越多錯誤。

故障恢復還需要日誌、執行編號、最後成功時間、重試上限與人工接管入口。先在低風險環境演練斷網、權限失效、半途停止與重複觸發，再逐步放大範圍，會比上線後靠運氣穩定得多。