心跳偵測

心跳偵測會在主要工作階段中執行週期性的代理程式回合，讓模型能提出任何需要注意的事項，而不會以大量訊息打擾你。

心跳偵測是排定的主要工作階段回合，不會建立背景任務記錄。任務記錄用於分離式工作（ACP 執行、子代理程式、隔離的排程工作）。

在底層，心跳偵測的頻率由排程器管理：閘道會為每個已啟用心跳偵測的代理程式維護一個系統擁有的排程工作（在 openclaw cron list --all 中顯示為 Heartbeat (agent-id)）。心跳偵測設定仍是期望狀態的輸入，而持久化的監控排程則控制實際的觸發時間點及執行器後續的冷卻時間。閘道會在啟動及重新載入設定時寫入設定變更；openclaw doctor --fix 可在下次閘道啟動前，建立缺少或過期的監控資料列。請編輯 agents.*.heartbeat，而非排程工作。

排定的心跳偵測需要排程功能。當 cron.enabled 為 false 或 OPENCLAW_SKIP_CRON=1 時，閘道會記錄啟動警告，且不會執行排定的心跳偵測；手動及事件驅動的心跳偵測喚醒仍可使用。沒有獨立的心跳偵測備援計時器。

疑難排解：排定的任務

快速開始（初學者）

設定範例：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 明確傳送至最後聯絡人（預設為 "none"）        directPolicy: "allow", // 預設：允許直接／私訊目標；設為 "block" 即可抑制        lightContext: true, // 選用：心跳偵測執行時略過工作區啟動檔案        isolatedSession: true, // 選用：每次執行都使用全新工作階段（無對話記錄）        // activeHours: { start: "08:00", end: "24:00" },      },    },  },}

預設值

• 間隔：30m。套用 Anthropic 提供者預設值時，若解析出的驗證模式為 OAuth／權杖（包括重複使用 Claude CLI），會將此值提高至 1h，但僅限 heartbeat.every 未設定時。設定 agents.defaults.heartbeat.every 或每個代理程式的 agents.entries.*.heartbeat.every；使用 0m 可停用。
• 提示詞本文（可透過 agents.defaults.heartbeat.prompt 設定）：Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• 逾時：未設定的心跳偵測回合會在已設定 agents.defaults.timeoutSeconds 時使用該值。否則，它們會使用心跳偵測頻率，且上限為 600 秒。設定 agents.defaults.heartbeat.timeoutSeconds 或每個代理程式的 agents.entries.*.heartbeat.timeoutSeconds，以執行較長的心跳偵測工作。
• 心跳偵測提示詞會逐字作為使用者訊息傳送。當預設代理程式啟用心跳偵測時，系統提示詞會包含「心跳偵測」區段，且該次執行會在內部加上標記。
• 使用 0m 停用心跳偵測時，監控排程工作會保留但處於停用狀態，其暫存內容也會保留，以供你重新啟用該頻率時使用。
• 當排程功能本身停用時，即使心跳偵測頻率仍保持啟用，排定的心跳偵測也不會執行。
• 活躍時段（heartbeat.activeHours）會依設定的時區檢查。在時段之外，心跳偵測會略過，直到時段內的下一個觸發時間點。
• 當排程工作正在執行或排隊中，或該代理程式以工作階段索引鍵為依據的子代理程式或巢狀命令通道忙碌時，心跳偵測會自動延後。同層代理程式不會彼此暫停。

心跳偵測提示詞的用途

預設提示詞刻意保持廣泛：

• 背景任務：「考量尚未完成的任務」會提示代理程式檢查後續事項（收件匣、行事曆、提醒事項、排隊中的工作），並提出任何緊急事項。
• 關心使用者：「白天偶爾關心你的使用者」會提示偶爾傳送一則輕量的「有什麼需要嗎？」訊息，但會使用你設定的當地時區來避免夜間傳送大量訊息（請參閱時區）。

心跳偵測可以回應已完成的背景任務，但心跳偵測執行本身不會建立任務記錄。

如果你希望心跳偵測執行非常具體的動作（例如「檢查 Gmail PubSub 統計資料」或「驗證閘道健康狀態」），請將 agents.defaults.heartbeat.prompt（或 agents.entries.*.heartbeat.prompt）設定為自訂本文（會逐字傳送）。

回應契約

• 如果沒有任何事項需要注意，請回覆 HEARTBEAT_OK。
• 心跳偵測執行也可以改為呼叫 heartbeat_respond，並搭配 notify: false 表示沒有可見更新；或搭配 notify: true 與 notificationText 發出警示。如果存在結構化工具回應，該回應的優先順序高於文字備援。
• 具有 notify: false 的有效 heartbeat_respond 結果會保持靜默，但會被記錄為有限的內部內容，以供該工作階段中的下一個使用者回合使用。no_change 確認及可見通知不會以此方式儲存。
• 在心跳偵測執行期間，當 HEARTBEAT_OK 出現在回覆的開頭或結尾時，OpenClaw 會將其視為確認。系統會移除該權杖；如果剩餘內容最多為 300 個字元，則會捨棄該回覆。
• 如果 HEARTBEAT_OK 出現在回覆的中間，系統不會對其進行特殊處理。
• 若為警示，請勿包含 HEARTBEAT_OK；只傳回警示文字。

