​

Heartbeat (Gateway)

Heartbeat vs Cron? Lihat Otomatisasi & Tugas untuk panduan kapan menggunakan masing-masing.

​

Memulai cepat (pemula)

1. Biarkan heartbeat tetap aktif (default adalah 30m, atau 1h untuk auth OAuth/token Anthropic, termasuk penggunaan ulang Claude CLI) atau atur cadence Anda sendiri.
2. Buat checklist HEARTBEAT.md kecil atau blok tasks: di workspace agent (opsional tetapi disarankan).
3. Tentukan ke mana pesan heartbeat harus dikirim (target: "none" adalah default; atur target: "last" untuk merutekan ke kontak terakhir).
4. Opsional: aktifkan pengiriman reasoning heartbeat untuk transparansi.
5. Opsional: gunakan konteks bootstrap ringan jika run heartbeat hanya memerlukan HEARTBEAT.md.
6. Opsional: aktifkan sesi terisolasi agar riwayat percakapan penuh tidak dikirim di setiap heartbeat.
7. Opsional: batasi heartbeat ke jam aktif (waktu lokal).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // pengiriman eksplisit ke kontak terakhir (default adalah "none")
        directPolicy: "allow", // default: izinkan target langsung/DM; atur "block" untuk menekan
        lightContext: true, // opsional: hanya menyuntikkan HEARTBEAT.md dari file bootstrap
        isolatedSession: true, // opsional: sesi baru di setiap run (tanpa riwayat percakapan)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // opsional: kirim juga pesan `Reasoning:` terpisah
      },
    },
  },
}

​

Default

• Interval: 30m (atau 1h ketika auth OAuth/token Anthropic adalah mode auth yang terdeteksi, termasuk penggunaan ulang Claude CLI). Atur agents.defaults.heartbeat.every atau agents.list[].heartbeat.every; 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.
• Prompt heartbeat dikirim apa adanya sebagai pesan pengguna. Prompt sistem menyertakan bagian “Heartbeat” dan run ditandai secara internal.
• Jam aktif (heartbeat.activeHours) diperiksa dalam zona waktu yang dikonfigurasi. Di luar jendela itu, heartbeat dilewati hingga tick berikutnya di dalam jendela.

​

Untuk apa prompt heartbeat digunakan

• Tugas latar belakang: “Consider outstanding tasks” mendorong agent untuk meninjau tindak lanjut (inbox, kalender, pengingat, pekerjaan yang tertunda) dan menampilkan hal mendesak.
• Check-in manusia: “Checkup sometimes on your human during day time” mendorong pesan ringan sesekali seperti “ada yang Anda perlukan?”, tetapi menghindari spam malam hari dengan menggunakan zona waktu lokal yang Anda konfigurasi (lihat /concepts/timezone).

​

Kontrak respons

• Jika tidak ada yang perlu diperhatikan, balas dengan HEARTBEAT_OK.
• Selama run heartbeat, OpenClaw memperlakukan HEARTBEAT_OK sebagai ack ketika muncul di awal atau akhir balasan. Token tersebut dihapus dan balasannya dibuang jika sisa kontennya ≤ ackMaxChars (default: 300).
• Jika HEARTBEAT_OK muncul di tengah balasan, itu tidak diperlakukan secara khusus.
• Untuk peringatan, jangan sertakan HEARTBEAT_OK; kembalikan hanya teks peringatannya.

​

Config

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m menonaktifkan)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (kirim pesan Reasoning: terpisah saat tersedia)
        lightContext: false, // default: false; true hanya menyimpan HEARTBEAT.md dari file bootstrap workspace
        isolatedSession: false, // default: false; true menjalankan setiap heartbeat dalam sesi baru (tanpa riwayat percakapan)
        target: "last", // default: none | opsi: last | none | <id channel> (inti atau plugin, mis. "bluebubbles")
        to: "+15551234567", // override spesifik channel opsional
        accountId: "ops-bot", // id channel multi-akun opsional
        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, // jumlah karakter maksimum yang diizinkan setelah HEARTBEAT_OK
      },
    },
  },
}

