Cron vs Heartbeat: Wanneer gebruik je welke¶

Zowel heartbeats als cron-jobs laten je taken volgens een schema uitvoeren. Deze gids helpt je het juiste mechanisme te kiezen voor jouw use case.

Snelle beslisgids¶

Heartbeat: Periodiek bewustzijn¶

Heartbeats draaien in de main sessie met een vaste interval (standaard: 30 min). Ze zijn ontworpen zodat de agent zaken kan nalopen en alles wat belangrijk is kan signaleren.

Wanneer heartbeat gebruiken¶

• Meerdere periodieke checks: In plaats van 5 losse cron-jobs die inbox, agenda, weer, notificaties en projectstatus checken, kan één heartbeat dit allemaal bundelen.
• Contextbewuste beslissingen: De agent heeft volledige main-sessiecontext en kan dus slim bepalen wat urgent is en wat kan wachten.
• Conversationele continuïteit: Heartbeat-runs delen dezelfde sessie, waardoor de agent recente gesprekken onthoudt en natuurlijk kan opvolgen.
• Monitoring met lage overhead: Eén heartbeat vervangt veel kleine pollingtaken.

Voordelen van heartbeat¶

• Bundelt meerdere checks: Eén agent-beurt kan inbox, agenda en notificaties samen bekijken.
• Vermindert API-calls: Eén heartbeat is goedkoper dan 5 geïsoleerde cron-jobs.
• Contextbewust: De agent weet waar je mee bezig bent en kan daarop prioriteren.
• Slimme onderdrukking: Als er niets is dat aandacht vraagt, antwoordt de agent HEARTBEAT_OK en wordt er geen bericht afgeleverd.
• Natuurlijke timing: Wijkt licht af op basis van wachtrijbelasting, wat voor de meeste monitoring prima is.

Heartbeat-voorbeeld: HEARTBEAT.md-checklist¶

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

De agent leest dit bij elke heartbeat en handelt alle items in één beurt af.

Heartbeat configureren¶

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval
        target: "last", // where to deliver alerts
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}

Zie Heartbeat voor de volledige configuratie.

Cron: Precieze planning¶

Cron-jobs draaien op exacte tijden en kunnen in geïsoleerde sessies draaien zonder de main context te beïnvloeden.

Wanneer cron gebruiken¶

• Exacte timing vereist: “Stuur dit elke maandag om 9:00” (niet “ongeveer rond 9”).
• Losstaande taken: Taken die geen conversationele context nodig hebben.
• Ander model/denkwerk: Zware analyses die een krachtiger model rechtvaardigen.
• Eenmalige herinneringen: “Herinner me over 20 minuten” met --at.
• Luidruchtige/frequente taken: Taken die de geschiedenis van de main sessie zouden vervuilen.
• Externe triggers: Taken die onafhankelijk moeten draaien van of de agent anders actief is.

Voordelen van cron¶

• Exacte timing: 5-veld cron-expressies met tijdzone-ondersteuning.
• Sessiescheiding: Draait in cron:<jobId> zonder de main-geschiedenis te vervuilen.
• Model overrides: Gebruik per job een goedkoper of krachtiger model.
• Afleveringscontrole: Geïsoleerde jobs staan standaard op announce (samenvatting); kies none indien nodig.
• Directe aflevering: Announce-modus post direct zonder op een heartbeat te wachten.
• Geen agentcontext nodig: Draait zelfs als de main sessie idle of gecomprimeerd is.
• Ondersteuning voor eenmalig: --at voor precieze toekomstige tijdstempels.

Cron-voorbeeld: Dagelijkse ochtendbriefing¶

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

Dit draait exact om 7:00 uur New York-tijd, gebruikt Opus voor kwaliteit en kondigt direct een samenvatting aan op WhatsApp.

Cron-voorbeeld: Eenmalige herinnering¶

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

Zie Cron jobs voor de volledige CLI-referentie.

Beschrijfdiagram¶

