讓你的 Agent 自動動起來：Heartbeat (Gateway) 配置指南

快速上手（初學者）

保持 Heartbeat 開啟（預設是 30m，如果是 Anthropic OAuth/setup-token 則是 1h），或者設定你自己的頻率。
在 agent workspace 建立一個小的 HEARTBEAT.md 檢查清單（選填，但建議加上）。
決定 Heartbeat 訊息要發送到哪裡（預設 target: "none"；設定為 target: "last" 會傳送給最後一個聯絡人）。
選填：開啟 Heartbeat 推理過程 (reasoning) 的傳送，增加透明度。
選填：如果 Heartbeat 執行時只需要 HEARTBEAT.md，可以使用輕量化的 bootstrap context。
選填：開啟獨立 session (isolated sessions)，避免每次 Heartbeat 都傳送完整的對話歷史。
選填：將 Heartbeat 限制在活躍時間內（當地時間）。

範例設定：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files
        isolatedSession: true, // optional: fresh session each run (no conversation history)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

預設設定

間隔：30m（當偵測到 Anthropic OAuth/setup-token 驗證模式時為 1h）。可以透過 agents.defaults.heartbeat.every 或針對特定 agent 設定 agents.list[].heartbeat.every；設定為 0m 即可停用。
Prompt 內容（可透過 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.
Heartbeat prompt 會以原樣 (verbatim) 作為使用者訊息傳送。System prompt 會包含一個「Heartbeat」區塊，且這次執行會在內部被標記。
活躍時間 (heartbeat.activeHours) 會根據設定的時區進行檢查。在時間視窗之外，Heartbeat 會被跳過，直到進入下一個時間視窗。

Heartbeat Prompt 的用途

預設的 prompt 刻意設計得很廣泛：

背景任務：「考慮未完成的任務」會引導 agent 檢查後續跟進事項（收件匣、日曆、提醒、排隊的工作），並提出任何緊急的事項。
人類關懷：「在白天偶爾關心你的人類」會引導 agent 偶爾發送輕量的「有什麼需要幫忙的嗎？」訊息，但透過你設定的在地時區（參考 /concepts/timezone）來避免在深夜騷擾你。

Heartbeat 可以對已完成的 background tasks 做出反應，但 Heartbeat 執行本身並不會產生 task 紀錄。

如果你想讓 Heartbeat 執行非常具體的操作（例如「檢查 Gmail PubSub 統計數據」或「驗證 Gateway 健康狀態」），請將 agents.defaults.heartbeat.prompt（或 agents.list[].heartbeat.prompt）設定為自定義內容（會原樣傳送）。

回應規範

如果沒有什麼需要注意的事項，請回覆 HEARTBEAT_OK。
在 Heartbeat 執行期間，當 HEARTBEAT_OK 出現在回覆的開頭或結尾時，OpenClaw 會將其視為確認 (ack)。該 token 會被移除，如果剩餘內容 ≤ ackMaxChars（預設：300），則該回覆會被捨棄。
如果 HEARTBEAT_OK 出現在回覆的中間，則不會被特殊處理。
如果是發送警報，不要包含 HEARTBEAT_OK；只回傳警報文字即可。

在 Heartbeat 之外，訊息開頭或結尾出現的零星 HEARTBEAT_OK 會被移除並記錄；如果訊息內容只有 HEARTBEAT_OK，則會被捨棄。

配置

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific override
        accountId: "ops-bot", // optional multi-account channel id
        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.",
        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
      },
    },
  },
}

範圍與優先順序

agents.defaults.heartbeat 設定全域的 Heartbeat 行為。
agents.list[].heartbeat 會合併並覆蓋上方設定；如果任何 Agent 擁有 heartbeat 區塊，就只有這些 Agent 會執行 Heartbeat。
channels.defaults.heartbeat 設定所有 Channel 的預設可見性。
channels.<channel>.heartbeat 會覆蓋 Channel 的預設值。
channels.<channel>.accounts.<id>.heartbeat（多帳號 Channel）會覆蓋每個 Channel 的特定設定。

個別 Agent 的 Heartbeat 設定

如果任何 agents.list[] 項目包含 heartbeat 區塊，就只有這些 Agent 會執行 Heartbeat。每個 Agent 的區塊會合併在 agents.defaults.heartbeat 之上（所以你可以先設定一次共用的預設值，再針對每個 Agent 進行覆蓋）。

範例：有兩個 Agent，但只有第二個 Agent 會執行 Heartbeat。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          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.",
        },
      },
    ],
  },
}

活躍時間範例

將 Heartbeat 限制在特定時區的工作時間內：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

