Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Heartbeat vs Cron? Zie Automatisering voor richtlijnen over wanneer je welke gebruikt.
Snelle start (beginner)
Kies een ritme
Laat heartbeats ingeschakeld (standaard is
30m, of 1h voor Anthropic OAuth/tokenauthenticatie, inclusief hergebruik van Claude CLI) of stel je eigen ritme 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 standaardwaarde; 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).
Standaardwaarden
- Interval:
30m(of1hwanneer Anthropic OAuth/tokenauthenticatie de gedetecteerde authenticatiemodus 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. - 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 ookHEARTBEAT.mdweg 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: truein 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).
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 voor 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 bevat, wordt weggegooid.
Configuratie
Bereik en voorrang
agents.defaults.heartbeatstelt globaal heartbeat-gedrag in.agents.list[].heartbeatwordt daarbovenop 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 een item inagents.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.
Voorbeeld van actieve uren
Beperk heartbeats tot kantooruren in een specifieke tijdzone:24/7-configuratie
Als je wilt dat heartbeats de hele dag draaien, gebruik dan een van deze patronen:- Laat
activeHoursvolledig 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
GebruikaccountId om een specifiek account te targeten op kanalen met meerdere accounts, zoals Telegram:
Veldnotities
Heartbeat-interval (duurstring; standaardeenheid = minuten).
Optionele modeloverschrijving voor heartbeat-runs (
provider/model).Wanneer ingeschakeld, wordt ook het afzonderlijke
Reasoning:-bericht geleverd wanneer beschikbaar (dezelfde vorm als /reasoning on).Wanneer true gebruiken heartbeat-runs lichte bootstrapcontext en behouden ze alleen
HEARTBEAT.md uit bootstrapbestanden van de werkruimte.Wanneer true wordt elke heartbeat uitgevoerd in een nieuwe sessie zonder eerdere gespreksgeschiedenis. Gebruikt hetzelfde isolatiepatroon als Cron
sessionTarget: "isolated". Verlaagt de tokenkosten per heartbeat drastisch. Combineer met lightContext: true voor maximale besparing. Leveringsroutering gebruikt nog steeds de context van de hoofdsessie.Wanneer true stellen heartbeat-runs uit op de extra bezette lanes van die agent: zijn eigen sessiespecifieke subagent- of geneste commandowerk. Cron-lanes stellen heartbeats altijd uit, ook zonder deze vlag, zodat hosts met lokale modellen niet tegelijkertijd Cron- en heartbeat-prompts uitvoeren.
Optionele sessiesleutel voor heartbeat-runs.
main(standaard): hoofdsessie van de agent.- Expliciete sessiesleutel (kopieer uit
openclaw sessions --jsonof de sessies-CLI). - Indelingen van sessiesleutels: 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.
Beheert direct/DM-leveringsgedrag.
allow: sta directe/DM-levering van heartbeats toe. block: onderdruk directe/DM-levering (reason=dm-blocked).Optionele overschrijving van ontvanger (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 ingesteld, geldt de account-id voor het opgeloste laatste kanaal als dat accounts ondersteunt; anders wordt hij genegeerd. Als de account-id niet overeenkomt met een geconfigureerd account voor het opgeloste kanaal, wordt levering overgeslagen.Overschrijft de standaard promptbody (niet samengevoegd).
Max. aantal tekens toegestaan na
HEARTBEAT_OK vóór aflevering.Wanneer true, worden payloads met waarschuwingen over toolfouten tijdens Heartbeat-runs onderdrukt.
Beperkt Heartbeat-runs tot een tijdvenster. Object met
start (HH:MM, inclusief; gebruik 00:00 voor begin van de dag), end (HH:MM exclusief; 24:00 toegestaan voor einde van de dag) en optioneel timezone.- Weggelaten of
"user": gebruikt jeagents.defaults.userTimezoneindien ingesteld, anders wordt teruggevallen op de tijdzone van het hostsysteem. "local": gebruikt altijd de tijdzone van het hostsysteem.- Elke IANA-identificatie (bijv.
America/New_York): wordt direct gebruikt; indien ongeldig, wordt teruggevallen op het bovenstaande"user"-gedrag. startenendmogen voor een actief venster niet gelijk zijn; gelijke waarden worden behandeld als nulbreedte (altijd buiten het venster).- Buiten het actieve venster worden Heartbeats overgeslagen tot de volgende tick binnen het venster.
Aflevergedrag
Sessie- en doelroutering
Sessie- en doelroutering
- Heartbeats worden standaard uitgevoerd 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 uitvoeringscontext; aflevering wordt bepaald doortargetento.- Stel
target+toin om af te leveren bij een specifiek kanaal/ontvanger. Mettarget: "last"gebruikt aflevering het laatste externe kanaal voor die sessie. - Heartbeat-afleveringen staan standaard directe/DM-doelen toe. Stel
directPolicy: "block"in om verzenden naar directe doelen te onderdrukken terwijl de Heartbeat-beurt nog steeds wordt uitgevoerd. - Als de hoofdwachtrij, doel-sessielane, Cron-lane of een actieve Cron-taak bezet is, wordt de Heartbeat overgeslagen en later opnieuw geprobeerd.
- Als
skipWhenBusy: trueis ingesteld, stellen ook de sessiesleutelgebonden subagent en geneste lanes van deze agent Heartbeat-runs uit. Bezette lanes van andere agents stellen deze agent niet uit. - Als
targetgeen externe bestemming oplevert, wordt de run nog steeds uitgevoerd maar wordt er geen uitgaand bericht verzonden.
Zichtbaarheid en overslaggedrag
Zichtbaarheid en overslaggedrag
- Als
showOk,showAlertsenuseIndicatorallemaal uitgeschakeld zijn, wordt de run vooraf overgeslagen alsreason=alerts-disabled. - Als alleen aflevering van waarschuwingen is uitgeschakeld, kan OpenClaw de Heartbeat nog steeds uitvoeren, tijdstempels van verschuldigde taken bijwerken, de idle-tijdstempel van de sessie herstellen en de uitgaande waarschuwingspayload onderdrukken.
- Als het opgeloste Heartbeat-doel typen ondersteunt, toont OpenClaw typen terwijl de Heartbeat-run actief is. Dit gebruikt hetzelfde doel waarnaar de Heartbeat chatuitvoer zou verzenden, en het wordt uitgeschakeld door
typingMode: "never".
Sessieleven en audit
Sessieleven en audit
- Alleen-Heartbeat-antwoorden houden de sessie niet levend. Heartbeat-metadata kan de sessierij bijwerken, maar idle-verval gebruikt
lastInteractionAtvan het laatste echte gebruikers-/kanaalbericht, en dagelijks verval gebruiktsessionStartedAt. - De besturings-UI en WebChat-geschiedenis verbergen Heartbeat-prompts en OK-only bevestigingen. Het onderliggende sessietranscript kan die beurten nog steeds bevatten voor audit/replay.
- Losgekoppelde achtergrondtaken kunnen een systeemgebeurtenis 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 waarschuwingcontent wordt afgeleverd. 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 waarschuwingcontent wanneer het model een niet-OK antwoord retourneert.useIndicator: verzendt indicatorgebeurtenissen voor UI-statusoppervlakken.
Voorbeelden per-kanaal vs per-account
Veelvoorkomende patronen
| Doel | Configuratie |
|---|---|
| Standaardgedrag (stille OKs, waarschuwingen aan) | (geen configuratie 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 } |
| OKs 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-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:
tasks:-blokken
HEARTBEAT.md ondersteunt ook een klein gestructureerd tasks:-blok voor intervalgebaseerde controles binnen Heartbeat zelf.
Voorbeeld:
Gedrag
Gedrag
- OpenClaw parseert het
tasks:-blok en controleert elke taak tegen het eigeninterval. - Alleen verschuldigde taken worden opgenomen in de Heartbeat-prompt voor die tick.
- Als er geen taken verschuldigd zijn, wordt de Heartbeat volledig overgeslagen (
reason=no-tasks-due) om een verspilde modelaanroep te voorkomen. - Niet-taakcontent in
HEARTBEAT.mdwordt behouden en toegevoegd als extra context na de lijst met verschuldigde taken. - Tijdstempels van de laatste taakrun worden opgeslagen in sessiestatus (
heartbeatTaskState), zodat intervallen normale herstarts overleven. - Taaktijdstempels worden alleen vooruitgezet nadat een Heartbeat-run het normale antwoordpad heeft voltooid. Overgeslagen
empty-heartbeat-file- /no-tasks-due-runs markeren taken niet als voltooid.
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.mdbij om een dagelijkse kalendercontrole toe te voegen.” - “Herschrijf
HEARTBEAT.mdzodat het korter is en gericht op inbox-opvolgingen.”
Handmatige wake (op aanvraag)
Je kunt een systeemgebeurtenis in de wachtrij zetten en een onmiddellijke Heartbeat triggeren met: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
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: trueom te voorkomen dat de volledige gespreksgeschiedenis wordt verzonden (~100K tokens teruggebracht tot ~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 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 geconfigureerdheartbeat.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