在心跳偵測之外，訊息開頭／結尾意外出現的 HEARTBEAT_OK 會被移除並記錄；僅包含 HEARTBEAT_OK 的訊息會被捨棄。

設定

{  agents: {    defaults: {      heartbeat: {        every: "30m", // 預設：30m（0m 會停用）        model: "anthropic/claude-opus-4-6",        lightContext: false, // 預設：false；true 會在心跳偵測執行時略過工作區啟動檔案        isolatedSession: false, // 預設：false；true 會讓每次心跳偵測在全新工作階段中執行（無對話記錄）        target: "last", // 預設：none | 選項：last | none | <channel id>（核心或外掛，例如 "imessage"）        to: "+15551234567", // 選用的頻道專屬覆寫值        accountId: "ops-bot", // 選用的多帳號頻道 ID        prompt: "提供心跳偵測監控暫存內容時，請遵循該內容。週期性任務是排程工作；請使用排程工具或 openclaw cron 命令列介面建立或變更其排程，而非使用心跳偵測暫存內容。請勿根據先前的聊天推斷或重複舊任務。如果沒有任何事項需要注意，請回覆 HEARTBEAT_OK。",      },    },  },}

範圍與優先順序

• agents.defaults.heartbeat 設定全域心跳偵測行為。
• agents.entries.*.heartbeat 會合併於其上；如果任何代理程式具有 heartbeat 區塊，則只有這些代理程式會執行心跳偵測。
• channels.defaults.heartbeatVisibility 設定所有頻道的可見性預設值。
• channels.<channel>.heartbeatVisibility 會覆寫頻道預設值。
• channels.<channel>.accounts.<id>.heartbeatVisibility（多帳號頻道）會覆寫每個頻道的設定。

每個代理程式的心跳偵測

如果任何 agents.entries.* 項目包含 heartbeat 區塊，則只有這些代理程式會執行心跳偵測。每個代理程式的區塊會合併於 agents.defaults.heartbeat 之上（因此你可以只設定一次共用預設值，再針對每個代理程式覆寫）。

範例：兩個代理程式，只有第二個代理程式執行心跳偵測。

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 明確傳送至最後聯絡人（預設為 "none"）      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "提供心跳偵測監控暫存內容時，請遵循該內容。週期性任務是排程工作；請使用排程工具或 openclaw cron 命令列介面建立或變更其排程，而非使用心跳偵測暫存內容。請勿根據先前的聊天推斷或重複舊任務。如果沒有任何事項需要注意，請回覆 HEARTBEAT_OK。",        },      },    ],  },}

活躍時段範例

將心跳偵測限制在特定時區的營業時間內：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // 明確傳送至最後聯絡人（預設為 "none"）        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // 選用；若已設定 userTimezone，則使用該值，否則使用主機時區        },      },    },  },}

在此時段之外（美東時間上午 9 點之前或晚上 10 點之後），會略過心跳偵測。時段內的下一個排定觸發時間點將正常執行。

24/7 設定

如果你希望心跳偵測全天執行，請使用下列其中一種模式：

• 完全省略 activeHours（不限制時段；這是預設行為）。
• 設定全天時段：activeHours: { start: "00:00", end: "24:00" }。

多帳號範例

使用 accountId，以指定 Telegram 等多帳號頻道上的特定帳號：

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // 選用：傳送至特定主題／討論串          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

欄位說明

傳送行為

可見性控制

預設會抑制 HEARTBEAT_OK 確認訊息，同時傳送警示內容。你可以針對每個頻道或每個帳號調整此設定：

channels:  defaults:    heartbeat:      showOk: false # 隱藏 HEARTBEAT_OK（預設）      showAlerts: true # 顯示警示訊息（預設）      useIndicator: true # 發出指示器事件（預設）  telegram:    heartbeat:      showOk: true # 在 Telegram 上顯示 OK 確認訊息  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # 禁止為此帳號傳送警示

優先順序：每個帳號 → 每個頻道 → 頻道預設值 → 內建預設值。

每個旗標的作用

• showOk：當模型僅回覆 OK 時，傳送 HEARTBEAT_OK 確認訊息。
• showAlerts：當模型回覆非 OK 內容時，傳送警示內容。
• useIndicator：為介面狀態表面發出指示器事件。

如果三者皆為 false，OpenClaw 會完全略過心跳偵測執行（不呼叫模型）。

每個頻道與每個帳號的範例

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # 所有 Slack 帳號    accounts:      ops:        heartbeat:          showAlerts: false # 僅禁止 ops 帳號的警示  telegram:    heartbeat:      showOk: true

常見模式

監視器暫存文件（選用）

每個心跳偵測監視器排程工作都擁有一份儲存在共用狀態資料庫中的私有暫存文件。可將它視為你的「心跳偵測檢查清單」：精簡、穩定，且適合每 30 分鐘檢視一次。暫存文件存在時，其內容會附加至心跳偵測提示詞。

