Heartbeat (Gateway)

Heartbeat vs Cron? Xem Cron vs Heartbeat để biết khi nào nên dùng cái nào.

Heartbeat chạy các lượt Agent định kỳ trong Session chính để model có thể phát hiện những việc cần chú ý mà không spam các bạn.

Bắt đầu nhanh (dành cho người mới)

Để Heartbeat bật (mặc định là 30m, hoặc 1h nếu dùng Anthropic OAuth/setup-token) hoặc tự đặt tần suất.
Tạo một file HEARTBEAT.md nhỏ gọn trong Workspace của Agent (tùy chọn nhưng khuyên dùng).
Quyết định nơi nhận thông báo Heartbeat (target: "last" là mặc định).
Tùy chọn: bật gửi reasoning của Heartbeat để minh bạch hơn.
Tùy chọn: giới hạn Heartbeat trong giờ hoạt động (giờ địa phương).

Ví dụ config:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // tùy chọn: gửi thêm tin nhắn `Reasoning:`
      },
    },
  },
}

Cài đặt mặc định

Khoảng thời gian: 30m (hoặc 1h khi phát hiện dùng Anthropic OAuth/setup-token). Đặt agents.defaults.heartbeat.every hoặc theo từng Agent agents.list[].heartbeat.every; dùng 0m để tắt.
Nội dung Prompt (có thể config qua 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.
Prompt Heartbeat được gửi nguyên văn như tin nhắn của user. System prompt có phần “Heartbeat” và lượt chạy được đánh dấu nội bộ.
Giờ hoạt động (heartbeat.activeHours) được kiểm tra theo timezone đã config. Ngoài khung giờ này, Heartbeat sẽ bị bỏ qua cho đến lần tick tiếp theo trong khung giờ.

Mục đích của Heartbeat prompt

Prompt mặc định cố tình được viết rộng:

Tác vụ nền: “Consider outstanding tasks” nhắc Agent xem lại các việc cần theo dõi (inbox, lịch, nhắc nhở, công việc đang chờ) và báo những gì khẩn cấp.
Check-in với người dùng: “Checkup sometimes on your human during day time” nhắc Agent thỉnh thoảng gửi tin nhắn nhẹ nhàng kiểu “có cần gì không?”, nhưng tránh spam ban đêm bằng cách dùng timezone địa phương đã config (xem /concepts/timezone).

Nếu các bạn muốn Heartbeat làm việc cụ thể nào đó (ví dụ “check Gmail PubSub stats” hoặc “verify gateway health”), hãy đặt agents.defaults.heartbeat.prompt (hoặc agents.list[].heartbeat.prompt) thành nội dung tùy chỉnh (gửi nguyên văn).

Quy tắc phản hồi

Nếu không có gì cần chú ý, trả về HEARTBEAT_OK.
Trong các lượt chạy Heartbeat, OpenClaw coi HEARTBEAT_OK là xác nhận khi nó xuất hiện ở đầu hoặc cuối phản hồi. Token này sẽ bị loại bỏ và phản hồi sẽ bị drop nếu nội dung còn lại ≤ ackMaxChars (mặc định: 300).
Nếu HEARTBEAT_OK xuất hiện ở giữa phản hồi, nó không được xử lý đặc biệt.
Với cảnh báo, không bao gồm HEARTBEAT_OK; chỉ trả về nội dung cảnh báo.

Ngoài Heartbeat, HEARTBEAT_OK lạc ở đầu/cuối tin nhắn sẽ bị loại bỏ và ghi log; tin nhắn chỉ có HEARTBEAT_OK sẽ bị drop.

Config

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // mặc định: 30m (0m để tắt)
        model: "anthropic/claude-opus-4-5",
        includeReasoning: false, // mặc định: false (gửi tin nhắn Reasoning: riêng khi có)
        target: "last", // last | none | <channel id> (core hoặc plugin, vd "bluebubbles")
        to: "+15551234567", // tùy chọn ghi đè người nhận theo channel
        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, // số ký tự tối đa cho phép sau HEARTBEAT_OK
      },
    },
  },
}

