Heartbeat

Heartbeat menjalankan giliran agen berkala dalam sesi utama agar model dapat memunculkan apa pun yang perlu diperhatikan tanpa membanjiri Anda.

Heartbeat adalah giliran sesi utama terjadwal — ini tidak membuat catatan tugas latar belakang. Catatan tugas digunakan untuk pekerjaan terpisah (jalankan ACP, subagen, pekerjaan Cron terisolasi).

Pemecahan masalah: Tugas Terjadwal

Mulai cepat (pemula)

Contoh konfigurasi:

{  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)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` message too      },    },  },}

Default

• Interval: 30m (atau 1h ketika autentikasi Anthropic OAuth/token adalah mode autentikasi yang terdeteksi, termasuk penggunaan ulang Claude CLI). Setel agents.defaults.heartbeat.every atau agents.list[].heartbeat.every per agen; gunakan 0m untuk menonaktifkan.
• Isi prompt (dapat dikonfigurasi melalui 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.
• Timeout: giliran heartbeat yang tidak disetel menggunakan agents.defaults.timeoutSeconds jika disetel. Jika tidak, giliran tersebut menggunakan irama heartbeat yang dibatasi hingga 600 detik. Setel agents.defaults.heartbeat.timeoutSeconds atau agents.list[].heartbeat.timeoutSeconds per agen untuk pekerjaan heartbeat yang lebih lama.
• Prompt heartbeat dikirim apa adanya sebagai pesan pengguna. Prompt sistem menyertakan bagian "Heartbeat" hanya ketika heartbeat diaktifkan untuk agen default, dan jalankan tersebut ditandai secara internal.
• Ketika heartbeat dinonaktifkan dengan 0m, jalankan normal juga menghilangkan HEARTBEAT.md dari konteks bootstrap sehingga model tidak melihat instruksi khusus heartbeat.
• Jam aktif (heartbeat.activeHours) diperiksa di zona waktu yang dikonfigurasi. Di luar rentang tersebut, heartbeat dilewati sampai tick berikutnya di dalam rentang.
• Heartbeat otomatis ditunda saat pekerjaan Cron aktif atau mengantre. Setel heartbeat.skipWhenBusy: true untuk juga menunda agen pada subagen berbasis kunci sesi miliknya sendiri atau lane perintah bertingkat; agen saudara tidak lagi berhenti hanya karena agen lain memiliki pekerjaan subagen yang sedang berjalan.

Untuk apa prompt heartbeat digunakan

Prompt default sengaja dibuat luas:

• Tugas latar belakang: "Consider outstanding tasks" mendorong agen untuk meninjau tindak lanjut (kotak masuk, kalender, pengingat, pekerjaan antrean) dan memunculkan apa pun yang mendesak.
• Sapaan ke manusia: "Checkup sometimes on your human during day time" mendorong pesan ringan sesekali "ada yang Anda butuhkan?", tetapi menghindari spam malam hari dengan menggunakan zona waktu lokal yang Anda konfigurasi (lihat Zona Waktu).

Heartbeat dapat bereaksi terhadap tugas latar belakang yang selesai, tetapi jalankan heartbeat itu sendiri tidak membuat catatan tugas.

Jika Anda ingin heartbeat melakukan sesuatu yang sangat spesifik (misalnya "check Gmail PubSub stats" atau "verify gateway health"), setel agents.defaults.heartbeat.prompt (atau agents.list[].heartbeat.prompt) ke isi kustom (dikirim apa adanya).

Kontrak respons

• Jika tidak ada yang perlu diperhatikan, balas dengan HEARTBEAT_OK.
• Jalankan heartbeat yang mampu menggunakan alat dapat sebagai gantinya memanggil heartbeat_respond dengan notify: false untuk tanpa pembaruan yang terlihat, atau notify: true plus notificationText untuk peringatan. Jika ada, respons alat terstruktur lebih diutamakan daripada fallback teks.
• Selama jalankan heartbeat, OpenClaw memperlakukan HEARTBEAT_OK sebagai ack ketika muncul di awal atau akhir balasan. Token tersebut dihapus dan balasan dibuang jika konten yang tersisa ≤ ackMaxChars (default: 300).
• Jika HEARTBEAT_OK muncul di tengah balasan, itu tidak diperlakukan secara khusus.
• Untuk peringatan, jangan sertakan HEARTBEAT_OK; kembalikan hanya teks peringatan.

Di luar heartbeat, HEARTBEAT_OK yang terselip di awal/akhir pesan dihapus dan dicatat; pesan yang hanya berisi HEARTBEAT_OK dibuang.

Konfigurasi

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Thinking 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)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        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      },    },  },}

Cakupan dan presedensi

• agents.defaults.heartbeat menetapkan perilaku heartbeat global.
• agents.list[].heartbeat digabungkan di atasnya; jika ada agen yang memiliki blok heartbeat, hanya agen tersebut yang menjalankan heartbeat.
• channels.defaults.heartbeat menetapkan default visibilitas untuk semua channel.
• channels.<channel>.heartbeat menimpa default channel.
• channels.<channel>.accounts.<id>.heartbeat (channel multi-akun) menimpa pengaturan per channel.

Heartbeat per agen

Jika ada entri agents.list[] yang menyertakan blok heartbeat, hanya agen tersebut yang menjalankan heartbeat. Blok per agen digabungkan di atas agents.defaults.heartbeat (sehingga Anda dapat menetapkan default bersama sekali dan menimpanya per agen).

Contoh: dua agen, hanya agen kedua yang menjalankan 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",          timeoutSeconds: 45,          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.",        },      },    ],  },}

Contoh jam aktif

Batasi heartbeat ke jam kerja di zona waktu tertentu:

{  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        },      },    },  },}

Di luar rentang ini (sebelum 09.00 atau setelah 22.00 Eastern), heartbeat dilewati. Tick terjadwal berikutnya di dalam rentang akan berjalan normal.

Penyiapan 24/7

Jika Anda ingin heartbeat berjalan sepanjang hari, gunakan salah satu pola berikut:

• Hilangkan activeHours sepenuhnya (tanpa batasan rentang waktu; ini adalah perilaku default).
• Setel rentang sehari penuh: activeHours: { start: "00:00", end: "24:00" }.

Contoh multi-akun

Gunakan accountId untuk menargetkan akun tertentu pada channel multi-akun seperti Telegram:

{  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" },      },    },  },}

Catatan field

Perilaku pengiriman

Kontrol visibilitas

Secara default, acknowledgement HEARTBEAT_OK ditekan sementara konten peringatan dikirim. Anda dapat menyesuaikan ini per channel atau per akun:

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

Prioritas: per-akun → per-channel → default channel → default bawaan.

Apa fungsi setiap flag

• showOk: mengirim acknowledgement HEARTBEAT_OK saat model mengembalikan balasan khusus OK.
• showAlerts: mengirim konten peringatan saat model mengembalikan balasan non-OK.
• useIndicator: memancarkan event indikator untuk permukaan status UI.

Jika ketiganya false, OpenClaw melewati proses heartbeat sepenuhnya (tidak ada panggilan model).

Contoh per-channel vs per-akun

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

Pola umum

HEARTBEAT.md (opsional)

Jika file HEARTBEAT.md ada di workspace, prompt default memberi tahu agen untuk membacanya. Anggap ini sebagai "checklist heartbeat" Anda: kecil, stabil, dan aman untuk dipertimbangkan setiap 30 menit.

Pada proses normal, HEARTBEAT.md hanya disisipkan saat panduan heartbeat diaktifkan untuk agen default. Menonaktifkan kadensi heartbeat dengan 0m atau mengatur includeSystemPromptSection: false menghilangkannya dari konteks bootstrap normal.

Pada harness Codex native, konten HEARTBEAT.md tidak disisipkan ke dalam giliran. Jika file ada dan memiliki konten non-whitespace, instruksi mode kolaborasi heartbeat mengarahkan Codex ke file tersebut dan memintanya membaca sebelum melanjutkan.

Jika HEARTBEAT.md ada tetapi secara efektif kosong (hanya baris kosong, komentar Markdown/HTML, heading Markdown seperti # Heading, penanda fence, atau stub checklist kosong), OpenClaw melewati proses heartbeat untuk menghemat panggilan API. Lewatan tersebut dilaporkan sebagai reason=empty-heartbeat-file. Jika file tidak ada, heartbeat tetap berjalan dan model memutuskan apa yang harus dilakukan.

Jaga tetap kecil (checklist singkat atau pengingat) untuk menghindari prompt yang membengkak.

Contoh 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.

Blok tasks:

HEARTBEAT.md juga mendukung blok tasks: terstruktur kecil untuk pemeriksaan berbasis interval di dalam heartbeat itu sendiri.

Contoh:

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

Mode tugas berguna saat Anda ingin satu file heartbeat memuat beberapa pemeriksaan berkala tanpa membayar semuanya pada setiap tick.

Bisakah agen memperbarui HEARTBEAT.md?

Ya — jika Anda memintanya.

HEARTBEAT.md hanyalah file normal di workspace agen, jadi Anda dapat memberi tahu agen (dalam chat normal) sesuatu seperti:

• "Update HEARTBEAT.md to add a daily calendar check."
• "Rewrite HEARTBEAT.md so it's shorter and focused on inbox follow-ups."

Jika Anda ingin ini terjadi secara proaktif, Anda juga dapat menyertakan baris eksplisit dalam prompt heartbeat Anda seperti: "If the checklist becomes stale, update HEARTBEAT.md with a better one."

Wake manual (sesuai permintaan)

Anda dapat mengantrekan event sistem dan memicu heartbeat segera dengan:

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

Jika beberapa agen memiliki heartbeat yang dikonfigurasi, wake manual menjalankan masing-masing heartbeat agen tersebut segera.

Gunakan --mode next-heartbeat untuk menunggu tick terjadwal berikutnya.

Pengiriman reasoning (opsional)

Secara default, heartbeat hanya mengirim payload "jawaban" akhir.

Jika Anda menginginkan transparansi, aktifkan:

• agents.defaults.heartbeat.includeReasoning: true

Saat diaktifkan, heartbeat juga akan mengirim pesan terpisah yang diawali Thinking (bentuk yang sama seperti /reasoning on). Ini dapat berguna saat agen mengelola beberapa sesi/codex dan Anda ingin melihat mengapa agen memutuskan untuk menghubungi Anda — tetapi ini juga dapat membocorkan lebih banyak detail internal daripada yang Anda inginkan. Sebaiknya tetap matikan di chat grup.

Kesadaran biaya

Heartbeat menjalankan giliran agen penuh. Interval yang lebih pendek menghabiskan lebih banyak token. Untuk mengurangi biaya:

• Gunakan isolatedSession: true agar tidak mengirim riwayat percakapan penuh (~100K token turun menjadi ~2-5K per proses).
• Gunakan lightContext: true untuk membatasi file bootstrap hanya ke HEARTBEAT.md.
• Atur model yang lebih murah (mis. ollama/llama3.2:1b).
• Jaga HEARTBEAT.md tetap kecil.
• Gunakan target: "none" jika Anda hanya menginginkan pembaruan state internal.

Overflow konteks setelah heartbeat

Jika heartbeat sebelumnya meninggalkan sesi yang ada pada model lokal yang lebih kecil, misalnya model Ollama dengan window 32k, dan giliran sesi utama berikutnya melaporkan overflow konteks, reset model runtime sesi kembali ke model utama yang dikonfigurasi. Pesan reset OpenClaw menyoroti ini saat model runtime terakhir cocok dengan heartbeat.model yang dikonfigurasi.

Heartbeat saat ini mempertahankan model runtime sesi bersama yang sudah ada setelah proses selesai. Anda tetap dapat menggunakan isolatedSession: true untuk menjalankan heartbeat dalam sesi baru, menggabungkannya dengan lightContext: true untuk prompt terkecil, atau memilih model heartbeat dengan window konteks yang cukup besar untuk sesi bersama.

Terkait

• Otomatisasi — semua mekanisme otomatisasi secara sekilas
• Tugas Latar Belakang — bagaimana pekerjaan terpisah dilacak
• Zona Waktu — bagaimana zona waktu memengaruhi penjadwalan Heartbeat
• Pemecahan Masalah — men-debug masalah otomatisasi