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 versus cron? Zie Automatisering en taken voor richtlijnen over wanneer je welke gebruikt.
Snelstart (beginner)
Kies een cadans
Laat heartbeats ingeschakeld (standaard is
30m, of 1h voor Anthropic OAuth/token-authenticatie, inclusief hergebruik van Claude CLI) of stel je eigen cadans in.Voeg HEARTBEAT.md toe (optioneel)
Maak een kleine
HEARTBEAT.md-checklist of een tasks:-blok in de agent-werkruimte.Bepaal waar heartbeat-berichten naartoe moeten
target: "none" is de standaard; stel target: "last" in om naar de laatste contactpersoon 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 de volledige gespreksgeschiedenis bij elke heartbeat wordt verzonden.
- Beperk heartbeats tot actieve uren (lokale tijd).
Standaardwaarden
- Interval:
30m(of1hwanneer Anthropic OAuth/token-authenticatie 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 worden automatisch uitgesteld terwijl cronwerk actief is of in de wachtrij staat. Stel
heartbeat.skipWhenBusy: truein om ook uit te stellen op extra drukke lanes (subagent- of genest commandowerk); dit is nuttig voor lokale Ollama en andere beperkte hosts met één runtime.
Waar de heartbeat-prompt voor is
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 melden.
- Check-in bij de mens: “Checkup sometimes on your human during day time” spoort aan tot af en toe een licht “heb je iets nodig?”-bericht, 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. - 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 weggelaten 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 is, wordt weggelaten.
Configuratie
Bereik en prioriteit
agents.defaults.heartbeatstelt het globale heartbeat-gedrag in.agents.list[].heartbeatwordt erbovenop samengevoegd; als een agent eenheartbeat-blok heeft, draaien alleen die agents heartbeats.channels.defaults.heartbeatstelt zichtbaarheidsstandaarden voor alle kanalen in.channels.<channel>.heartbeatoverschrijft kanaalstandaarden.channels.<channel>.accounts.<id>.heartbeat(kanalen met meerdere accounts) overschrijft instellingen per kanaal.
Heartbeats per agent
Als een vermelding inagents.list[] een heartbeat-blok bevat, draaien alleen die agents heartbeats. Het blok per agent wordt samengevoegd bovenop agents.defaults.heartbeat (zodat je gedeelde standaardwaarden eenmaal kunt instellen en per agent kunt overschrijven).
Voorbeeld: twee agents, alleen de tweede agent draait heartbeats.
Voorbeeld van actieve uren
Beperk heartbeats tot kantooruren in een specifieke tijdzone:24/7-instelling
Als je heartbeats de hele dag wilt laten draaien, gebruik dan een van deze patronen:- Laat
activeHoursvolledig weg (geen beperking op tijdvenster; dit is het standaardgedrag). - Stel een venster voor de volledige 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, 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 de bootstrapbestanden van de werkruimte.Wanneer true, draait elke heartbeat 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 extra drukke lanes: subagent- of genest commandowerk. Cron-lanes stellen heartbeats altijd uit, zelfs zonder deze vlag, zodat hosts met lokale modellen niet tegelijk cron- en heartbeat-prompts draaien.
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: lever aan het laatst gebruikte externe kanaal.- expliciet kanaal: een geconfigureerd kanaal of Plugin-id, bijvoorbeeld
discord,matrix,telegramofwhatsapp. none(standaard): draai de heartbeat 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 levering overgeslagen.Overschrijft de standaardprompttekst (niet samengevoegd).
Maximum aantal tekens toegestaan na
HEARTBEAT_OK vóór levering.Wanneer waar, onderdrukt dit waarschuwingspayloads voor toolfouten tijdens Heartbeat-runs.
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"user"-gedrag hierboven. startenendmogen niet gelijk zijn voor een actief venster; gelijke waarden worden behandeld als nul breedte (altijd buiten het venster).- Buiten het actieve venster worden Heartbeats overgeslagen tot de volgende tick binnen het venster.
Leveringsgedrag
Session and target routing
Session and target routing
- 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.). sessionheeft alleen invloed op de runcontext; levering wordt geregeld doortargetento.- Stel
target+toin om aan een specifiek kanaal/specifieke ontvanger te leveren. Mettarget: "last"gebruikt de levering het laatste externe kanaal voor die sessie. - Heartbeat-leveringen staan standaard directe/DM-doelen toe. Stel
directPolicy: "block"in om verzendingen naar directe doelen te onderdrukken terwijl de Heartbeat-beurt nog steeds wordt uitgevoerd. - Als de hoofdwachtrij, doelsessielane, Cron-lane of een actieve Cron-taak bezet is, wordt de Heartbeat overgeslagen en later opnieuw geprobeerd.
- Als
skipWhenBusy: true, stellen subagent- en geneste lanes Heartbeat-runs ook uit. - Als
targetgeen externe bestemming oplevert, vindt de run nog steeds plaats, maar wordt er geen uitgaand bericht verzonden.
Visibility and skip behavior
Visibility and skip behavior
- Als
showOk,showAlertsenuseIndicatorallemaal zijn uitgeschakeld, wordt de run vooraf overgeslagen alsreason=alerts-disabled. - Als alleen alertlevering is uitgeschakeld, kan OpenClaw de Heartbeat nog steeds uitvoeren, tijdstempels van vervallen taken bijwerken, de inactieve tijdstempel van de sessie herstellen en de uitgaande alertpayload onderdrukken.
- Als het opgeloste Heartbeat-doel typen ondersteunt, toont OpenClaw typen terwijl de Heartbeat-run actief is. Dit gebruikt hetzelfde doel waar de Heartbeat chatuitvoer naartoe zou sturen, en het wordt uitgeschakeld door
typingMode: "never".
Session lifecycle and audit
Session lifecycle and audit
- Antwoorden die alleen van Heartbeat zijn, houden de sessie niet actief. Heartbeat-metadata kan de sessierij bijwerken, maar inactieve vervaldatum gebruikt
lastInteractionAtvan het laatste echte gebruikers-/kanaalbericht, en dagelijkse vervaldatum gebruiktsessionStartedAt. - Control 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 alertinhoud wordt geleverd. 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 indicatorgebeurtenissen uit voor UI-statusoppervlakken.
Voorbeelden per kanaal versus per account
Veelvoorkomende patronen
| Doel | Configuratie |
|---|---|
| Standaardgedrag (stille OK’s, alerts 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 } |
| OK’s alleen in éé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 op te nemen.
Bij normale runs wordt HEARTBEAT.md alleen geïnjecteerd wanneer Heartbeat-richtlijnen zijn ingeschakeld voor de standaardagent. De Heartbeat-cadans uitschakelen met 0m of includeSystemPromptSection: false instellen laat het weg uit de normale bootstrapcontext.
Als HEARTBEAT.md bestaat maar feitelijk 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, draait de Heartbeat nog steeds en beslist het model wat te doen.
Houd het klein (korte checklist of herinneringen) om promptbloat te vermijden.
Voorbeeld HEARTBEAT.md:
tasks:-blokken
HEARTBEAT.md ondersteunt ook een klein gestructureerd tasks:-blok voor intervalgebaseerde controles binnen Heartbeat zelf.
Voorbeeld:
Behavior
Behavior
- OpenClaw parseert het
tasks:-blok en controleert elke taak tegen zijn eigeninterval. - Alleen vervallen taken worden opgenomen in de Heartbeat-prompt voor die tick.
- Als er geen taken vervallen zijn, wordt de Heartbeat volledig overgeslagen (
reason=no-tasks-due) om een verspilde modelaanroep te vermijden. - Niet-taakinhoud in
HEARTBEAT.mdwordt behouden en toegevoegd als extra context na de lijst met vervallen 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 voltooit. Overgeslagen
empty-heartbeat-file- /no-tasks-due-runs markeren taken niet als voltooid.
Kan de agent HEARTBEAT.md bijwerken?
Ja — als je hem daarom 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 is op inboxopvolgingen.”
Handmatige wake (op aanvraag)
Je kunt een systeemgebeurtenis in de wachtrij zetten en een onmiddellijke Heartbeat activeren 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.
Reasoning-levering (optioneel)
Standaard leveren Heartbeats alleen de uiteindelijke “answer”-payload. 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/codexen beheert en je wilt zien waarom hij besloot je te pingen — maar het kan ook meer interne details lekken dan je wilt. Houd het bij voorkeur uitgeschakeld 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 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 een kleiner lokaal model gebruikt, bijvoorbeeld een Ollama-model met een 32k-venster, en de volgende hoofdsessiebeurt contextoverloop meldt, controleer dan of de vorige Heartbeat de sessie op het Heartbeat-model heeft achtergelaten. Het resetbericht van OpenClaw wijst hierop wanneer het laatste runtimemodel overeenkomt met het geconfigureerdeheartbeat.model.
Gebruik isolatedSession: true om Heartbeats in een nieuwe sessie uit te voeren, combineer het met lightContext: true voor de kleinste prompt, of kies een Heartbeat-model met een contextvenster dat groot genoeg is voor de gedeelde sessie.
Gerelateerd
- Automatisering en taken — alle automatiseringsmechanismen in één overzicht
- Achtergrondtaken — hoe losgekoppeld werk wordt gevolgd
- Tijdzone — hoe de tijdzone Heartbeat-planning beïnvloedt
- Probleemoplossing — automatiseringsproblemen debuggen