Phạm vi và thứ tự ưu tiên

agents.defaults.heartbeat đặt hành vi Heartbeat toàn cục.
agents.list[].heartbeat merge lên trên; nếu Agent nào có block heartbeat, chỉ những Agent đó chạy Heartbeat.
channels.defaults.heartbeat đặt mặc định hiển thị cho tất cả Channel.
channels.<channel>.heartbeat ghi đè mặc định của Channel.
channels.<channel>.accounts.<id>.heartbeat (Channel nhiều tài khoản) ghi đè cài đặt theo Channel.

Heartbeat theo từng Agent

Nếu bất kỳ entry agents.list[] nào có block heartbeat, chỉ những Agent đó chạy Heartbeat. Block theo Agent sẽ merge lên trên agents.defaults.heartbeat (để các bạn có thể đặt mặc định chung một lần và ghi đè theo từng Agent).

Ví dụ: hai Agent, chỉ Agent thứ hai chạy Heartbeat.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    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.",
        },
      },
    ],
  },
}

Ghi chú về các trường

every: khoảng thời gian Heartbeat (chuỗi duration; đơn vị mặc định = phút).
model: tùy chọn ghi đè model cho lượt chạy Heartbeat (provider/model).
includeReasoning: khi bật, cũng gửi tin nhắn Reasoning: riêng khi có (giống /reasoning on).
session: tùy chọn session key cho lượt chạy Heartbeat.
- main (mặc định): Session chính của Agent.
- Session key cụ thể (copy từ openclaw sessions --json hoặc sessions CLI).
- Định dạng session key: xem Sessions và Groups.
target:
- last (mặc định): gửi đến Channel bên ngoài được dùng gần nhất.
- Channel cụ thể: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
- none: chạy Heartbeat nhưng không gửi ra ngoài.
to: tùy chọn ghi đè người nhận (id theo Channel, vd E.164 cho WhatsApp hoặc Telegram chat id).
prompt: ghi đè nội dung prompt mặc định (không merge).
ackMaxChars: số ký tự tối đa cho phép sau HEARTBEAT_OK trước khi gửi.

Hành vi gửi tin

Heartbeat chạy trong Session chính của Agent theo mặc định (agent:<id>:<mainKey>), hoặc global khi session.scope = "global". Đặt session để ghi đè sang Session của Channel cụ thể (Discord/WhatsApp/v.v.).
session chỉ ảnh hưởng ngữ cảnh chạy; việc gửi tin được điều khiển bởi target và to.
Để gửi đến Channel/người nhận cụ thể, đặt target + to. Với target: "last", việc gửi dùng Channel bên ngoài cuối cùng của Session đó.
Nếu hàng đợi chính đang bận, Heartbeat sẽ bị bỏ qua và thử lại sau.
Nếu target không resolve được đích bên ngoài, lượt chạy vẫn diễn ra nhưng không gửi tin ra ngoài.
Phản hồi chỉ từ Heartbeat không giữ Session sống; updatedAt cuối cùng được khôi phục để idle expiry hoạt động bình thường.

Kiểm soát hiển thị

Mặc định, xác nhận HEARTBEAT_OK bị ẩn trong khi nội dung cảnh báo được gửi. Các bạn có thể điều chỉnh theo từng Channel hoặc từng tài khoản:

channels:
  defaults:
    heartbeat:
      showOk: false # Ẩn HEARTBEAT_OK (mặc định)
      showAlerts: true # Hiện tin cảnh báo (mặc định)
      useIndicator: true # Phát sự kiện indicator (mặc định)
  telegram:
    heartbeat:
      showOk: true # Hiện xác nhận OK trên Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Ẩn cảnh báo cho tài khoản này

Thứ tự ưu tiên: theo tài khoản → theo Channel → mặc định Channel → mặc định built-in.