Does the task need to run at an EXACT time?
  YES -> Use cron
  NO  -> Continue...

Does the task need isolation from main session?
  YES -> Use cron (isolated)
  NO  -> Continue...

Can this task be batched with other periodic checks?
  YES -> Use heartbeat (add to HEARTBEAT.md)
  NO  -> Use cron

Is this a one-shot reminder?
  YES -> Use cron with --at
  NO  -> Continue...

Does it need a different model or thinking level?
  YES -> Use cron (isolated) with --model/--thinking
  NO  -> Use heartbeat

Beide combineren¶

De meest efficiënte setup gebruikt beide:

1. Heartbeat verzorgt routinematige monitoring (inbox, agenda, notificaties) in één gebundelde beurt elke 30 minuten.
2. Cron verzorgt precieze schema’s (dagelijkse rapporten, wekelijkse reviews) en eenmalige herinneringen.

Voorbeeld: Efficiënte automatiseringssetup¶

HEARTBEAT.md (elke 30 min gecontroleerd):

# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours

Cron-jobs (precieze timing):

# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster: Deterministische workflows met goedkeuringen¶

Lobster is de workflow-runtime voor multi-step tool-pipelines die deterministische uitvoering en expliciete goedkeuringen nodig hebben. Gebruik dit wanneer de taak meer is dan één agent-beurt en je een hervatbare workflow met menselijke checkpoints wilt.

Wanneer Lobster past¶

• Multi-step automatisering: Je hebt een vaste pipeline van tool-calls nodig, geen eenmalige prompt.
• Goedkeuringspoorten: Bijwerkingen moeten pauzeren tot je goedkeurt en daarna hervatten.
• Hervatbare runs: Ga verder met een gepauzeerde workflow zonder eerdere stappen opnieuw uit te voeren.

Hoe het samenwerkt met heartbeat en cron¶

• Heartbeat/cron bepalen wanneer een run plaatsvindt.
• Lobster definieert welke stappen plaatsvinden zodra de run start.

Voor geplande workflows gebruik je cron of heartbeat om een agent-beurt te triggeren die Lobster aanroept. Voor ad-hoc workflows roep je Lobster direct aan.

Operationele notities (uit de code)¶

• Lobster draait als een lokale subprocess (lobster CLI) in tool-modus en retourneert een JSON-envelop.
• Als de tool needs_approval retourneert, hervat je met een resumeToken en de approve vlag.
• De tool is een optionele plugin; schakel deze additief in via tools.alsoAllow: ["lobster"] (aanbevolen).
• Als je lobsterPath doorgeeft, moet dit een absoluut pad zijn.

Zie Lobster voor volledig gebruik en voorbeelden.

Main sessie vs geïsoleerde sessie¶

Zowel heartbeat als cron kunnen met de main sessie interageren, maar op verschillende manieren:

Wanneer cron in de main sessie gebruiken¶

Gebruik --session main met --system-event wanneer je wilt:

• Dat de herinnering/het event in de main-sessiecontext verschijnt
• Dat de agent dit tijdens de volgende heartbeat met volledige context afhandelt
• Geen aparte geïsoleerde run

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

Wanneer geïsoleerde cron gebruiken¶

Gebruik --session isolated wanneer je wilt:

• Een schone lei zonder eerdere context
• Andere model- of denk-instellingen
• Samenvattingen direct naar een kanaal aankondigen
• Historie die de main sessie niet vervuilt

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

Kostenoverwegingen¶

Tips:

• Houd HEARTBEAT.md klein om token-overhead te minimaliseren.
• Bundel vergelijkbare checks in heartbeat in plaats van meerdere cron-jobs.
• Gebruik target: "none" op heartbeat als je alleen interne verwerking wilt.
• Gebruik geïsoleerde cron met een goedkoper model voor routinetaken.

Gerelateerd¶

• Heartbeat - volledige heartbeat-configuratie
• Cron jobs - volledige cron CLI- en API-referentie
• System - system events + heartbeat-bediening