Heartbeat

Heartbeat voert periodieke agentbeurten uit in de hoofdsessie, zodat het model alles kan melden dat aandacht nodig heeft zonder je te spammen.

Heartbeat is een geplande beurt in de hoofdsessie — het maakt geen records voor achtergrondtaken aan. Taakrecords zijn voor losgekoppeld werk (ACP-runs, subagenten, geïsoleerde Cron-taken).

Probleemoplossing: Geplande taken

Snelle start (beginner)

Voorbeeldconfiguratie:

{  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 `Reasoning:` message too      },    },  },}

Standaardwaarden

• Interval: 30m (of 1h wanneer Anthropic OAuth/tokenauthenticatie de gedetecteerde authenticatiemodus is, inclusief hergebruik van Claude CLI). Stel agents.defaults.heartbeat.every of per agent agents.list[].heartbeat.every in; gebruik 0m om uit te schakelen.
• Prompttekst (configureerbaar via 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.
• De heartbeat-prompt wordt letterlijk als gebruikersbericht verzonden. De systeemprompt bevat alleen een sectie "Heartbeat" wanneer heartbeats zijn ingeschakeld voor de standaardagent, en de run wordt intern gemarkeerd.
• Wanneer heartbeats zijn uitgeschakeld met 0m, laten normale runs ook HEARTBEAT.md weg uit de bootstrapcontext, zodat het model geen heartbeat-specifieke instructies ziet.
• Actieve uren (heartbeat.activeHours) worden gecontroleerd in de geconfigureerde tijdzone. Buiten het venster worden heartbeats overgeslagen tot de volgende tick binnen het venster.
• Heartbeats stellen automatisch uit zolang Cron-werk actief is of in de wachtrij staat. Stel heartbeat.skipWhenBusy: true in om ook een agent uit te stellen op zijn eigen sessiespecifieke subagent- of geneste commandolanes; sibling-agents pauzeren niet meer alleen omdat een andere agent subagentwerk heeft lopen.

Waar de heartbeat-prompt voor dient

De standaardprompt is bewust breed:

• Achtergrondtaken: "Overweeg openstaande taken" zet de agent aan om follow-ups te bekijken (inbox, agenda, herinneringen, werk in de wachtrij) en alles te melden dat urgent is.
• Inchecken bij de mens: "Check soms overdag bij je mens in" zet aan tot af en toe een lichtgewicht bericht als "heb je iets nodig?", maar voorkomt nachtelijke spam door je geconfigureerde lokale tijdzone te gebruiken (zie Tijdzone).

Heartbeat kan reageren op voltooide achtergrondtaken, maar een heartbeat-run zelf maakt geen taakrecord aan.

Als je wilt dat een heartbeat iets heel specifieks doet (bijv. "controleer Gmail PubSub-statistieken" of "verifieer Gateway-gezondheid"), stel dan agents.defaults.heartbeat.prompt (of agents.list[].heartbeat.prompt) in op een aangepaste tekst (letterlijk verzonden).

Responscontract

• Als niets aandacht nodig heeft, antwoord dan met HEARTBEAT_OK.
• Heartbeat-runs met tools kunnen in plaats daarvan heartbeat_respond aanroepen met notify: false voor geen zichtbare update, of notify: true plus notificationText voor een waarschuwing. Wanneer aanwezig, heeft de gestructureerde toolrespons voorrang op de tekstfallback.
• Tijdens heartbeat-runs behandelt OpenClaw HEARTBEAT_OK als een bevestiging wanneer het aan het begin of einde van het antwoord staat. Het token wordt verwijderd en het antwoord wordt weggegooid als de resterende inhoud ≤ ackMaxChars is (standaard: 300).
• Als HEARTBEAT_OK in het midden van een antwoord staat, wordt het niet speciaal behandeld.
• Neem voor waarschuwingen geen HEARTBEAT_OK op; retourneer alleen de waarschuwingstekst.

Buiten heartbeats wordt losse HEARTBEAT_OK aan het begin/einde van een bericht verwijderd en gelogd; een bericht dat alleen HEARTBEAT_OK bevat, wordt weggegooid.

Configuratie

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Reasoning: 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      },    },  },}