使用排程命令列介面管理它（工作 ID 來自 openclaw cron list --all）：

openclaw cron scratch <jobId>                 # 顯示目前的暫存文件openclaw cron scratch <jobId> --set "..."     # 以指定文字完整取代openclaw cron scratch <jobId> --file notes.md # 使用檔案內容取代（- 表示標準輸入）openclaw cron scratch <jobId> --unset         # 移除

寫入受到比較並交換機制保護：傳入 --expected-revision <n>，即可在發生並行編輯時失敗，而非覆寫該編輯。暫存文件上限為 256 KiB，且絕不會出現在 cron list/cron runs 輸出中。

代理程式也可更新自己的暫存文件：在心跳偵測回合期間，heartbeat_respond 接受選用的 scratch 字串，以完整取代監視器的暫存文件，供未來心跳偵測使用。

如果暫存文件存在但實際上為空（僅包含空白行、Markdown／HTML 註解、如 # Heading 的 Markdown 標題、程式碼圍欄標記或空白檢查清單項目），OpenClaw 會略過心跳偵測執行，以節省 API 呼叫。該略過會回報為 reason=empty-heartbeat-file。如果暫存文件不存在，心跳偵測仍會執行，並由模型決定要採取的動作。

請保持精簡（簡短的檢查清單或提醒），以避免提示詞過度膨脹。

暫存文件範例：

# 心跳偵測檢查清單 - 快速查看：收件匣中是否有任何緊急事項？- 如果是白天，且沒有其他待處理事項，進行一次簡單的問候。- 如果工作受阻，記下_缺少什麼_，並在下次詢問 Peter。

使用排程安排定期檢查

心跳偵測暫存文件是提示詞環境，而不是排程器。請將每項定期檢查建立為排程工作，使其擁有自己的週期、啟用／停用狀態和執行歷程記錄。當檢查需要使用一般對話環境時，排程工作仍可將主要工作階段設為目標。

舊版暫存文件可能包含結構化的 tasks: 區塊。升級後請執行一次 openclaw doctor --fix：Doctor 會將每個有效項目轉換為獨立排程的排程工作、保留其間隔與先前的上次執行時間，並移除已淘汰的區塊，同時保留周圍的暫存文件文字。執行階段心跳偵測回合不會將 tasks: 文字解析為排程。

Doctor 建立的心跳偵測工作會保留心跳偵測的有效時段、冷卻、防洪與忙碌防護。到期時間相同的工作可合併為單一心跳偵測回合。在有效時段外發生的執行會被略過，並在其下一次排程發生時間再次嘗試。

代理程式可以更新自己的暫存文件嗎？

可以。在心跳偵測回合期間，代理程式可將 scratch 值傳給 heartbeat_respond，以完整取代供未來心跳偵測使用的監視器文字。你也可以在一般聊天中要求它執行 openclaw cron scratch <jobId> --set ...，或使用相同命令自行編輯暫存文件。請使用排程管理定期排程，而非將排程器語法寫入暫存文件。

手動喚醒（隨需）

使用 openclaw system event 將系統事件加入佇列，並選擇是否立即觸發心跳偵測：

openclaw system event --text "檢查是否有緊急的後續事項" --mode now

若未提供 --session-key，且有多個代理程式設定了 heartbeat，則 --mode now 會立即執行其中每個代理程式的心跳偵測。

同一命令列介面群組中的相關心跳偵測控制：

openclaw system heartbeat last     # 顯示最近一次心跳偵測事件openclaw system heartbeat enable   # 啟用心跳偵測openclaw system heartbeat disable  # 停用心跳偵測

成本考量

心跳偵測會執行完整的代理程式回合。間隔越短，消耗的權杖越多。若要降低成本：

• 使用 isolatedSession: true，避免傳送完整的對話歷史記錄（每次執行可從約 100K 個權杖降至約 2–5K 個）。
• 使用 lightContext: true，在執行心跳偵測時略過工作區啟動載入檔案。
• 設定成本較低的 model（例如 ollama/llama3.2:1b）。
• 保持監控暫存內容精簡。
• 若只需要更新內部狀態，請使用 target: "none"。

心跳偵測後的上下文溢位

心跳偵測執行完成後，會保留共用工作階段中既有的執行階段模型。因此，若心跳偵測曾將工作階段切換至較小的本機模型（例如具有 32k 上下文視窗的 Ollama 模型），下一個主要工作階段回合仍可能沿用該模型。若下一回合接著回報上下文溢位，且該工作階段最近使用的執行階段模型符合已設定的 heartbeat.model，OpenClaw 的復原訊息會指出心跳偵測模型殘留可能是原因，並建議修正方式。

若要避免此問題：使用 isolatedSession: true，在全新的工作階段中執行心跳偵測（也可搭配 lightContext: true，將提示詞縮至最小），或選擇上下文視窗足以容納共用工作階段的心跳偵測模型。

相關內容

• 自動化 - 一覽所有自動化機制
• 背景任務 - 如何追蹤分離執行的工作
• 時區 - 時區如何影響心跳偵測排程
• 疑難排解 - 偵錯自動化問題