Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Heartbeat vs cron? Lihat Automasi untuk panduan kapan menggunakan masing-masing.
Mulai cepat (pemula)
Pilih irama
Biarkan heartbeat tetap aktif (default adalah
30m, atau 1h untuk autentikasi OAuth/token Anthropic, termasuk penggunaan ulang Claude CLI) atau tetapkan irama Anda sendiri.Tambahkan HEARTBEAT.md (opsional)
Buat checklist kecil
HEARTBEAT.md atau blok tasks: di ruang kerja agen.Tentukan ke mana pesan heartbeat harus dikirim
target: "none" adalah default; setel target: "last" untuk merutekan ke kontak terakhir.Penyesuaian opsional
- Aktifkan pengiriman penalaran heartbeat untuk transparansi.
- Gunakan konteks bootstrap ringan jika proses heartbeat hanya membutuhkan
HEARTBEAT.md. - Aktifkan sesi terisolasi untuk menghindari pengiriman riwayat percakapan penuh pada setiap heartbeat.
- Batasi heartbeat ke jam aktif (waktu lokal).
Default
- Interval:
30m(atau1hketika autentikasi OAuth/token Anthropic adalah mode autentikasi yang terdeteksi, termasuk penggunaan ulang Claude CLI). Setelagents.defaults.heartbeat.everyatau per agenagents.list[].heartbeat.every; 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. - Prompt heartbeat dikirim apa adanya sebagai pesan pengguna. Prompt sistem menyertakan bagian “Heartbeat” hanya ketika heartbeat diaktifkan untuk agen default, dan proses ditandai secara internal.
- Ketika heartbeat dinonaktifkan dengan
0m, proses normal juga menghilangkanHEARTBEAT.mddari konteks bootstrap sehingga model tidak melihat instruksi khusus heartbeat. - Jam aktif (
heartbeat.activeHours) diperiksa dalam zona waktu yang dikonfigurasi. Di luar jendela tersebut, heartbeat dilewati hingga tick berikutnya di dalam jendela. - Heartbeat otomatis ditunda saat pekerjaan cron aktif atau mengantre. Setel
heartbeat.skipWhenBusy: trueuntuk juga menunda agen pada subagen berbasis kunci sesinya sendiri atau lane perintah bertingkat; agen saudara tidak lagi dijeda hanya karena agen lain memiliki pekerjaan subagen yang sedang berjalan.
Untuk apa prompt heartbeat digunakan
Prompt default sengaja dibuat luas:- Tugas latar belakang: “Pertimbangkan tugas yang belum selesai” mendorong agen untuk meninjau tindak lanjut (inbox, kalender, pengingat, pekerjaan antrean) dan memunculkan apa pun yang mendesak.
- Check-in manusia: “Sesekali cek manusia Anda pada siang hari” mendorong pesan ringan sesekali seperti “ada yang Anda butuhkan?”, tetapi menghindari spam malam hari dengan menggunakan zona waktu lokal yang Anda konfigurasikan (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. - Proses heartbeat yang mampu memakai tool dapat sebagai gantinya memanggil
heartbeat_responddengannotify: falseuntuk tanpa pembaruan terlihat, ataunotify: trueplusnotificationTextuntuk peringatan. Jika ada, respons tool terstruktur didahulukan atas fallback teks. - Selama proses 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 prioritas
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 kanal.channels.<channel>.heartbeatmenimpa default kanal.channels.<channel>.accounts.<id>.heartbeat(kanal multi-akun) menimpa pengaturan per kanal.
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 dalam zona waktu tertentu:Penyiapan 24/7
Jika Anda ingin heartbeat berjalan sepanjang hari, gunakan salah satu pola ini:- Hilangkan
activeHourssepenuhnya (tanpa batasan jendela waktu; ini adalah perilaku default). - Setel jendela sehari penuh:
activeHours: { start: "00:00", end: "24:00" }.
Contoh multi-akun
GunakanaccountId untuk menargetkan akun tertentu pada kanal multi-akun seperti Telegram:
Catatan field
Interval heartbeat (string durasi; unit default = menit).
Override model opsional untuk proses heartbeat (
provider/model).Ketika diaktifkan, juga kirim pesan
Reasoning: terpisah saat tersedia (bentuk yang sama seperti /reasoning on).Ketika true, proses 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". Secara drastis mengurangi biaya token per heartbeat. Gabungkan dengan lightContext: true untuk penghematan maksimum. Perutean pengiriman tetap menggunakan konteks sesi utama.Ketika true, proses heartbeat ditunda pada lane sibuk tambahan milik agen tersebut: subagen berbasis kunci sesinya 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 kanal eksternal yang terakhir digunakan.- kanal eksplisit: kanal atau id 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: hentikan pengiriman langsung/DM (reason=dm-blocked).Override penerima opsional (id khusus kanal, misalnya E.164 untuk WhatsApp atau id chat Telegram). Untuk topik/thread Telegram, gunakan
<chatId>:topic:<messageThreadId>.Id akun opsional untuk kanal multi-akun. Ketika
target: "last", id akun diterapkan pada kanal terakhir yang diselesaikan jika mendukung akun; jika tidak, id tersebut diabaikan. Jika id akun tidak cocok dengan akun yang dikonfigurasi untuk kanal yang diselesaikan, pengiriman dilewati.Mengganti isi prompt default (tidak digabungkan).
Jumlah karakter maksimum yang diizinkan setelah
HEARTBEAT_OK sebelum pengiriman.Jika true, menekan payload peringatan kesalahan alat selama heartbeat berjalan.
Membatasi heartbeat agar berjalan hanya dalam jendela waktu tertentu. 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 disetel, jika tidak kembali ke zona waktu sistem host. "local": selalu menggunakan zona waktu sistem host.- Identifier 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>), atauglobalketikasession.scope = "global". Setelsessionuntuk mengganti ke sesi kanal tertentu (Discord/WhatsApp/dll.). sessionhanya memengaruhi konteks proses; pengiriman dikendalikan olehtargetdanto.- Untuk mengirim ke kanal/penerima tertentu, setel
target+to. Dengantarget: "last", pengiriman menggunakan kanal eksternal terakhir untuk sesi tersebut. - Pengiriman heartbeat mengizinkan target langsung/DM secara default. Setel
directPolicy: "block"untuk menekan pengiriman ke target langsung sambil tetap menjalankan giliran heartbeat. - Jika antrean utama, lane sesi target, lane cron, atau pekerjaan cron aktif sedang sibuk, heartbeat dilewati dan dicoba lagi nanti.
- Jika
skipWhenBusy: true, subagen berbasis kunci sesi milik agen ini dan lane bersarang juga menunda heartbeat. Lane sibuk milik agen lain tidak menunda agen ini. - Jika
targettidak menghasilkan tujuan eksternal, proses tetap berjalan 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 stempel waktu tugas jatuh tempo, memulihkan stempel waktu idle sesi, dan menekan payload peringatan keluar.
- Jika target heartbeat yang diselesaikan mendukung pengetikan, OpenClaw menampilkan pengetikan saat heartbeat berjalan 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 aktif. Metadata heartbeat dapat memperbarui baris sesi, tetapi kedaluwarsa idle menggunakan
lastInteractionAtdari pesan pengguna/kanal nyata terakhir, dan kedaluwarsa harian menggunakansessionStartedAt. - UI Kontrol dan riwayat WebChat menyembunyikan prompt heartbeat dan pengakuan OK saja. Transkrip sesi yang mendasarinya masih dapat berisi giliran tersebut untuk audit/pemutaran ulang.
- Tugas latar belakang yang dilepas dapat mengantrekan peristiwa sistem dan membangunkan heartbeat ketika sesi utama harus segera memperhatikan sesuatu. Wake tersebut tidak membuat heartbeat menjalankan tugas latar belakang.
Kontrol visibilitas
Secara default, pengakuanHEARTBEAT_OK ditekan sementara konten peringatan dikirim. Anda dapat menyesuaikan ini per kanal atau per akun:
Fungsi tiap flag
showOk: mengirim pengakuanHEARTBEAT_OKketika model mengembalikan balasan OK saja.showAlerts: mengirim konten peringatan ketika model mengembalikan balasan non-OK.useIndicator: memancarkan peristiwa indikator untuk permukaan status UI.
Contoh per kanal 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 kanal | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md (opsional)
Jika fileHEARTBEAT.md ada di workspace, prompt default memberi tahu agen untuk membacanya. Anggap ini sebagai “daftar periksa heartbeat” Anda: kecil, stabil, dan aman untuk disertakan setiap 30 menit.
Pada proses normal, HEARTBEAT.md hanya disuntikkan ketika panduan heartbeat diaktifkan untuk agen default. Menonaktifkan cadence heartbeat dengan 0m atau menyetel includeSystemPromptSection: false menghilangkannya dari konteks bootstrap normal.
Jika HEARTBEAT.md ada tetapi secara efektif kosong (hanya baris kosong dan header markdown seperti # Heading), OpenClaw melewati proses heartbeat untuk menghemat panggilan API. Pelewatan itu dilaporkan sebagai reason=empty-heartbeat-file. Jika file tidak ada, heartbeat tetap berjalan dan model memutuskan apa yang harus dilakukan.
Jaga agar tetap kecil (daftar periksa atau pengingat singkat) untuk menghindari pembengkakan prompt.
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 terhadapinterval-nya sendiri. - Hanya tugas yang jatuh tempo 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 di
HEARTBEAT.mddipertahankan dan ditambahkan sebagai konteks tambahan setelah daftar tugas jatuh tempo. - Stempel waktu terakhir berjalan tugas disimpan dalam state sesi (
heartbeatTaskState), sehingga interval bertahan melewati restart normal. - Stempel waktu 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:
- “Perbarui
HEARTBEAT.mduntuk menambahkan pemeriksaan kalender harian.” - “Tulis ulang
HEARTBEAT.mdagar lebih singkat dan berfokus pada tindak lanjut inbox.”
Wake manual (sesuai permintaan)
Anda dapat mengantrekan peristiwa sistem dan memicu heartbeat langsung dengan:heartbeat yang dikonfigurasi, wake manual langsung menjalankan setiap heartbeat agen tersebut.
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
Reasoning: (bentuk yang sama seperti /reasoning on). Ini dapat berguna ketika agen mengelola beberapa sesi/codex dan Anda ingin melihat mengapa ia memutuskan untuk menghubungi Anda — tetapi ini juga dapat membocorkan lebih banyak detail internal daripada yang Anda inginkan. Sebaiknya tetap nonaktif di chat grup.
Kesadaran biaya
Heartbeat menjalankan giliran agen penuh. Interval yang lebih pendek menghabiskan lebih banyak token. Untuk mengurangi biaya:- Gunakan
isolatedSession: trueuntuk menghindari pengiriman riwayat percakapan penuh (~100K token turun menjadi ~2-5K per proses). - Gunakan
lightContext: trueuntuk membatasi file bootstrap hanya keHEARTBEAT.md. - Setel
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 jendela 32k, dan giliran sesi utama berikutnya melaporkan overflow konteks, reset model runtime sesi kembali ke model primer yang dikonfigurasi. Pesan reset OpenClaw menyebutkan ini ketika model runtime terakhir cocok denganheartbeat.model yang dikonfigurasi.
Heartbeat saat ini mempertahankan model runtime yang ada milik sesi bersama setelah proses selesai. Anda masih dapat menggunakan isolatedSession: true untuk menjalankan heartbeat dalam sesi baru, menggabungkannya dengan lightContext: true untuk prompt terkecil, atau memilih model heartbeat dengan jendela konteks yang cukup besar untuk sesi bersama.
Terkait
- Otomasi — semua mekanisme otomasi sekilas
- Tugas Latar Belakang — bagaimana pekerjaan yang dilepas dilacak
- Zona Waktu — bagaimana zona waktu memengaruhi penjadwalan heartbeat
- Pemecahan Masalah — men-debug masalah otomasi