Bereik en voorrang

• agents.defaults.heartbeat stelt globaal heartbeat-gedrag in.
• agents.list[].heartbeat wordt daarbovenop samengevoegd; als een agent een heartbeat-blok heeft, voeren alleen die agents heartbeats uit.
• channels.defaults.heartbeat stelt zichtbaarheidsstandaarden in voor alle kanalen.
• channels.<channel>.heartbeat overschrijft kanaalstandaarden.
• channels.<channel>.accounts.<id>.heartbeat (kanalen met meerdere accounts) overschrijft instellingen per kanaal.

Heartbeats per agent

Als een item in agents.list[] een heartbeat-blok bevat, voeren alleen die agents heartbeats uit. Het blok per agent wordt bovenop agents.defaults.heartbeat samengevoegd (zodat je gedeelde standaardwaarden één keer kunt instellen en per agent kunt overschrijven).

Voorbeeld: twee agents, alleen de tweede agent voert heartbeats uit.

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

Voorbeeld van actieve uren

Beperk heartbeats tot kantooruren in een specifieke tijdzone:

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

Buiten dit venster (voor 9.00 uur of na 22.00 uur Eastern) worden heartbeats overgeslagen. De volgende geplande tick binnen het venster wordt normaal uitgevoerd.

24/7-configuratie

Als je wilt dat heartbeats de hele dag draaien, gebruik dan een van deze patronen:

• Laat activeHours volledig weg (geen beperking tot een tijdvenster; dit is het standaardgedrag).
• Stel een venster voor de hele dag in: activeHours: { start: "00:00", end: "24:00" }.

Voorbeeld met meerdere accounts

Gebruik accountId om een specifiek account te targeten op kanalen met meerdere accounts, zoals 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" },      },    },  },}

Veldnotities

Aflevergedrag

Zichtbaarheidsinstellingen

Standaard worden HEARTBEAT_OK-bevestigingen onderdrukt terwijl waarschuwingcontent wordt afgeleverd. Je kunt dit per kanaal of per account aanpassen:

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

Voorrang: per-account → per-kanaal → kanaalstandaarden → ingebouwde standaarden.

Wat elke vlag doet

• showOk: verzendt een HEARTBEAT_OK-bevestiging wanneer het model een OK-only antwoord retourneert.
• showAlerts: verzendt de waarschuwingcontent wanneer het model een niet-OK antwoord retourneert.
• useIndicator: verzendt indicatorgebeurtenissen voor UI-statusoppervlakken.

Als alle drie false zijn, slaat OpenClaw de Heartbeat-run volledig over (geen modelaanroep).

Voorbeelden per-kanaal vs per-account

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

Veelvoorkomende patronen

HEARTBEAT.md (optioneel)

Als er een HEARTBEAT.md-bestand in de workspace bestaat, vertelt de standaardprompt de agent om het te lezen. Zie het als je "Heartbeat-checklist": klein, stabiel en veilig om elke 30 minuten mee te nemen.

Bij normale runs wordt HEARTBEAT.md alleen geïnjecteerd wanneer Heartbeat-begeleiding is ingeschakeld voor de standaardagent. Door de Heartbeat-cadans uit te schakelen met 0m of includeSystemPromptSection: false in te stellen, wordt het weggelaten uit de normale bootstrapcontext.

