心跳偵測與排程? 請參閱自動化,了解何時使用各自功能的指引。
快速開始(初學者)
範例設定:
預設值
- 間隔:
30m。套用 Anthropic 提供者預設值時,如果解析後的驗證模式為 OAuth/token(包括 Claude CLI 重複使用),會將此提升為1h,但僅在heartbeat.every未設定時。設定agents.defaults.heartbeat.every或每個代理程式的agents.list[].heartbeat.every;使用0m停用。 - 提示本文(可透過
agents.defaults.heartbeat.prompt設定):Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. 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.list[].heartbeat.timeoutSeconds。 - 心跳偵測提示會作為使用者訊息逐字傳送。只有在預設代理程式啟用心跳偵測(且
includeSystemPromptSection不是false)時,系統提示才會包含「Heartbeats」區段,並且執行會在內部標記。 - 使用
0m停用心跳偵測時,正常執行也會從啟動情境中省略HEARTBEAT.md,讓模型不會看到僅供心跳偵測使用的指示。 - 活動時段(
heartbeat.activeHours)會在設定的時區中檢查。在時間範圍外,心跳偵測會跳過,直到下一個位於時間範圍內的刻度。 - 當排程工作正在進行或佇列中時,心跳偵測會自動延後。設定
heartbeat.skipWhenBusy: true也會在代理程式自己的工作階段鍵控子代理程式或巢狀命令通道忙碌時延後該代理程式;同層代理程式不再只是因為另一個代理程式有子代理程式工作正在進行就暫停。
心跳偵測提示的用途
預設提示刻意保持廣泛:- 背景任務:「Consider outstanding tasks」會推動代理程式檢視後續事項(收件匣、行事曆、提醒、佇列工作),並提示任何緊急事項。
- 人類關懷確認:「Checkup sometimes on your human during day time」會推動偶爾傳送輕量的「有什麼需要嗎?」訊息,但會使用你設定的本地時區(請參閱時區)避免夜間垃圾訊息。
agents.defaults.heartbeat.prompt(或 agents.list[].heartbeat.prompt)設定為自訂本文(逐字傳送)。
回應合約
- 如果沒有需要注意的事項,請回覆
HEARTBEAT_OK。 - 心跳偵測執行也可以改為呼叫
heartbeat_respond,搭配notify: false表示沒有可見更新,或notify: true加上notificationText表示警示。存在時,結構化工具回應優先於文字備援。 - 在心跳偵測執行期間,當
HEARTBEAT_OK出現在回覆的開頭或結尾時,OpenClaw 會將其視為確認。該權杖會被移除,而且如果剩餘內容 ≤ackMaxChars(預設:300),回覆會被捨棄。 - 如果
HEARTBEAT_OK出現在回覆的中間,不會受到特殊處理。 - 對於警示,不要包含
HEARTBEAT_OK;只傳回警示文字。
HEARTBEAT_OK 會被移除並記錄;只有 HEARTBEAT_OK 的訊息會被捨棄。
設定
範圍與優先順序
agents.defaults.heartbeat設定全域心跳偵測行為。agents.list[].heartbeat會合併在其上;如果任何代理程式有heartbeat區塊,只有那些代理程式會執行心跳偵測。channels.defaults.heartbeat設定所有通道的可見性預設值。channels.<channel>.heartbeat覆寫通道預設值。channels.<channel>.accounts.<id>.heartbeat(多帳號通道)覆寫每個通道的設定。
每個代理程式的心跳偵測
如果任何agents.list[] 項目包含 heartbeat 區塊,只有那些代理程式會執行心跳偵測。每個代理程式的區塊會合併在 agents.defaults.heartbeat 之上(因此你可以先設定一次共用預設值,再依代理程式覆寫)。
範例:兩個代理程式,只有第二個代理程式執行心跳偵測。
活動時段範例
將心跳偵測限制在特定時區的營業時間:24/7 設定
如果你希望心跳偵測全天執行,請使用以下其中一種模式:- 完全省略
activeHours(沒有時間範圍限制;這是預設行為)。 - 設定整日時間範圍:
activeHours: { start: "00:00", end: "24:00" }。
多帳號範例
使用accountId 來指定多帳號通道(例如 Telegram)上的特定帳號:
欄位備註
心跳偵測間隔(持續時間字串;預設單位 = 分鐘)。
心跳偵測執行的選用模型覆寫(
provider/model)。啟用時,也會在可用時傳送獨立的
Thinking 訊息(與 /reasoning on 相同形狀)。為 true 時,心跳偵測執行會使用輕量啟動情境,並且只保留工作區啟動檔案中的
HEARTBEAT.md。為 true 時,每次心跳偵測都會在沒有先前對話歷史的全新工作階段中執行。使用與排程
sessionTarget: "isolated" 相同的隔離模式。大幅降低每次心跳偵測的權杖成本。搭配 lightContext: true 可獲得最大節省。傳送路由仍使用主要工作階段情境。為 true 時,心跳偵測執行會因該代理程式的額外忙碌通道而延後:其自己的工作階段鍵控子代理程式或巢狀命令工作。排程通道一律會延後心跳偵測,即使沒有此旗標也是如此,因此本地模型主機不會同時執行排程和心跳偵測提示。
last:傳送到最後使用的外部通道。- 明確通道:任何已設定的通道或外掛 id,例如
discord、matrix、telegram或whatsapp。 none(預設):執行心跳偵測但不會傳送到外部。
控制直接/DM 傳送行為。
allow:允許直接/DM 心跳偵測傳送。block:抑制直接/DM 傳送(reason=dm-blocked)。選用的收件者覆寫(通道特定 ID,例如 WhatsApp 的 E.164 或 Telegram 聊天 ID)。對於 Telegram 主題/討論串,請使用
<chatId>:topic:<messageThreadId>。多帳號通道的選用帳號 ID。當
target: "last" 時,如果解析出的最後通道支援帳號,帳號 ID 會套用到該通道;否則會被忽略。如果帳號 ID 與解析通道中已設定的帳號不相符,將略過傳送。覆寫預設提示本文(不合併)。
是否注入預設代理的
## Heartbeats 系統提示章節。設為 false 可保留心跳偵測執行階段行為(節奏、傳送、HEARTBEAT.md),同時從代理系統提示中省略心跳偵測指示。傳送前,
HEARTBEAT_OK 後允許的最大字元數。為 true 時,會在心跳偵測執行期間抑制工具錯誤警告酬載。
心跳偵測代理回合中止前允許的最大秒數。保持未設定時,若已設定
agents.defaults.timeoutSeconds 則使用該值,否則使用心跳偵測節奏並上限為 600 秒。將心跳偵測執行限制在時間視窗內。物件包含
start(HH:MM,含起始;使用 00:00 表示一天開始)、end(HH:MM,不含結束;允許 24:00 表示一天結束),以及選用的 timezone。- 省略或
"user":若已設定agents.defaults.userTimezone則使用該值,否則退回主機系統時區。 "local":一律使用主機系統時區。- 任何 IANA 識別碼(例如
America/New_York):直接使用;若無效,則退回上述"user"行為。 - 對於有效視窗,
start和end不得相等;相等值會被視為零寬度(一律在視窗外)。 - 在有效視窗外,心跳偵測會被略過,直到視窗內的下一個 tick。
傳送行為
Session and target routing
Session and target routing
- 心跳偵測預設會在代理的主要工作階段中執行(
agent:<id>:<mainKey>),或在session.scope = "global"時使用global。設定session可覆寫為特定通道工作階段(Discord/WhatsApp 等)。 session只會影響執行內容;傳送由target和to控制。- 若要傳送到特定通道/收件者,請設定
target+to。使用target: "last"時,傳送會使用該工作階段的最後外部通道。 - 心跳偵測傳送預設允許直接/DM 目標。設定
directPolicy: "block"可在仍執行心跳偵測回合的同時,抑制直接目標傳送。 - 如果主佇列、目標工作階段 lane、排程 lane 或作用中的排程作業忙碌中,心跳偵測會被略過並稍後重試。
- 如果
skipWhenBusy: true,此代理以工作階段鍵控的子代理和巢狀 lane 也會延後心跳偵測執行。其他代理的忙碌 lane 不會延後此代理。 - 如果
target未解析到外部目的地,執行仍會發生,但不會傳送外送訊息。
Visibility and skip behavior
Visibility and skip behavior
- 如果
showOk、showAlerts和useIndicator全部停用,執行會一開始就以reason=alerts-disabled略過。 - 如果只停用警示傳送,OpenClaw 仍可執行心跳偵測、更新到期任務時間戳、還原工作階段閒置時間戳,並抑制對外警示酬載。
- 如果解析出的心跳偵測目標支援輸入中狀態,OpenClaw 會在心跳偵測執行期間顯示輸入中。這會使用心跳偵測原本要傳送聊天輸出的同一個目標,並可透過
typingMode: "never"停用。
Session lifecycle and audit
Session lifecycle and audit
- 僅心跳偵測的回覆不會讓工作階段保持存活。心跳偵測中繼資料可能會更新工作階段列,但閒置到期會使用最後一則真實使用者/通道訊息的
lastInteractionAt,每日到期則使用sessionStartedAt。 - Control UI 和 WebChat 歷史記錄會隱藏心跳偵測提示和僅 OK 的確認。底層工作階段逐字稿仍可能包含這些回合,以供稽核/重播。
- 分離的背景任務可以將系統事件加入佇列,並在主要工作階段應快速注意到某件事時喚醒心跳偵測。該喚醒不會讓心跳偵測執行成為背景任務。
可見性控制
預設會抑制HEARTBEAT_OK 確認,同時傳送警示內容。你可以依通道或依帳號調整:
每個旗標的作用
showOk:當模型傳回僅 OK 的回覆時,傳送HEARTBEAT_OK確認。showAlerts:當模型傳回非 OK 回覆時,傳送警示內容。useIndicator:為 UI 狀態介面發出指示器事件。
每通道與每帳號範例
常見模式
| 目標 | 設定 |
|---|---|
| 預設行為(靜默 OK,開啟警示) | (不需要設定) |
| 完全靜默(無訊息、無指示器) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false } |
| 僅指示器(無訊息) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true } |
| 僅在一個通道中顯示 OK | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md(選用)
如果工作區中存在HEARTBEAT.md 檔案,預設提示會要求代理讀取它。請把它視為你的「心跳偵測檢查清單」:簡短、穩定,且適合每 30 分鐘考量一次。
在一般執行中,只有在預設代理啟用心跳偵測指引時,才會注入 HEARTBEAT.md。使用 0m 停用心跳偵測節奏,或設定 includeSystemPromptSection: false,會從一般啟動內容中省略它。
在原生 Codex harness 上,HEARTBEAT.md 內容不會像其他啟動檔一樣注入回合。如果檔案存在且包含非空白內容,心跳偵測協作模式註記會將 Codex 指向該檔案,並告知它在繼續前先讀取檔案。
如果 HEARTBEAT.md 存在但實際上是空的(只有空白行、Markdown/HTML 註解、像 # Heading 這樣的 Markdown 標題、fence 標記,或空的檢查清單 stub),OpenClaw 會略過心跳偵測執行以節省 API 呼叫。該略過會回報為 reason=empty-heartbeat-file。如果檔案遺失,心跳偵測仍會執行,並由模型決定要做什麼。
請保持精簡(短檢查清單或提醒),以避免提示膨脹。
HEARTBEAT.md 範例:
tasks: 區塊
HEARTBEAT.md 也支援一個小型結構化 tasks: 區塊,用於心跳偵測內部以間隔為基礎的檢查。
範例:
Behavior
Behavior
- OpenClaw 會剖析
tasks:區塊,並依每個任務自己的interval檢查。 - 只有到期的任務會包含在該 tick 的心跳偵測提示中。
- 如果沒有任務到期,心跳偵測會完全略過(
reason=no-tasks-due),以避免浪費模型呼叫。 HEARTBEAT.md中的非任務內容會保留,並作為額外內容附加在到期任務清單之後。- 任務上次執行時間戳會儲存在工作階段狀態(
heartbeatTaskState)中,因此間隔可在一般重新啟動後保留。 - 任務時間戳只會在心跳偵測執行完成其一般回覆路徑後推進。略過的
empty-heartbeat-file/no-tasks-due執行不會將任務標記為已完成。
代理可以更新 HEARTBEAT.md 嗎?
可以 - 如果你要求它這麼做。HEARTBEAT.md 只是代理工作區中的一般檔案,因此你可以在一般聊天中告訴代理,例如:
- “Update
HEARTBEAT.mdto add a daily calendar check.” - “Rewrite
HEARTBEAT.mdso it’s shorter and focused on inbox follow-ups.”
手動喚醒(隨需)
使用openclaw system event 將系統事件加入佇列,並可選擇觸發立即心跳偵測:
| 旗標 | 說明 |
|---|---|
--text <text> | 系統事件文字(必填)。 |
--mode <mode> | now 會執行立即心跳偵測;next-heartbeat(預設)會等待下一個排程 tick。 |
--session-key <sessionKey> | 將事件目標設為特定工作階段;預設為代理的主要工作階段。 |
--json | 輸出 JSON。 |
--session-key,且有多個代理設定了 heartbeat,--mode now 會立即執行每個這類代理的心跳偵測。
同一個命令列介面群組中的相關心跳偵測控制:
推理傳送(選用)
根據預設,心跳偵測只會傳送最終的「答案」承載內容。 如果你想要透明度,請啟用:agents.defaults.heartbeat.includeReasoning: true
Thinking 為前綴的獨立訊息(形狀與 /reasoning on 相同)。當代理程式正在管理多個工作階段/Codex,且你想知道它為何決定 ping 你時,這會很有用,但它也可能洩漏比你想要更多的內部細節。在群組聊天中建議保持關閉。
成本意識
心跳偵測會執行完整的代理程式回合。間隔越短會消耗越多 token。若要降低成本:- 使用
isolatedSession: true,避免傳送完整對話歷史記錄(每次執行約從 100K token 降到約 2-5K)。 - 使用
lightContext: true,將啟動載入檔案限制為只有HEARTBEAT.md。 - 設定較便宜的
model(例如ollama/llama3.2:1b)。 - 保持
HEARTBEAT.md精簡。 - 如果你只想要內部狀態更新,請使用
target: "none"。
心跳偵測後的情境溢位
心跳偵測會在執行完成後保留共享工作階段既有的執行階段模型,因此將工作階段切換到較小本機模型(例如具備 32k 視窗的 Ollama 模型)的心跳偵測,可能會讓該模型保留到下一個主工作階段回合。如果下一個回合接著回報情境溢位,且工作階段的上一個執行階段模型符合設定的heartbeat.model,OpenClaw 的復原訊息會指出心跳偵測模型滲漏是可能原因,並建議修正方式。
若要避免這種情況:使用 isolatedSession: true 在全新工作階段中執行心跳偵測(可選擇搭配 lightContext: true 以取得最小提示),或選擇具備足夠大情境視窗、可支援共享工作階段的心跳偵測模型。