Heartbeat atau Cron? Lihat Automation untuk panduan kapan menggunakan masing-masing.
Mulai cepat (pemula)
Pick a cadence
Biarkan heartbeat aktif (default-nya
30m, atau 1h untuk autentikasi Anthropic OAuth/token, termasuk penggunaan ulang Claude CLI) atau tetapkan irama Anda sendiri.Add HEARTBEAT.md (optional)
Buat daftar periksa kecil
HEARTBEAT.md atau blok tasks: di ruang kerja agen.Decide where heartbeat messages should go
target: "none" adalah default; setel target: "last" untuk merutekan ke kontak terakhir.Optional tuning
- Aktifkan pengiriman penalaran heartbeat untuk transparansi.
- Gunakan konteks bootstrap ringan jika jalankan heartbeat hanya memerlukan
HEARTBEAT.md. - Aktifkan sesi terisolasi untuk menghindari pengiriman seluruh riwayat percakapan pada setiap heartbeat.
- Batasi heartbeat ke jam aktif (waktu lokal).
Default
- Interval:
30m(atau1hketika autentikasi Anthropic OAuth/token adalah mode autentikasi yang terdeteksi, termasuk penggunaan ulang Claude CLI). Setelagents.defaults.heartbeat.everyatauagents.list[].heartbeat.everyper agen; gunakan0muntuk 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.timeoutSecondsjika disetel. Jika tidak, giliran tersebut menggunakan irama heartbeat yang dibatasi hingga 600 detik. Setelagents.defaults.heartbeat.timeoutSecondsatauagents.list[].heartbeat.timeoutSecondsper 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 menghilangkanHEARTBEAT.mddari 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: trueuntuk 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).
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_responddengannotify: falseuntuk tanpa pembaruan yang terlihat, ataunotify: trueplusnotificationTextuntuk peringatan. Jika ada, respons alat terstruktur lebih diutamakan daripada fallback teks. - Selama jalankan heartbeat, OpenClaw memperlakukan
HEARTBEAT_OKsebagai ack ketika muncul di awal atau akhir balasan. Token tersebut dihapus dan balasan dibuang jika konten yang tersisa ≤ackMaxChars(default: 300). - Jika
HEARTBEAT_OKmuncul di tengah balasan, itu tidak diperlakukan secara khusus. - Untuk peringatan, jangan sertakan
HEARTBEAT_OK; kembalikan hanya teks peringatan.
HEARTBEAT_OK yang terselip di awal/akhir pesan dihapus dan dicatat; pesan yang hanya berisi HEARTBEAT_OK dibuang.
Konfigurasi
Cakupan dan presedensi
agents.defaults.heartbeatmenetapkan perilaku heartbeat global.agents.list[].heartbeatdigabungkan di atasnya; jika ada agen yang memiliki blokheartbeat, hanya agen tersebut yang menjalankan heartbeat.channels.defaults.heartbeatmenetapkan default visibilitas untuk semua channel.channels.<channel>.heartbeatmenimpa default channel.channels.<channel>.accounts.<id>.heartbeat(channel multi-akun) menimpa pengaturan per channel.
Heartbeat per agen
Jika ada entriagents.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.
Contoh jam aktif
Batasi heartbeat ke jam kerja di zona waktu tertentu:Penyiapan 24/7
Jika Anda ingin heartbeat berjalan sepanjang hari, gunakan salah satu pola berikut:- Hilangkan
activeHourssepenuhnya (tanpa batasan rentang waktu; ini adalah perilaku default). - Setel rentang sehari penuh:
activeHours: { start: "00:00", end: "24:00" }.
Contoh multi-akun
GunakanaccountId untuk menargetkan akun tertentu pada channel multi-akun seperti Telegram:
Catatan field
Interval Heartbeat (string durasi; unit default = menit).
Override model opsional untuk jalankan heartbeat (
provider/model).Ketika diaktifkan, juga kirim pesan
Thinking terpisah saat tersedia (bentuk yang sama seperti /reasoning on).Ketika true, jalankan heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan
HEARTBEAT.md dari file bootstrap ruang kerja.Ketika true, setiap heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Menggunakan pola isolasi yang sama seperti Cron
sessionTarget: "isolated". Mengurangi biaya token per heartbeat secara drastis. Gabungkan dengan lightContext: true untuk penghematan maksimal. Perutean pengiriman tetap menggunakan konteks sesi utama.Ketika true, jalankan heartbeat ditunda pada lane sibuk tambahan agen tersebut: subagen berbasis kunci sesi miliknya sendiri atau pekerjaan perintah bertingkat. Lane Cron selalu menunda heartbeat, bahkan tanpa flag ini, sehingga host model lokal tidak menjalankan prompt Cron dan heartbeat pada saat yang sama.
last: kirim ke channel eksternal yang terakhir digunakan.- channel eksplisit: id channel atau Plugin apa pun yang dikonfigurasi, misalnya
discord,matrix,telegram, atauwhatsapp. none(default): jalankan heartbeat tetapi jangan kirim secara eksternal.
Mengontrol perilaku pengiriman langsung/DM.
allow: izinkan pengiriman heartbeat langsung/DM. block: tekan pengiriman langsung/DM (reason=dm-blocked).Override penerima opsional (id khusus channel, misalnya E.164 untuk WhatsApp atau id chat Telegram). Untuk topik/thread Telegram, gunakan
<chatId>:topic:<messageThreadId>.Id akun opsional untuk channel multi-akun. Saat
target: "last", id akun berlaku pada channel terakhir yang terselesaikan jika channel tersebut mendukung akun; jika tidak, id akun diabaikan. Jika id akun tidak cocok dengan akun yang dikonfigurasi untuk channel yang terselesaikan, pengiriman dilewati.Mengganti isi prompt default (tidak digabungkan).
Karakter maksimum yang diizinkan setelah
HEARTBEAT_OK sebelum pengiriman.Jika true, menekan payload peringatan kesalahan tool selama proses heartbeat.
Detik maksimum yang diizinkan untuk satu giliran agen heartbeat sebelum dibatalkan. Biarkan tidak diatur untuk menggunakan
agents.defaults.timeoutSeconds jika diatur, jika tidak menggunakan kadensi heartbeat yang dibatasi pada 600 detik.Membatasi proses heartbeat ke jendela waktu. Objek dengan
start (HH:MM, inklusif; gunakan 00:00 untuk awal hari), end (HH:MM eksklusif; 24:00 diizinkan untuk akhir hari), dan timezone opsional.- Dihilangkan atau
"user": menggunakanagents.defaults.userTimezoneAnda jika diatur, jika tidak kembali ke zona waktu sistem host. "local": selalu menggunakan zona waktu sistem host.- Pengidentifikasi IANA apa pun (mis.
America/New_York): digunakan langsung; jika tidak valid, kembali ke perilaku"user"di atas. startdanendtidak boleh sama untuk jendela aktif; nilai yang sama diperlakukan sebagai lebar nol (selalu di luar jendela).- Di luar jendela aktif, heartbeat dilewati hingga tick berikutnya di dalam jendela.
Perilaku pengiriman
Perutean sesi dan target
Perutean sesi dan target
- Heartbeat berjalan di sesi utama agen secara default (
agent:<id>:<mainKey>), atauglobalsaatsession.scope = "global". Atursessionuntuk mengganti ke sesi channel tertentu (Discord/WhatsApp/dll.). sessionhanya memengaruhi konteks proses; pengiriman dikendalikan olehtargetdanto.- Untuk mengirim ke channel/penerima tertentu, atur
target+to. Dengantarget: "last", pengiriman menggunakan channel eksternal terakhir untuk sesi tersebut. - Pengiriman heartbeat mengizinkan target langsung/DM secara default. Atur
directPolicy: "block"untuk menekan pengiriman target langsung sambil tetap menjalankan giliran heartbeat. - Jika antrean utama, lane sesi target, lane cron, atau job cron aktif sedang sibuk, heartbeat dilewati dan dicoba lagi nanti.
- Jika
skipWhenBusy: true, subagen berbasis kunci sesi agen ini dan lane bertingkat juga menunda proses heartbeat. Lane sibuk milik agen lain tidak menunda agen ini. - Jika
targettidak terselesaikan ke tujuan eksternal apa pun, proses tetap terjadi tetapi tidak ada pesan keluar yang dikirim.
Visibilitas dan perilaku lewati
Visibilitas dan perilaku lewati
- Jika
showOk,showAlerts, danuseIndicatorsemuanya dinonaktifkan, proses dilewati sejak awal sebagaireason=alerts-disabled. - Jika hanya pengiriman peringatan yang dinonaktifkan, OpenClaw masih dapat menjalankan heartbeat, memperbarui timestamp tugas jatuh tempo, memulihkan timestamp idle sesi, dan menekan payload peringatan keluar.
- Jika target heartbeat yang terselesaikan mendukung pengetikan, OpenClaw menampilkan pengetikan saat proses heartbeat aktif. Ini menggunakan target yang sama dengan tujuan output chat heartbeat, dan dinonaktifkan oleh
typingMode: "never".
Siklus hidup sesi dan audit
Siklus hidup sesi dan audit
- Balasan khusus heartbeat tidak menjaga sesi tetap hidup. Metadata heartbeat dapat memperbarui baris sesi, tetapi kedaluwarsa idle menggunakan
lastInteractionAtdari pesan pengguna/channel nyata terakhir, dan kedaluwarsa harian menggunakansessionStartedAt. - Riwayat Control UI dan WebChat menyembunyikan prompt heartbeat dan acknowledgement khusus OK. Transkrip sesi yang mendasarinya tetap dapat berisi giliran tersebut untuk audit/replay.
- Tugas latar belakang yang dilepaskan dapat mengantrekan event sistem dan membangunkan heartbeat saat sesi utama perlu segera mengetahui sesuatu. Wake tersebut tidak membuat proses heartbeat menjadi tugas latar belakang.
Kontrol visibilitas
Secara default, acknowledgementHEARTBEAT_OK ditekan sementara konten peringatan dikirim. Anda dapat menyesuaikan ini per channel atau per akun:
Apa fungsi setiap flag
showOk: mengirim acknowledgementHEARTBEAT_OKsaat model mengembalikan balasan khusus OK.showAlerts: mengirim konten peringatan saat model mengembalikan balasan non-OK.useIndicator: memancarkan event indikator untuk permukaan status UI.
Contoh per-channel vs per-akun
Pola umum
| Tujuan | Konfigurasi |
|---|---|
| Perilaku default (OK senyap, peringatan aktif) | (tidak perlu konfigurasi) |
| Sepenuhnya senyap (tanpa pesan, tanpa indikator) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false } |
| Hanya indikator (tanpa pesan) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true } |
| OK hanya di satu channel | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md (opsional)
Jika fileHEARTBEAT.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:
Blok tasks:
HEARTBEAT.md juga mendukung blok tasks: terstruktur kecil untuk pemeriksaan berbasis interval di dalam heartbeat itu sendiri.
Contoh:
Perilaku
Perilaku
- OpenClaw mengurai blok
tasks:dan memeriksa setiap tugas terhadapintervalmiliknya. - Hanya tugas yang jatuh tempo yang disertakan dalam prompt heartbeat untuk tick tersebut.
- Jika tidak ada tugas yang jatuh tempo, heartbeat dilewati sepenuhnya (
reason=no-tasks-due) untuk menghindari panggilan model yang sia-sia. - Konten non-tugas dalam
HEARTBEAT.mddipertahankan dan ditambahkan sebagai konteks tambahan setelah daftar tugas jatuh tempo. - Timestamp terakhir dijalankan tugas disimpan dalam state sesi (
heartbeatTaskState), sehingga interval bertahan melewati restart normal. - Timestamp tugas hanya dimajukan setelah proses heartbeat menyelesaikan jalur balasan normalnya. Proses
empty-heartbeat-file/no-tasks-dueyang dilewati tidak menandai tugas sebagai selesai.
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.mdto add a daily calendar check.” - “Rewrite
HEARTBEAT.mdso it’s shorter and focused on inbox follow-ups.”
Wake manual (sesuai permintaan)
Anda dapat mengantrekan event sistem dan memicu heartbeat segera dengan: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
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: trueagar tidak mengirim riwayat percakapan penuh (~100K token turun menjadi ~2-5K per proses). - Gunakan
lightContext: trueuntuk membatasi file bootstrap hanya keHEARTBEAT.md. - Atur
modelyang lebih murah (mis.ollama/llama3.2:1b). - Jaga
HEARTBEAT.mdtetap 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 denganheartbeat.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