Cron 與 Heartbeat：何時該用哪一個

Heartbeat 和 cron 都能讓你按排程執行任務。這份指南幫助你根據使用情境選擇合適的機制。

快速判斷表

使用情境建議方式原因
每 30 分鐘檢查收件匣Heartbeat可與其他檢查批次處理，具備上下文感知
每天早上 9 點準時發送報告Cron（isolated）需要精確的時間點
監控行事曆即將到來的事件Heartbeat天生適合定期感知
執行每週深度分析Cron（isolated）獨立任務，可使用不同模型
20 分鐘後提醒我Cron（main，--at）需要精確計時的一次性提醒
背景專案健康檢查Heartbeat搭便車在既有循環上

Heartbeat：定期感知

Heartbeat 在主要工作階段中以固定間隔執行（預設：30 分鐘），設計讓代理定期檢查狀況並浮出重要事項。

適合使用 heartbeat 的情境

  • 多項定期檢查：與其建立 5 個分別檢查收件匣、行事曆、天氣、通知和專案狀態的 cron 排程，一次 heartbeat 就能批次處理所有項目。
  • 具備上下文的決策：代理擁有完整的主要工作階段上下文，能聰明地判斷哪些事情緊急、哪些可以等。
  • 對話連貫性：heartbeat 共享同一個工作階段，代理記得最近的對話，能自然地追蹤進度。
  • 低開銷監控：一個 heartbeat 取代許多小型輪詢任務。

Heartbeat 的優勢

  • 批次處理多項檢查：一次代理回合就能同時檢閱收件匣、行事曆和通知。
  • 減少 API 呼叫：一次 heartbeat 比 5 個獨立 cron 排程更省成本。
  • 上下文感知：代理知道你正在做什麼，能據此安排優先順序。
  • 智慧抑制：如果沒有需要注意的事項，代理回覆 HEARTBEAT_OK，不會發送訊息。
  • 自然的時間節奏：會因佇列負載略有漂移，但對大多數監控來說完全沒問題。

Heartbeat 範例：HEARTBEAT.md 檢查清單

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

代理每次 heartbeat 都會讀取這份清單，並在一個回合中處理所有項目。

設定 heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 間隔
        target: "last", // 明確的告警投遞目標（預設為 "none"）
        activeHours: { start: "08:00", end: "22:00" }, // 選用
      },
    },
  },
}

完整設定請參閱 Heartbeat。

Cron：精確排程

Cron 排程在精確的時間執行，可在獨立工作階段中執行，不影響主要上下文。 週期性的整點排程會透過確定性的逐排程偏移，自動分散在 0-5 分鐘的視窗內。

適合使用 cron 的情境

  • 需要精確時間：「每週一早上 9:00 發送」（不是「大約 9 點左右」）。
  • 獨立任務：不需要對話上下文的任務。
  • 不同模型/思考層級：需要更強大模型的深度分析。
  • 一次性提醒：「20 分鐘後提醒我」搭配 --at。
  • 頻繁/嘈雜的任務：會讓主要工作階段歷史變得雜亂的任務。
  • 外部觸發：無論代理是否活躍都應執行的任務。

Cron 的優勢

  • 精確計時：支援 5 欄位或 6 欄位（含秒）cron 表達式，並支援時區。
  • 內建負載分散：週期性整點排程預設錯開最多 5 分鐘。
  • 逐排程控制：用 --stagger <duration> 覆寫錯開設定，或用 --exact 強制精確執行。
  • 工作階段隔離：在 cron:<jobId> 中執行，不污染主要歷史記錄。
  • 模型覆寫：可依排程使用更便宜或更強大的模型。
  • 投遞控制：獨立排程預設為 announce（摘要）；視需要選擇 none。
  • 即時投遞：announce 模式直接發送，不必等待 heartbeat。
  • 不需要代理上下文：即使主要工作階段閒置或已壓縮也能執行。
  • 一次性支援：--at 用於精確的未來時間戳。

Cron 範例：每日晨報

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

這會在紐約時間早上 7:00 準時執行，使用 Opus 確保品質，並直接將摘要投遞到 WhatsApp。

Cron 範例：一次性提醒

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

完整 CLI 參考請見 Cron jobs。

決策流程圖

這個任務需要在精確的時間執行嗎？
  是 -> 使用 cron
  否 -> 繼續...