在這個時間窗口之外（美東時間上午 9 點之前或晚上 10 點之後），Heartbeat 會被跳過。下一個落在窗口內的預定時間點將會正常執行。

24/7 全天候設定

如果你希望 Heartbeat 整天執行，可以使用以下其中一種模式：

完全省略 activeHours（沒有時間窗口限制；這是預設行為）。
設定全天窗口：activeHours: { start: "00:00", end: "24:00" }。

不要將 start 和 end 設定為相同的時間（例如 08:00 到 08:00）。這會被視為寬度為零的窗口，導致 Heartbeat 永遠被跳過。

多帳號範例

在 Telegram 等多帳號 Channel 上，使用 accountId 來指定特定的帳號：

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // optional: route to a specific topic/thread
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

欄位說明

every: Heartbeat 間隔（時間長度字串；預設單位為分鐘）。
model: 選填，覆蓋 Heartbeat 執行時使用的模型 (provider/model)。
includeReasoning: 啟用時，如果有的話也會傳送獨立的 Reasoning: 訊息（格式與 /reasoning on 相同）。
lightContext: 為 true 時，Heartbeat 執行會使用輕量級的啟動上下文，且僅保留 Workspace 啟動檔案中的 HEARTBEAT.md。
isolatedSession: 為 true 時，每次 Heartbeat 都會在一個沒有先前對話歷史的新 Session 中執行。這使用了與 cron sessionTarget: "isolated" 相同的隔離模式。這能大幅降低每次 Heartbeat 的 Token 消耗。建議搭配 lightContext: true 以達到最大節省效果。傳送路由仍會使用主 Session 的上下文。
session: 選填，Heartbeat 執行時的 Session Key。
- main (預設值): Agent 的主 Session。
- 明確的 Session Key (從 openclaw sessions --json 或 sessions CLI 複製)。
- Session Key 格式：請參考 Sessions 與 Groups。
target:
- last: 傳送到最後使用的外部 Channel。
- 明確的 Channel: 任何已配置的 Channel 或 Plugin ID，例如 discord, matrix, telegram 或 whatsapp。
- none (預設值): 執行 Heartbeat 但不進行外部傳送。
directPolicy: 控制直接訊息/私訊 (DM) 的傳送行為：
- allow (預設值): 允許直接訊息/私訊的 Heartbeat 傳送。
- block: 抑制直接訊息/私訊傳送 (reason=dm-blocked)。
to: 選填，覆蓋接收者（Channel 特定的 ID，例如 WhatsApp 的 E.164 格式或 Telegram 的 Chat ID）。對於 Telegram 的話題/討論串 (Topics/Threads)，請使用 <chatId>:topic:<messageThreadId>。
accountId: 選填，多帳號 Channel 的帳號 ID。當 target: "last" 時，如果解析出的最後一個 Channel 支援多帳號，則會套用此帳號 ID；否則會被忽略。如果帳號 ID 與該 Channel 配置的帳號不符，則會跳過傳送。
prompt: 覆蓋預設的 Prompt 主體（不會進行合併）。
ackMaxChars: 在 HEARTBEAT_OK 之後，傳送前允許的最大字元數。
suppressToolErrorWarnings: 為 true 時，會抑制 Heartbeat 執行期間的工具錯誤警告內容。
activeHours: 將 Heartbeat 執行限制在某個時間窗口內。這是一個包含 start（HH:MM，包含；當天開始請用 00:00）、end（HH:MM，不包含；當天結束可用 24:00）以及選填 timezone 的物件。
- 省略或設為 "user": 使用你的 agents.defaults.userTimezone（如果有設定），否則退而使用主機系統時區。
- "local": 始終使用主機系統時區。
- 任何 IANA 識別碼（例如 America/New_York）：直接使用；如果無效，則退而使用上述的 "user" 行為。
- start 與 end 不能相等；相等的值會被視為零寬度（永遠在窗口之外）。
- 在活躍時間窗口之外，Heartbeat 會被跳過，直到下一個落在窗口內的時間點。

傳送行為

預設情況下，Heartbeat 在 Agent 的主 Session 中執行 (agent:<id>:<mainKey>)，或者當 session.scope = "global" 時在 global 中執行。你可以設定 session 來覆蓋並指定特定的 Channel Session (Discord/WhatsApp 等)。
session 僅影響執行的上下文；傳送則是由 target 與 to 控制。
若要傳送到特定的 Channel/接收者，請設定 target + to。若使用 target: "last"，傳送會使用該 Session 最後一個外部 Channel。
Heartbeat 傳送預設允許直接訊息/私訊目標。設定 directPolicy: "block" 可以抑制直接目標的傳送，但 Heartbeat 輪次仍會執行。
如果主佇列 (Main Queue) 繁忙，Heartbeat 會被跳過並在稍後重試。
如果 target 無法解析出外部目的地，執行仍會發生，但不會送出任何外部訊息。
僅限 Heartbeat 的回覆不會讓 Session 保持活躍；系統會還原最後的 updatedAt，讓閒置過期機制正常運作。
分離的 background tasks 可以將系統事件排入佇列，並在主 Session 需要快速注意到某些事情時喚醒 Heartbeat。這種喚醒不會讓 Heartbeat 執行背景任務。