Als HEARTBEAT.md bestaat maar effectief leeg is (alleen lege regels en markdownkoppen zoals # Heading), slaat OpenClaw de Heartbeat-run over om API-aanroepen te besparen. Die overslag wordt gerapporteerd als reason=empty-heartbeat-file. Als het bestand ontbreekt, wordt de Heartbeat nog steeds uitgevoerd en beslist het model wat het doet.

Houd het klein (korte checklist of herinneringen) om promptgroei te voorkomen.

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

tasks:-blokken

HEARTBEAT.md ondersteunt ook een klein gestructureerd tasks:-blok voor intervalgebaseerde controles binnen Heartbeat zelf.

Voorbeeld:

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.

Taakmodus is nuttig wanneer je wilt dat één Heartbeat-bestand meerdere periodieke controles bevat zonder voor allemaal bij elke tick te betalen.

Kan de agent HEARTBEAT.md bijwerken?

Ja — als je dat vraagt.

HEARTBEAT.md is gewoon een normaal bestand in de agent-workspace, dus je kunt de agent (in een normale chat) iets vertellen als:

• "Werk HEARTBEAT.md bij om een dagelijkse kalendercontrole toe te voegen."
• "Herschrijf HEARTBEAT.md zodat het korter is en gericht op inbox-opvolgingen."

Als je wilt dat dit proactief gebeurt, kun je ook een expliciete regel opnemen in je Heartbeat-prompt zoals: "Als de checklist verouderd raakt, werk HEARTBEAT.md dan bij met een betere."

Handmatige wake (op aanvraag)

Je kunt een systeemgebeurtenis in de wachtrij zetten en een onmiddellijke Heartbeat triggeren met:

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

Als meerdere agents heartbeat geconfigureerd hebben, voert een handmatige wake elk van die agent-Heartbeats onmiddellijk uit.

Gebruik --mode next-heartbeat om te wachten op de volgende geplande tick.

Reasoning-aflevering (optioneel)

Standaard leveren Heartbeats alleen de uiteindelijke "answer"-payload af.

Als je transparantie wilt, schakel dan in:

• agents.defaults.heartbeat.includeReasoning: true

Wanneer ingeschakeld, leveren Heartbeats ook een afzonderlijk bericht af met prefix Reasoning: (dezelfde vorm als /reasoning on). Dit kan nuttig zijn wanneer de agent meerdere sessies/codexes beheert en je wilt zien waarom hij besloot je te pingen — maar het kan ook meer interne details lekken dan je wilt. Houd dit bij voorkeur uit in groepschats.

Kostenbewustzijn

Heartbeats voeren volledige agentbeurten uit. Kortere intervallen verbruiken meer tokens. Om kosten te verlagen:

• Gebruik isolatedSession: true om te voorkomen dat de volledige gespreksgeschiedenis wordt verzonden (~100K tokens teruggebracht tot ~2-5K per run).
• Gebruik lightContext: true om bootstrapbestanden te beperken tot alleen HEARTBEAT.md.
• Stel een goedkoper model in (bijv. ollama/llama3.2:1b).
• Houd HEARTBEAT.md klein.
• Gebruik target: "none" als je alleen interne statusupdates wilt.

Contextoverloop na Heartbeat

Als een Heartbeat eerder een bestaande sessie op een kleiner lokaal model heeft achtergelaten, bijvoorbeeld een Ollama-model met een venster van 32k, en de volgende hoofdsessiebeurt contextoverloop meldt, reset dan het runtime-model van de sessie terug naar het geconfigureerde primaire model. Het resetbericht van OpenClaw wijst dit expliciet aan wanneer het laatste runtime-model overeenkomt met geconfigureerd heartbeat.model.

Huidige Heartbeats behouden het bestaande runtime-model van de gedeelde sessie nadat de run is voltooid. Je kunt nog steeds isolatedSession: true gebruiken om Heartbeats in een verse sessie uit te voeren, dit combineren met lightContext: true voor de kleinste prompt, of een Heartbeat-model kiezen met een contextvenster dat groot genoeg is voor de gedeelde sessie.

Gerelateerd

• Automatisering — alle automatiseringsmechanismen in één oogopslag
• Achtergrondtaken — hoe losgekoppeld werk wordt bijgehouden
• Tijdzone — hoe tijdzone Heartbeat-planning beïnvloedt
• Probleemoplossing — automatiseringsproblemen debuggen