​

Hartslag (Gateway)

Heartbeat vs Cron? Zie Cron vs Heartbeat voor richtlijnen over wanneer je welke gebruikt.

​

Snelle start (beginner)

1. Laat heartbeats ingeschakeld (standaard is 30m, of 1h voor Anthropic OAuth/setup-token) of stel je eigen cadans in.
2. Maak een kleine HEARTBEAT.md-checklist in de agent-werkruimte (optioneel maar aanbevolen).
3. Bepaal waar heartbeat-berichten naartoe moeten (target: "last" is de standaard).
4. Optioneel: schakel levering van heartbeat-redenering in voor transparantie.
5. Optioneel: beperk heartbeats tot actieve uren (lokale tijd).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

Standaardwaarden

• Interval: 30m (of 1h wanneer Anthropic OAuth/setup-token de gedetecteerde authenticatiemodus is). Stel agents.defaults.heartbeat.every in of per agent agents.list[].heartbeat.every; 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 woordelijk als gebruikersbericht verzonden. De systeem- prompt bevat een sectie “Heartbeat” en de run wordt intern gemarkeerd.
• Actieve uren (heartbeat.activeHours) worden gecontroleerd in de geconfigureerde tijdzone. Buiten het venster worden heartbeats overgeslagen tot de volgende tick binnen het venster.

​

Waar de heartbeat-prompt voor dient

• Achtergrondtaken: “Consider outstanding tasks” stimuleert de agent om openstaande opvolgingen (inbox, agenda, herinneringen, wachtrijen) te bekijken en alles urgents naar voren te brengen.
• Menselijke check-in: “Checkup sometimes on your human during day time” stimuleert een af en toe licht “heb je iets nodig?”-bericht, maar vermijdt nachtelijke spam door je geconfigureerde lokale tijdzone te gebruiken (zie /concepts/timezone).

​

Responscontract

• Als er niets aandacht nodig heeft, antwoord met HEARTBEAT_OK.
• Tijdens heartbeat-runs behandelt OpenClaw HEARTBEAT_OK als een ack wanneer het aan het begin of einde van het antwoord verschijnt. De token wordt verwijderd en het antwoord wordt verworpen als de resterende inhoud ≤ ackMaxChars (standaard: 300).
• Als HEARTBEAT_OK in het midden van een antwoord verschijnt, wordt het niet speciaal behandeld.
• Voor waarschuwingen niet HEARTBEAT_OK opnemen; retourneer alleen de waarschuwingstekst.

​

Config

{
  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)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        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
      },
    },
  },
}

​

Reikwijdte en prioriteit

• agents.defaults.heartbeat stelt globaal heartbeat-gedrag in.
• agents.list[].heartbeat voegt hier bovenop samen; als een agent een heartbeat-blok heeft, draaien alleen die agents heartbeats.
• channels.defaults.heartbeat stelt zichtbaarheidsstandaarden in voor alle kanalen.
• channels.<channel>.heartbeat overschrijft kanaalstandaarden.
• channels.<channel>.accounts.<id>.heartbeat (kanalen met meerdere accounts) overschrijft per-kanaalinstellingen.

​

Per-agent heartbeats

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    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.",
        },
      },
    ],
  },
}

​

Voorbeeld actieve uren

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

Voorbeeld met meerdere accounts

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Veld notities

• every: heartbeat-interval (duurstring; standaardeenheid = minuten).
• model: optionele model-override voor heartbeat-runs (provider/model).
• includeReasoning: wanneer ingeschakeld, lever ook het aparte Reasoning:-bericht wanneer beschikbaar (zelfde vorm als /reasoning on).
• session: optionele sessiesleutel voor heartbeat-runs.
  • main (standaard): hoofdsessie van de agent.
  • Expliciete sessiesleutel (kopieer uit openclaw sessions --json of de sessions CLI).
  • Formaten van sessiesleutels: zie Sessions en Groups.
• target:
  • last (standaard): lever aan het laatst gebruikte externe kanaal.
  • expliciet kanaal: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: voer de heartbeat uit maar lever niet extern.
• to: optionele ontvanger-override (kanaalspecifieke id, bijv. E.164 voor WhatsApp of een Telegram-chat-id).
• accountId: optionele account-id voor kanalen met meerdere accounts. Wanneer target: "last", geldt de account-id voor het opgeloste laatste kanaal als dat accounts ondersteunt; anders wordt deze genegeerd. Als de account-id niet overeen- komt met een geconfigureerd account voor het opgeloste kanaal, wordt levering overgeslagen.
• prompt: overschrijft de standaardprompttekst (niet samengevoegd).
• ackMaxChars: maximaal toegestane tekens na HEARTBEAT_OK vóór levering.
• activeHours: beperkt heartbeat-runs tot een tijdvenster. Object met start (HH:MM, inclusief), end (HH:MM exclusief; 24:00 toegestaan voor einde-van-de-dag), en optioneel timezone.
  • Weggelaten of "user": gebruikt je agents.defaults.userTimezone indien ingesteld, anders valt het terug op de tijdzone van het hostsysteem.
  • "local": gebruikt altijd de tijdzone van het hostsysteem.
  • Elke IANA-identificatie (bijv. America/New_York): direct gebruikt; bij ongeldig valt het terug op het "user"-gedrag hierboven.
  • Buiten het actieve venster worden heartbeats overgeslagen tot de volgende tick binnen het venster.

​

Leveringsgedrag

• Heartbeats draaien standaard in de hoofdsessie van de agent (agent:<id>:<mainKey>), of global wanneer session.scope = "global". Stel session in om te overschrijven naar een specifieke kanaalsessie (Discord/WhatsApp/etc.).
• session beïnvloedt alleen de runcontext; levering wordt geregeld door target en to.
• Om te leveren aan een specifiek kanaal/ontvanger, stel target + to in. Met target: "last" gebruikt levering het laatste externe kanaal voor die sessie.
• Als de hoofdqueue bezet is, wordt de heartbeat overgeslagen en later opnieuw geprobeerd.
• Als target naar geen externe bestemming resolveert, vindt de run nog steeds plaats maar wordt er geen uitgaand bericht verzonden.
• Alleen-heartbeat-antwoorden houden de sessie niet actief; de laatste updatedAt wordt hersteld zodat idle-verval normaal werkt.

​

Zichtbaarheidsinstellingen

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

​

Wat elke vlag doet

• showOk: verstuurt een HEARTBEAT_OK-acknowledgment wanneer het model een alleen-OK-antwoord retourneert.
• showAlerts: verstuurt de waarschuwingsinhoud wanneer het model een niet-OK- antwoord retourneert.
• useIndicator: genereert indicatorgebeurtenissen voor UI-statusoppervlakken.

​

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)

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

​

Kan de agent HEARTBEAT.md bijwerken?

• “Werk HEARTBEAT.md bij om een dagelijkse agendacontrole toe te voegen.”
• “Herschrijf HEARTBEAT.md zodat het korter is en gericht op inbox-opvolging.”

​

Handmatige wake (on-demand)

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

​

Levering van redenering (optioneel)

• agents.defaults.heartbeat.includeReasoning: true

​

Kostenbewustzijn