可見度控制 (Visibility controls)

預設情況下，當發送警報內容時，HEARTBEAT_OK 的確認訊息會被隱藏。你可以針對每個 channel 或帳號進行調整：

channels:
  defaults:
    heartbeat:
      showOk: false # Hide HEARTBEAT_OK (default)
      showAlerts: true # Show alert messages (default)
      useIndicator: true # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true # Show OK acknowledgments on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alert delivery for this account

優先順序：per-account → per-channel → channel defaults → 內建預設值。

每個 flag 的作用

showOk: 當 model 回傳僅有 OK 的回覆時，發送 HEARTBEAT_OK 確認訊息。
showAlerts: 當 model 回傳非 OK 的回覆時，發送警報內容。
useIndicator: 為 UI 狀態介面發送指示器事件。

如果這三個都是 false，OpenClaw 會完全跳過 heartbeat 執行（不會呼叫 model）。

Per-channel 與 per-account 範例

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

常見模式

目標	設定
預設行為（隱藏 OK，開啟警報）	(不需要設定)
完全靜音（無訊息，無指示器）	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
僅指示器（無訊息）	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
僅在單一 channel 顯示 OK	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (選填)

如果 workspace 中存在 HEARTBEAT.md 檔案，預設的 prompt 會告訴 agent 去讀取它。你可以把它當作你的「heartbeat 檢查清單」：內容精簡、穩定，且每 30 分鐘包含在 prompt 中也很安全。

如果 HEARTBEAT.md 存在但內容基本上是空的（只有空白行或像 # Heading 這樣的 markdown 標題），OpenClaw 會跳過 heartbeat 執行以節省 API 呼叫。如果檔案不存在，heartbeat 仍會執行，並由 model 決定要做什麼。

保持內容精簡（短小的檢查清單或提醒），避免 prompt 過於臃腫。

HEARTBEAT.md 範例：

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

Agent 可以更新 HEARTBEAT.md 嗎？

可以 —— 只要你要求它這麼做。

HEARTBEAT.md 只是 agent workspace 中的一個普通檔案，所以你可以在一般對話中告訴 agent：

「更新 HEARTBEAT.md，加入每日日曆檢查。」
「重寫 HEARTBEAT.md，讓它更短一點，並專注在收件匣跟進。」

如果你希望這能主動發生，你也可以在 heartbeat prompt 中加入明確的一行，例如：「如果檢查清單過時了，請用更好的內容更新 HEARTBEAT.md。」

安全提示：不要把秘密（API keys、電話號碼、私密 token）放進 HEARTBEAT.md —— 它會成為 prompt context 的一部分。

手動喚醒 (隨選)

你可以透過排入系統事件來立即觸發 heartbeat：

openclaw system event --text "Check for urgent follow-ups" --mode now

如果你有多個 agent 都設定了 heartbeat，手動喚醒會讓這些 agent 的 heartbeat 全部立刻執行。

使用 --mode next-heartbeat 則會等到下一次預定的排程時間點才執行。

推理過程傳送 (選填)

預設情況下，heartbeat 只會傳送最終的「答案」內容。

如果你想要更透明的資訊，可以開啟：

agents.defaults.heartbeat.includeReasoning: true

開啟後，heartbeat 會額外傳送一則以 Reasoning: 開頭的獨立訊息（格式與 /reasoning on 相同）。當 agent 同時管理多個 session 或 codex，而你想知道它為什麼決定傳訊息給你時，這功能非常實用。不過這也可能會洩漏比你預期更多的內部細節，建議在群組對話中保持關閉。

成本考量

Heartbeats 會執行完整的 agent 輪次。設定的間隔越短，消耗的 token 就越多。你可以透過以下方式來降低成本：

使用 isolatedSession: true 來避免發送完整的對話歷史（這能讓每次執行的 token 消耗從約 100K 降到 2-5K 左右）。
使用 lightContext: true 將引導檔案限制在只有 HEARTBEAT.md。
設定較便宜的 model（例如 ollama/llama3.2:1b）。
保持 HEARTBEAT.md 內容精簡。
如果你只需要更新內部狀態，請使用 target: "none"。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。