OpenClaw 排程指南：選擇 Heartbeat 與 Cron 的最佳時機

你是否曾經為了該用什麼方式讓 AI 幫你處理例行公事而感到頭痛？是該讓它每隔一段時間自己去檢查信箱，還是設定一個精確的鬧鐘叫它起床工作？選擇錯誤的機制可能會讓你的 Token 消耗過快，或者讓 AI 在不該說話的時候打擾你。

這篇指南會幫你釐清 Heartbeat 與 Cron 的差異，讓你根據具體需求選擇最適合的方案。

快速決策指南

使用場景	建議方案	原因
每 30 分鐘檢查一次收件匣	Heartbeat	可與其他檢查合併處理，且具備上下文感知能力
每天早上 9 點準時發送報告	Cron (isolated)	需要精確的觸發時間
監控行事曆中的即將到來事件	Heartbeat	非常適合週期性的狀態感知
每週執行一次深度分析	Cron (isolated)	獨立任務，可以使用不同的 model
20 分鐘後提醒我	Cron (main, --at)	具備精確時間的一次性任務
背景專案健康檢查	Heartbeat	順便搭現有週期的便車執行

Heartbeat：週期性感知

Heartbeat 會以固定的間隔（預設為 30 分鐘）在 main session 中執行。它們的設計目的是讓 agent 檢查各項事務，並在發現重要事情時主動回報。

何時使用 Heartbeat

• 多個週期性檢查：與其設定 5 個獨立的 Cron 任務分別檢查信箱、行事曆、天氣、通知和專案狀態，不如用一個 Heartbeat 把這些全部打包處理。
• 具備上下文感知的決策：Agent 擁有完整的 main session 上下文，因此它可以聰明地判斷哪些事情很緊急，哪些可以稍後再說。
• 對話連貫性：Heartbeat 執行時共享同一個 session，所以 agent 會記得最近的對話內容，並能自然地進行後續追蹤。
• 低開銷監控：一個 Heartbeat 就能取代許多細碎的輪詢任務。

Heartbeat 的優勢

• 批次處理多個檢查：Agent 可以在一次執行中同時查看信箱、行事曆和通知。
• 減少 API 呼叫：單一 Heartbeat 比 5 個獨立的 Cron 任務更省錢。
• 上下文感知：Agent 知道你最近在忙什麼，並能據此調整優先順序。
• 智慧抑制：如果沒有什麼需要注意的事，agent 會回覆 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

Agent 在每次 Heartbeat 時都會閱讀這份清單，並在一次執行中處理所有項目。

設定 Heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval
        target: "last", // explicit alert delivery target (default is "none")
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}

完整設定請參考 Heartbeat。

Cron：精確排程

Cron 任務會在精確的時間點執行，並且可以在獨立的 session 中執行，不會影響 main session 的上下文。 重複性的整點排程會自動在 0-5 分鐘的視窗內，透過每個任務固定的偏移量來分散執行時間。

何時使用 Cron

• 需要精確時間：例如「每週一早上 9:00 發送這個」（而不是「9 點左右」）。
• 獨立任務：不需要對話上下文的任務。
• 不同的 model 或思考層級：需要更強大的 model 來進行繁重的分析。
• 一次性提醒：使用 --at 實現「20 分鐘後提醒我」。
• 雜訊多或頻繁的任務：如果放在 main session 會讓歷史紀錄變得混亂的任務。
• 外部觸發：無論 agent 當前是否活躍都應該獨立執行的任務。

Cron 的優勢

• 精確計時：支援 5 欄位或 6 欄位（秒級）的 Cron 表達式，並支援時區。
• 內建負載分散：預設情況下，重複性的整點排程會錯開最多 5 分鐘。
• 單一任務控制：可以使用 --stagger <duration> 覆蓋偏移量，或使用 --exact 強制精確時間。
• Session 隔離：在 cron:<jobId> 中執行，不會污染 main session 的歷史紀錄。
• Model 覆蓋：可以為每個任務指定更便宜或更強大的 model。
• 傳送控制：隔離任務預設為 announce（摘要）模式；你可以根據需要選擇 none。
• 立即傳送：Announce 模式會直接發布訊息，不需要等待 Heartbeat。
• 無需 agent 上下文：即使 main session 處於閒置或壓縮狀態，任務也能執行。
• 支援一次性任務：使用 --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。