Chức năng của từng flag

showOk: gửi xác nhận HEARTBEAT_OK khi model trả về phản hồi chỉ có OK.
showAlerts: gửi nội dung cảnh báo khi model trả về phản hồi không phải OK.
useIndicator: phát sự kiện indicator cho các giao diện trạng thái.

Nếu cả ba đều false, OpenClaw bỏ qua lượt chạy Heartbeat hoàn toàn (không gọi model).

Ví dụ theo Channel vs theo tài khoản

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # tất cả tài khoản Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # ẩn cảnh báo chỉ cho tài khoản ops
  telegram:
    heartbeat:
      showOk: true

Các pattern phổ biến

Mục đích	Config
Hành vi mặc định (OK im lặng, cảnh báo bật)	(không cần config)
Hoàn toàn im lặng (không tin nhắn, không indicator)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
Chỉ indicator (không tin nhắn)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
OK chỉ trong một Channel	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (tùy chọn)

Nếu file HEARTBEAT.md tồn tại trong Workspace, prompt mặc định sẽ bảo Agent đọc nó. Coi nó như “checklist heartbeat” của các bạn: nhỏ gọn, ổn định, và an toàn để đưa vào mỗi 30 phút.

Nếu HEARTBEAT.md tồn tại nhưng thực tế trống (chỉ có dòng trống và markdown header như # Heading), OpenClaw bỏ qua lượt chạy Heartbeat để tiết kiệm API call. Nếu file không tồn tại, Heartbeat vẫn chạy và model tự quyết định làm gì.

Giữ nó nhỏ gọn (checklist ngắn hoặc nhắc nhở) để tránh prompt quá dài.

Ví dụ 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 có thể cập nhật HEARTBEAT.md không?

Có — nếu các bạn yêu cầu.

HEARTBEAT.md chỉ là file bình thường trong Workspace của Agent, nên các bạn có thể bảo Agent (trong chat thường) kiểu như:

“Update HEARTBEAT.md để thêm kiểm tra lịch hàng ngày.”
“Viết lại HEARTBEAT.md cho ngắn hơn và tập trung vào theo dõi inbox.”

Nếu muốn điều này xảy ra chủ động, các bạn cũng có thể thêm dòng rõ ràng trong Heartbeat prompt như: “If the checklist becomes stale, update HEARTBEAT.md with a better one.”

Lưu ý an toàn: đừng đặt thông tin nhạy cảm (API key, số điện thoại, token riêng) vào HEARTBEAT.md — nó sẽ trở thành phần của prompt context.

Đánh thức thủ công (on-demand)

Các bạn có thể đưa system event vào hàng đợi và kích hoạt Heartbeat ngay lập tức bằng:

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

Nếu nhiều Agent có config heartbeat, đánh thức thủ công sẽ chạy Heartbeat của từng Agent đó ngay lập tức.

Dùng --mode next-heartbeat để đợi tick theo lịch tiếp theo.

Gửi Reasoning (tùy chọn)

Mặc định, Heartbeat chỉ gửi payload “answer” cuối cùng.

Nếu muốn minh bạch hơn, hãy bật:

agents.defaults.heartbeat.includeReasoning: true

Khi bật, Heartbeat cũng sẽ gửi tin nhắn riêng có prefix Reasoning: (giống /reasoning on). Điều này hữu ích khi Agent đang quản lý nhiều Session/codex và các bạn muốn biết tại sao nó quyết định ping — nhưng nó cũng có thể leak nhiều chi tiết nội bộ hơn mong muốn. Nên giữ tắt trong group chat.

Nhận thức về chi phí

Heartbeat chạy các lượt Agent đầy đủ. Khoảng thời gian ngắn hơn tiêu tốn nhiều token hơn. Giữ HEARTBEAT.md nhỏ gọn và cân nhắc dùng model rẻ hơn hoặc target: "none" nếu các bạn chỉ muốn cập nhật trạng thái nội bộ.