​

Cakupan dan prioritas

• agents.defaults.heartbeat menetapkan perilaku heartbeat global.
• agents.list[].heartbeat digabungkan di atasnya; jika ada agent yang memiliki blok heartbeat, hanya agent-agent 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-agent

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // pengiriman eksplisit ke kontak terakhir (default adalah "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.",
        },
      },
    ],
  },
}

​

Contoh jam aktif

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // pengiriman eksplisit ke kontak terakhir (default adalah "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // opsional; menggunakan userTimezone Anda jika diatur, jika tidak zona waktu host
        },
      },
    },
  },
}

​

Penyiapan 24/7

• Hilangkan activeHours sepenuhnya (tanpa pembatasan jendela waktu; ini perilaku default).
• Atur jendela sehari penuh: activeHours: { start: "00:00", end: "24:00" }.

​

Contoh multi-akun

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // opsional: rute ke topik/thread tertentu
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Catatan field

• every: interval heartbeat (string durasi; unit default = menit).
• model: override model opsional untuk run heartbeat (provider/model).
• includeReasoning: saat diaktifkan, juga mengirim pesan Reasoning: terpisah saat tersedia (bentuk yang sama seperti /reasoning on).
• lightContext: saat true, run heartbeat menggunakan konteks bootstrap ringan dan hanya menyimpan HEARTBEAT.md dari file bootstrap workspace.
• isolatedSession: saat 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 maksimal. Routing pengiriman tetap menggunakan konteks sesi utama.
• session: kunci sesi opsional untuk run heartbeat.
  • main (default): sesi utama agent.
  • Kunci sesi eksplisit (salin dari openclaw sessions --json atau CLI sesi).
  • Format kunci sesi: lihat Sesi dan Grup.
• target:
  • last: kirim ke channel eksternal terakhir yang digunakan.
  • channel eksplisit: channel atau id plugin apa pun yang dikonfigurasi, misalnya discord, matrix, telegram, atau whatsapp.
  • none (default): jalankan heartbeat tetapi jangan kirim ke luar.
• directPolicy: mengontrol perilaku pengiriman langsung/DM:
  • allow (default): izinkan pengiriman heartbeat langsung/DM.
  • block: tekan pengiriman target langsung/DM (reason=dm-blocked).
• to: override penerima opsional (id spesifik channel, misalnya E.164 untuk WhatsApp atau id chat Telegram). Untuk topik/thread Telegram, gunakan <chatId>:topic:<messageThreadId>.
• accountId: id akun opsional untuk channel multi-akun. Saat target: "last", id akun berlaku untuk channel terakhir yang teresolusikan jika mendukung akun; jika tidak, diabaikan. Jika id akun tidak cocok dengan akun yang dikonfigurasi untuk channel yang teresolusikan, pengiriman dilewati.
• prompt: menimpa isi prompt default (tidak digabungkan).
• ackMaxChars: jumlah karakter maksimum yang diizinkan setelah HEARTBEAT_OK sebelum pengiriman.
• suppressToolErrorWarnings: saat true, menekan payload peringatan error tool selama run heartbeat.
• activeHours: membatasi run 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": menggunakan agents.defaults.userTimezone Anda jika diatur, jika tidak fallback 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, fallback ke perilaku "user" di atas.
  • start dan end tidak 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