這個任務需要與主要工作階段隔離嗎？
  是 -> 使用 cron（isolated）
  否 -> 繼續...

這個任務可以和其他定期檢查批次處理嗎？
  是 -> 使用 heartbeat（加到 HEARTBEAT.md）
  否 -> 使用 cron

這是一次性提醒嗎？
  是 -> 使用 cron 搭配 --at
  否 -> 繼續...

需要不同的模型或思考層級嗎？
  是 -> 使用 cron（isolated）搭配 --model/--thinking
  否 -> 使用 heartbeat

搭配使用兩者

最有效率的設定是同時使用兩者：

  1. Heartbeat 處理例行監控（收件匣、行事曆、通知），每 30 分鐘一次批次處理。
  2. Cron 處理精確排程（每日報告、每週回顧）和一次性提醒。

範例：高效的自動化設定

HEARTBEAT.md（每 30 分鐘檢查一次）：

# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours

Cron 排程（精確計時）：

# 每天早上 7 點的晨報
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# 每週一早上 9 點的專案回顧
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# 一次性提醒
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster：具備核准機制的確定性工作流程

Lobster 是用於多步驟工具管線的工作流程執行環境，提供確定性執行和明確的核准閘道。 當任務超過單一代理回合，且你需要可恢復的工作流程搭配人工檢查點時，就適合使用 Lobster。

Lobster 適用的情境

  • 多步驟自動化：你需要固定的工具呼叫管線，而非一次性提示。
  • 核准閘道：副作用應暫停直到你核准，然後繼續執行。
  • 可恢復的執行：暫停後繼續工作流程，不需要重新執行先前的步驟。

如何搭配 heartbeat 和 cron

  • Heartbeat/cron 決定_什麼時候_執行。
  • Lobster 定義執行開始後_要做哪些步驟_。

若要排程工作流程，使用 cron 或 heartbeat 觸發一個呼叫 Lobster 的代理回合。 若要臨時執行工作流程，直接呼叫 Lobster。

實作說明（來自程式碼）

  • Lobster 以本地子行程（lobster CLI）在工具模式下執行，回傳 JSON 封裝。
  • 如果工具回傳 needs_approval，你用 resumeToken 和 approve 旗標恢復執行。
  • 這個工具是選用外掛；透過 tools.alsoAllow: ["lobster"] 額外啟用（建議做法）。
  • Lobster 預期 lobster CLI 在 PATH 上可用。

完整用法和範例請見 Lobster。

主要工作階段 vs 獨立工作階段

Heartbeat 和 cron 都能與主要工作階段互動，但方式不同：

HeartbeatCron（main）Cron（isolated）
工作階段主要主要（透過系統事件）cron:<jobId>
歷史記錄共享共享每次執行重新開始
上下文完整完整無（從零開始）
模型主要工作階段模型主要工作階段模型可覆寫
輸出非 HEARTBEAT_OK 時投遞heartbeat 提示 + 事件投遞摘要（預設）

何時使用主要工作階段 cron

當你希望以下效果時，使用 --session main 搭配 --system-event：

  • 提醒/事件出現在主要工作階段上下文中
  • 代理在下次 heartbeat 時搭配完整上下文處理
  • 不產生獨立的隔離執行
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

何時使用獨立 cron

當你希望以下效果時，使用 --session isolated：

  • 從零開始，不帶先前上下文
  • 使用不同的模型或思考設定
  • 將摘要直接投遞到頻道
  • 歷史記錄不會讓主要工作階段變得雜亂
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

成本考量

機制成本特性
Heartbeat每 N 分鐘一個回合；隨 HEARTBEAT.md 大小而增長
Cron（main）將事件加到下次 heartbeat（不產生獨立回合）
Cron（isolated）每個排程一個完整代理回合；可使用較便宜的模型

訣竅：

  • 保持 HEARTBEAT.md 精簡以減少 token 開銷。
  • 將類似的檢查批次整合到 heartbeat，而非建立多個 cron 排程。
  • 如果只需要內部處理，在 heartbeat 上使用 target: "none"。
  • 針對例行任務，使用搭配較便宜模型的 isolated cron。

相關文件

  • Heartbeat - 完整的 heartbeat 設定
  • Cron jobs - 完整的 cron CLI 和 API 參考
  • System - 系統事件 + heartbeat 控制
arrow_back
上一頁
Cron Jobs
下一頁
Troubleshooting
arrow_forward