Heartbeat versus cron? Zie Automatisering voor richtlijnen over wanneer u welke gebruikt.
Snel aan de slag (beginner)
Kies een interval
Laat heartbeats ingeschakeld (standaard is
30m, of 1h voor Anthropic OAuth/token-authenticatie, inclusief hergebruik van Claude CLI) of stel uw eigen interval in.Voeg HEARTBEAT.md toe (optioneel)
Maak een kleine
HEARTBEAT.md-checklist of een tasks:-blok in de agentwerkruimte.Bepaal waar heartbeat-berichten naartoe moeten
target: "none" is de standaard; stel target: "last" in om naar het laatste contact te routeren.Optionele afstemming
- Schakel levering van heartbeat-redenering in voor transparantie.
- Gebruik lichte bootstrapcontext als heartbeat-runs alleen
HEARTBEAT.mdnodig hebben. - Schakel geïsoleerde sessies in om te voorkomen dat bij elke heartbeat de volledige gespreksgeschiedenis wordt verzonden.
- Beperk heartbeats tot actieve uren (lokale tijd).
Standaarden
- Interval:
30m(of1hwanneer Anthropic OAuth/token-authenticatie de gedetecteerde auth-modus is, inclusief hergebruik van Claude CLI). Stelagents.defaults.heartbeat.everyof per agentagents.list[].heartbeat.everyin; gebruik0mom 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. - Time-out: niet-ingestelde heartbeat-beurten gebruiken
agents.defaults.timeoutSecondswanneer ingesteld. Anders gebruiken ze het heartbeat-interval, begrensd op 600 seconden. Stelagents.defaults.heartbeat.timeoutSecondsof per agentagents.list[].heartbeat.timeoutSecondsin voor langer heartbeat-werk. - De heartbeat-prompt wordt letterlijk verzonden als gebruikersbericht. 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 ookHEARTBEAT.mdweg uit de bootstrapcontext, zodat het model heartbeat-specifieke instructies niet 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 worden automatisch uitgesteld terwijl cron-werk actief is of in de wachtrij staat. Stel
heartbeat.skipWhenBusy: truein om een agent ook uit te stellen op zijn eigen sessie-gekoppelde subagent of geneste opdrachtbanen; sibling agents pauzeren niet langer alleen omdat een andere agent subagentwerk in uitvoering heeft.
Waar de heartbeat-prompt voor dient
De standaardprompt is bewust breed:- Achtergrondtaken: “Consider outstanding tasks” spoort de agent aan om follow-ups te bekijken (inbox, agenda, herinneringen, werk in de wachtrij) en alles wat urgent is te signaleren.
- Menselijke check-in: “Checkup sometimes on your human during day time” spoort een incidenteel licht “iets nodig?”-bericht aan, maar voorkomt nachtelijke spam door uw geconfigureerde lokale tijdzone te gebruiken (zie Tijdzone).
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_respondaanroepen metnotify: falsevoor geen zichtbare update, ofnotify: trueplusnotificationTextvoor een waarschuwing. Wanneer aanwezig heeft de gestructureerde toolrespons voorrang op de tekstfallback. - Tijdens heartbeat-runs behandelt OpenClaw
HEARTBEAT_OKals 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 ≤ackMaxCharsis (standaard: 300). - Als
HEARTBEAT_OKin het midden van een antwoord staat, wordt het niet speciaal behandeld. - Neem bij waarschuwingen geen
HEARTBEAT_OKop; retourneer alleen de waarschuwingstekst.
HEARTBEAT_OK aan het begin/einde van een bericht verwijderd en gelogd; een bericht dat alleen HEARTBEAT_OK is, wordt weggegooid.
Configuratie
Scope en voorrang
agents.defaults.heartbeatstelt globaal heartbeat-gedrag in.agents.list[].heartbeatwordt erbovenop samengevoegd; als een agent eenheartbeat-blok heeft, voeren alleen die agents heartbeats uit.channels.defaults.heartbeatstelt zichtbaarheidsstandaarden in voor alle kanalen.channels.<channel>.heartbeatoverschrijft kanaalstandaarden.channels.<channel>.accounts.<id>.heartbeat(kanalen met meerdere accounts) overschrijft instellingen per kanaal.
Heartbeats per agent
Als eenagents.list[]-item een heartbeat-blok bevat, voeren alleen die agents heartbeats uit. Het blok per agent wordt samengevoegd bovenop agents.defaults.heartbeat (zodat u gedeelde standaarden eenmaal kunt instellen en per agent kunt overschrijven).
Voorbeeld: twee agents, alleen de tweede agent voert heartbeats uit.
Voorbeeld van actieve uren
Beperk heartbeats tot kantooruren in een specifieke tijdzone:24/7-installatie
Als u wilt dat heartbeats de hele dag worden uitgevoerd, gebruikt u een van deze patronen:- Laat
activeHourshelemaal weg (geen tijdvensterbeperking; dit is het standaardgedrag). - Stel een venster voor de hele dag in:
activeHours: { start: "00:00", end: "24:00" }.
Voorbeeld met meerdere accounts
GebruikaccountId om een specifiek account te targeten op kanalen met meerdere accounts zoals Telegram:
Veldnotities
Heartbeat-interval (duurtekenreeks; standaardeenheid = minuten).
Optionele modeloverschrijving voor heartbeat-runs (
provider/model).Wanneer ingeschakeld, ook het afzonderlijke
Thinking-bericht leveren wanneer beschikbaar (dezelfde vorm als /reasoning on).Wanneer true gebruiken heartbeat-runs lichte bootstrapcontext en behouden ze alleen
HEARTBEAT.md uit workspace-bootstrapbestanden.Wanneer true wordt elke heartbeat uitgevoerd in een nieuwe sessie zonder eerdere gespreksgeschiedenis. Gebruikt hetzelfde isolatiepatroon als cron
sessionTarget: "isolated". Vermindert de tokenkosten per heartbeat drastisch. Combineer met lightContext: true voor maximale besparing. Leveringsroutering gebruikt nog steeds de context van de hoofdsessie.Wanneer true worden heartbeat-runs uitgesteld op de extra bezette banen van die agent: zijn eigen sessie-gekoppelde subagent of genest opdrachtwerk. Cron-banen stellen heartbeats altijd uit, zelfs zonder deze vlag, zodat hosts met lokale modellen cron- en heartbeat-prompts niet tegelijk uitvoeren.
Optionele sessiesleutel voor heartbeat-runs.
main(standaard): hoofdsessie van de agent.- Expliciete sessiesleutel (kopieer uit
openclaw sessions --jsonof de sessies-CLI). - Sessiesleutelformaten: zie Sessies en Groepen.
last: leveren aan het laatst gebruikte externe kanaal.- expliciet kanaal: elke geconfigureerde kanaal- of plugin-id, bijvoorbeeld
discord,matrix,telegramofwhatsapp. none(standaard): voer de heartbeat uit maar lever niet extern.
Regelt direct/DM-leveringsgedrag.
allow: sta direct/DM-heartbeatlevering toe. block: onderdruk direct/DM-levering (reason=dm-blocked).Optionele ontvangeroverschrijving (kanaalspecifieke id, bijv. E.164 voor WhatsApp of een Telegram-chat-id). Gebruik voor Telegram-onderwerpen/threads
<chatId>:topic:<messageThreadId>.Optionele account-id voor kanalen met meerdere accounts. Wanneer
target: "last" is, geldt de account-id voor het opgeloste laatste kanaal als dat accounts ondersteunt; anders wordt deze genegeerd. Als de account-id niet overeenkomt met een geconfigureerd account voor het opgeloste kanaal, wordt bezorging overgeslagen.Overschrijft de standaard prompttekst (niet samengevoegd).
Maximaal aantal tekens toegestaan na
HEARTBEAT_OK voor bezorging.Indien true, onderdrukt dit waarschuwingspayloads voor toolfouten tijdens Heartbeat-runs.
Maximaal aantal seconden toegestaan voor een Heartbeat-agentbeurt voordat deze wordt afgebroken. Laat dit leeg om
agents.defaults.timeoutSeconds te gebruiken wanneer ingesteld; anders wordt de Heartbeat-cadans gebruikt met een maximum van 600 seconden.Beperkt Heartbeat-runs tot een tijdvenster. Object met
start (HH:MM, inclusief; gebruik 00:00 voor het begin van de dag), end (HH:MM exclusief; 24:00 toegestaan voor het einde van de dag) en optioneel timezone.- Weggelaten of
"user": gebruikt jeagents.defaults.userTimezoneals die is ingesteld, en valt anders terug op de tijdzone van het hostsysteem. "local": gebruikt altijd de tijdzone van het hostsysteem.- Elke IANA-identificatie (bijv.
America/New_York): direct gebruikt; indien ongeldig, valt dit terug op het"user"-gedrag hierboven. startenendmogen niet gelijk zijn voor een actief venster; gelijke waarden worden behandeld als nulbreedte (altijd buiten het venster).- Buiten het actieve venster worden Heartbeats overgeslagen tot de volgende tick binnen het venster.
Bezorggedrag
Sessie- en targetroutering
Sessie- en targetroutering
- Heartbeats draaien standaard in de hoofdsessie van de agent (
agent:<id>:<mainKey>), ofglobalwanneersession.scope = "global". Stelsessionin om dit te overschrijven naar een specifieke kanaalsessie (Discord/WhatsApp/enz.). sessionbeïnvloedt alleen de runcontext; bezorging wordt bepaald doortargetento.- Stel
target+toin om bij een specifiek kanaal/specifieke ontvanger te bezorgen. Mettarget: "last"gebruikt bezorging het laatste externe kanaal voor die sessie. - Heartbeat-bezorgingen staan standaard directe/DM-targets toe. Stel
directPolicy: "block"in om verzendingen naar directe targets te onderdrukken terwijl de Heartbeat-beurt nog steeds draait. - Als de hoofdwachtrij, target-sessielane, Cron-lane of een actieve Cron-taak bezet is, wordt de Heartbeat overgeslagen en later opnieuw geprobeerd.
- Als
skipWhenBusy: trueis, stellen ook de op sessiesleutel gebaseerde subagent en geneste lanes van deze agent Heartbeat-runs uit. Bezette lanes van andere agents stellen deze agent niet uit. - Als
targetniet naar een externe bestemming oplost, vindt de run nog steeds plaats, maar wordt er geen uitgaand bericht verzonden.
Zichtbaarheid en overslaggedrag
Zichtbaarheid en overslaggedrag
- Als
showOk,showAlertsenuseIndicatorallemaal zijn uitgeschakeld, wordt de run vooraf overgeslagen alsreason=alerts-disabled. - Als alleen alertbezorging is uitgeschakeld, kan OpenClaw de Heartbeat nog steeds uitvoeren, tijdstempels van vervallen taken bijwerken, de inactiviteitstijdstempel van de sessie herstellen en de uitgaande alertpayload onderdrukken.
- Als het opgeloste Heartbeat-target typen ondersteunt, toont OpenClaw typen terwijl de Heartbeat-run actief is. Dit gebruikt hetzelfde target waarnaar de Heartbeat chatuitvoer zou sturen, en wordt uitgeschakeld door
typingMode: "never".
Sessieleven cyclus en audit
Sessieleven cyclus en audit
- Antwoorden die alleen van Heartbeat komen houden de sessie niet levend. Heartbeat-metadata kan de sessierij bijwerken, maar inactiviteitsverloop gebruikt
lastInteractionAtvan het laatste echte gebruikers-/kanaalbericht, en dagelijks verloop gebruiktsessionStartedAt. - Geschiedenis in Control UI en WebChat verbergt Heartbeat-prompts en OK-only bevestigingen. Het onderliggende sessietranscript kan die beurten nog steeds bevatten voor audit/replay.
- Losgekoppelde achtergrondtaken kunnen een systeemevent in de wachtrij zetten en Heartbeat wekken wanneer de hoofdsessie snel iets moet opmerken. Die wake maakt van de Heartbeat-run geen achtergrondtaak.
Zichtbaarheidsinstellingen
Standaard wordenHEARTBEAT_OK-bevestigingen onderdrukt terwijl alertinhoud wordt bezorgd. Je kunt dit per kanaal of per account aanpassen:
Wat elke vlag doet
showOk: verzendt eenHEARTBEAT_OK-bevestiging wanneer het model een OK-only antwoord retourneert.showAlerts: verzendt de alertinhoud wanneer het model een niet-OK-antwoord retourneert.useIndicator: zendt indicator-events uit voor UI-statusoppervlakken.
Voorbeelden per kanaal versus per account
Veelvoorkomende patronen
| Doel | Config |
|---|---|
| Standaardgedrag (stille OK’s, alerts aan) | (geen config nodig) |
| Volledig stil (geen berichten, geen indicator) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false } |
| Alleen indicator (geen berichten) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true } |
| OK’s in slechts één kanaal | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md (optioneel)
Als er eenHEARTBEAT.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-richtlijnen zijn ingeschakeld voor de standaardagent. Het uitschakelen van de Heartbeat-cadans met 0m of het instellen van includeSystemPromptSection: false laat het weg uit de normale bootstrapcontext.
Op de native Codex-harness wordt HEARTBEAT.md-inhoud niet in de beurt geïnjecteerd. Als het bestand bestaat en inhoud bevat die niet alleen uit witruimte bestaat, wijzen de instructies voor Heartbeat-samenwerkingsmodus Codex naar het bestand en vertellen ze het om dit te lezen voordat het verdergaat.
Als HEARTBEAT.md bestaat maar feitelijk leeg is (alleen lege regels, Markdown-/HTML-comments, Markdown-koppen zoals # Heading, fence-markers of lege checkliststubs), slaat OpenClaw de Heartbeat-run over om API-aanroepen te besparen. Die overslag wordt gerapporteerd als reason=empty-heartbeat-file. Als het bestand ontbreekt, draait de Heartbeat nog steeds en bepaalt het model wat er moet gebeuren.
Houd het heel klein (korte checklist of herinneringen) om promptbloat te voorkomen.
Voorbeeld HEARTBEAT.md:
tasks:-blokken
HEARTBEAT.md ondersteunt ook een klein gestructureerd tasks:-blok voor intervalgebaseerde controles binnen Heartbeat zelf.
Voorbeeld:
Gedrag
Gedrag
- OpenClaw parset het
tasks:-blok en controleert elke taak tegen zijn eigeninterval. - Alleen vervallen taken worden voor die tick in de Heartbeat-prompt opgenomen.
- Als er geen taken vervallen zijn, wordt de Heartbeat volledig overgeslagen (
reason=no-tasks-due) om een verspilde modelaanroep te voorkomen. - Niet-taakinhoud in
HEARTBEAT.mdwordt behouden en toegevoegd als extra context na de lijst met vervallen taken. - Tijdstempels van de laatste run van taken worden opgeslagen in sessiestatus (
heartbeatTaskState), zodat intervallen normale herstarts overleven. - Taaktijdstempels worden pas bijgewerkt nadat een Heartbeat-run het normale antwoordpad voltooit. Overgeslagen
empty-heartbeat-file- /no-tasks-due-runs markeren taken niet als voltooid.
Kan de agent HEARTBEAT.md bijwerken?
Ja — als je erom vraagt.HEARTBEAT.md is gewoon een normaal bestand in de agentworkspace, dus je kunt de agent (in een normale chat) iets vertellen als:
- “Werk
HEARTBEAT.mdbij om een dagelijkse kalendercontrole toe te voegen.” - “Herschrijf
HEARTBEAT.mdzodat het korter is en gericht op inboxopvolging.”
Handmatige wake (op aanvraag)
Je kunt een systeemevent in de wachtrij zetten en een onmiddellijke Heartbeat triggeren met:heartbeat hebben geconfigureerd, voert een handmatige wake elk van die agent-Heartbeats onmiddellijk uit.
Gebruik --mode next-heartbeat om te wachten op de volgende geplande tick.
Redeneringsbezorging (optioneel)
Standaard bezorgen Heartbeats alleen de uiteindelijke “answer”-payload. Als je transparantie wilt, schakel dan in:agents.defaults.heartbeat.includeReasoning: true
Thinking (dezelfde vorm als /reasoning on). Dit kan nuttig zijn wanneer de agent meerdere sessies/codexen beheert en je wilt zien waarom die 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: trueom te voorkomen dat volledige gespreksgeschiedenis wordt verzonden (~100K tokens omlaag naar ~2-5K per run). - Gebruik
lightContext: trueom bootstrapbestanden te beperken tot alleenHEARTBEAT.md. - Stel een goedkoper
modelin (bijv.ollama/llama3.2:1b). - Houd
HEARTBEAT.mdklein. - 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 32k-venster, en de volgende hoofdsessiebeurt contextoverloop meldt, zet dan het runtimemodel van de sessie terug naar het geconfigureerde primaire model. Het resetbericht van OpenClaw benoemt dit wanneer het laatste runtimemodel overeenkomt met de geconfigureerdeheartbeat.model.
Huidige Heartbeats behouden het bestaande runtimemodel van de gedeelde sessie nadat de run is voltooid. Je kunt nog steeds isolatedSession: true gebruiken om Heartbeats in een nieuwe 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 gevolgd
- Tijdzone — hoe de tijdzone Heartbeat-planning beïnvloedt
- Probleemoplossing — automatiseringsproblemen debuggen