• Heartbeat secara default berjalan di sesi utama agent (agent:<id>:<mainKey>), atau global ketika session.scope = "global". Atur session untuk menimpa ke sesi channel tertentu (Discord/WhatsApp/dll.).
• session hanya memengaruhi konteks run; pengiriman dikendalikan oleh target dan to.
• Untuk mengirim ke channel/penerima tertentu, atur target + to. Dengan target: "last", pengiriman menggunakan channel eksternal terakhir untuk sesi itu.
• Pengiriman heartbeat secara default mengizinkan target langsung/DM. Atur directPolicy: "block" untuk menekan pengiriman target langsung sambil tetap menjalankan giliran heartbeat.
• Jika antrean utama sibuk, heartbeat dilewati dan dicoba lagi nanti.
• Jika target tidak teresolusikan ke tujuan eksternal mana pun, run tetap terjadi tetapi tidak ada pesan outbound yang dikirim.
• Jika showOk, showAlerts, dan useIndicator semuanya dinonaktifkan, run dilewati dari awal sebagai reason=alerts-disabled.
• Jika hanya pengiriman alert yang dinonaktifkan, OpenClaw masih dapat menjalankan heartbeat, memperbarui timestamp tugas yang jatuh tempo, memulihkan timestamp idle sesi, dan menekan payload alert keluar.
• Balasan khusus heartbeat tidak membuat sesi tetap hidup; updatedAt terakhir dipulihkan agar kedaluwarsa idle tetap berperilaku normal.
• Tugas latar belakang yang terlepas dapat mengantrikan event sistem dan membangunkan heartbeat ketika sesi utama perlu segera menyadari sesuatu. Bangun ini tidak membuat run heartbeat menjadi tugas latar belakang.

​

Kontrol visibilitas

channels:
  defaults:
    heartbeat:
      showOk: false # Sembunyikan HEARTBEAT_OK (default)
      showAlerts: true # Tampilkan pesan alert (default)
      useIndicator: true # Emit event indikator (default)
  telegram:
    heartbeat:
      showOk: true # Tampilkan ack OK di Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Tekan pengiriman alert untuk akun ini

​

Fungsi setiap flag

• showOk: mengirim ack HEARTBEAT_OK ketika model mengembalikan balasan yang hanya berisi OK.
• showAlerts: mengirim konten alert ketika model mengembalikan balasan non-OK.
• useIndicator: memancarkan event indikator untuk permukaan status UI.

​

Contoh per-channel vs per-akun

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # semua akun Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # tekan alert hanya untuk akun ops
  telegram:
    heartbeat:
      showOk: true

​

Pola umum

​

HEARTBEAT.md (opsional)

# Checklist heartbeat

- Pemindaian cepat: ada yang mendesak di inbox?
- Jika siang hari, lakukan check-in ringan jika tidak ada hal lain yang tertunda.
- Jika suatu tugas terblokir, tuliskan _apa yang kurang_ dan tanyakan ke Peter lain kali.

​

Blok tasks:

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.

• OpenClaw mem-parse blok tasks: dan memeriksa setiap tugas terhadap interval-nya sendiri.
• 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-task di HEARTBEAT.md dipertahankan dan ditambahkan sebagai konteks tambahan setelah daftar tugas yang jatuh tempo.
• Timestamp terakhir-jalan tugas disimpan di state sesi (heartbeatTaskState), sehingga interval bertahan melewati restart normal.
• Timestamp tugas hanya dimajukan setelah run heartbeat menyelesaikan jalur balasan normalnya. Run empty-heartbeat-file / no-tasks-due yang dilewati tidak menandai tugas sebagai selesai.

​

Apakah agent dapat memperbarui HEARTBEAT.md?

• “Perbarui HEARTBEAT.md untuk menambahkan pemeriksaan kalender harian.”
• “Tulis ulang HEARTBEAT.md agar lebih singkat dan fokus pada tindak lanjut inbox.”

​

Bangun manual (sesuai permintaan)

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

​

Pengiriman reasoning (opsional)

• agents.defaults.heartbeat.includeReasoning: true

​

Kesadaran biaya

• Gunakan isolatedSession: true agar riwayat percakapan penuh tidak dikirim (~100K token turun menjadi ~2-5K per run).
• 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 ingin pembaruan state internal.

​

Terkait

• Otomatisasi & Tugas — semua mekanisme otomatisasi sekilas
• Tugas Latar Belakang — bagaimana pekerjaan terlepas dilacak
• Zona waktu — bagaimana zona waktu memengaruhi penjadwalan heartbeat
• Pemecahan masalah — debugging masalah otomatisasi