決策流程圖

Does the task need to run at an EXACT time?
  YES -> Use cron
  NO  -> Continue...

Does the task need isolation from main session?
  YES -> Use cron (isolated)
  NO  -> Continue...

Can this task be batched with other periodic checks?
  YES -> Use heartbeat (add to HEARTBEAT.md)
  NO  -> Use cron

Is this a one-shot reminder?
  YES -> Use cron with --at
  NO  -> Continue...

Does it need a different model or thinking level?
  YES -> Use cron (isolated) with --model/--thinking
  NO  -> Use 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 任務（精確計時）：

# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

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

Lobster 是一個用於執行多步驟工具流水線的運行環境，適用於需要確定性執行和明確審核的場景。當任務不只是單次的 agent 對話，而是一個包含人類檢查點、可恢復的工作流時，請使用它。

何時適合使用 Lobster

• 多步驟自動化：你需要固定的工具呼叫流水線，而不是單次的 prompt。
• 審核關卡：涉及副作用的操作應該暫停，直到你批准後再繼續。
• 可恢復的執行：可以繼續執行暫停的工作流，而不需要重新執行先前的步驟。

如何與 Heartbeat 和 Cron 搭配

• Heartbeat/Cron 決定「何時」執行。
• Lobster 定義執行開始後「有哪些步驟」。

對於排程工作流，可以使用 Cron 或 Heartbeat 觸發一次 agent 執行，進而呼叫 Lobster。對於臨時工作流，則直接呼叫 Lobster。

運作說明（摘自程式碼）

• Lobster 以本地子程序 (lobster CLI) 的形式在工具模式下執行，並回傳 JSON envelope。
• 如果工具回傳 needs_approval，你可以使用 resumeToken 和 approve 旗標來恢復執行。
• 該工具是一個選用外掛；建議透過 tools.alsoAllow: ["lobster"] 開啟。
• Lobster 要求 lobster CLI 在你的 PATH 中可用。

完整用法與範例請見 Lobster。

Main Session vs Isolated Session

Heartbeat 和 Cron 都可以與 main session 互動，但方式有所不同：

	Heartbeat	Cron (main)	Cron (isolated)
Session	Main	Main (透過 system event)	cron:<jobId>
歷史紀錄	共享	共享	每次執行都是新的
上下文	完整	完整	無（從零開始）
Model	Main session model	Main session model	可覆蓋
輸出	若非 HEARTBEAT_OK 則傳送	Heartbeat prompt + event	預設傳送摘要 (announce)

何時使用 Main Session Cron

當你希望達成以下目標時，請使用 --session main 搭配 --system-event：

• 提醒或事件出現在 main session 的上下文中。
• Agent 在下一次 Heartbeat 時帶著完整上下文來處理它。
• 不需要產生額外獨立的執行紀錄。

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

何時使用 Isolated Cron

當你希望達成以下目標時，請使用 --session isolated：

• 一個沒有先前上下文的乾淨狀態。
• 使用不同的 model 或思考設定。
• 直接將摘要發布到頻道。
• 歷史紀錄不會弄亂 main session。

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)	每個任務都是一次完整的 agent 執行；可使用較便宜的 model

小撇步：

• 保持 HEARTBEAT.md 精簡，以減少 Token 開銷。
• 將類似的檢查合併到 Heartbeat 中，而不是建立多個 Cron 任務。
• 如果你只需要內部處理，請在 Heartbeat 上使用 target: "none"。
• 對於例行任務，使用隔離的 Cron 並搭配較便宜的 model。

下一步

• Heartbeat - 完整的 Heartbeat 設定說明
• Cron jobs - 完整的 Cron CLI 與 API 參考
• System - 系統事件與 Heartbeat 控制項

如果你在設定過程中遇到任何問題，隨時可以詢問 AI Setup Assistant。