Cron vs Heartbeat: Wann du was nutzen solltest

Sowohl Heartbeats als auch Cron-Jobs erlauben es dir, Aufgaben nach Zeitplan auszuführen. Diese Anleitung hilft dir, den richtigen Mechanismus für deinen Anwendungsfall zu wählen.

Schnelle Entscheidungshilfe

Heartbeat: Periodische Aufmerksamkeit

Heartbeats laufen in der Main-Session in regelmäßigen Intervallen (Standard: 30 Min). Sie sind dafür gedacht, dass der Agent nach dem Rechten schaut und Wichtiges meldet.

Wann du Heartbeat nutzen solltest

• Mehrere periodische Checks: Statt 5 separate Cron-Jobs für Posteingang, Kalender, Wetter, Benachrichtigungen und Projektstatus, kann ein einzelner Heartbeat das alles bündeln.
• Kontextbewusste Entscheidungen: Der Agent hat vollen Main-Session-Kontext und kann so klug entscheiden, was dringend ist und was warten kann.
• Gesprächskontinuität: Heartbeat-Läufe teilen sich die gleiche Session, sodass der Agent sich an kürzliche Gespräche erinnert und natürlich nachfassen kann.
• Leichtgewichtige Überwachung: Ein Heartbeat ersetzt viele kleine Polling-Aufgaben.

Vorteile von Heartbeat

• Bündelt mehrere Checks: Ein Agent-Turn kann Posteingang, Kalender und Benachrichtigungen zusammen prüfen.
• Reduziert API-Aufrufe: Ein einzelner Heartbeat ist günstiger als 5 isolierte Cron-Jobs.
• Kontextbewusst: Der Agent weiß, woran du gearbeitet hast, und kann entsprechend priorisieren.
• Intelligente Unterdrückung: Wenn nichts Aufmerksamkeit braucht, antwortet der Agent HEARTBEAT_OK und es wird keine Nachricht zugestellt.
• Natürliches Timing: Driftet leicht je nach Queue-Last, was für die meisten Überwachungsaufgaben völlig in Ordnung ist.

Heartbeat-Beispiel: HEARTBEAT.md Checkliste

# Heartbeat-Checkliste

- E-Mails auf dringende Nachrichten prüfen
- Kalender auf Termine in den nächsten 2 Stunden prüfen
- Falls eine Hintergrundaufgabe fertig ist, Ergebnisse zusammenfassen
- Falls seit 8+ Stunden idle, kurzen Check-in senden

Der Agent liest das bei jedem Heartbeat und bearbeitet alle Punkte in einem Turn.

Heartbeat konfigurieren

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // Intervall
        target: "last", // explizites Alert-Zustellungsziel (Standard ist "none")
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}

Siehe Heartbeat für die vollständige Konfiguration.

Cron: Präzise Zeitplanung

Cron-Jobs laufen zu genauen Zeitpunkten und können in isolierten Sessions laufen, ohne den Main-Kontext zu beeinflussen. Wiederkehrende Zur-vollen-Stunde-Zeitpläne werden automatisch durch einen deterministischen Job-bezogenen Versatz in einem 0-5-Minuten-Fenster verteilt.

Wann du Cron nutzen solltest

• Exaktes Timing nötig: „Sende das jeden Montag um 9:00 Uhr” (nicht „irgendwann gegen 9”).
• Eigenständige Aufgaben: Aufgaben, die keinen Gesprächskontext brauchen.
• Anderes Modell/Thinking: Aufwändige Analysen, die ein leistungsstärkeres Modell rechtfertigen.
• Einmalige Erinnerungen: „Erinnere mich in 20 Minuten” mit --at.
• Häufige/laute Aufgaben: Aufgaben, die die Main-Session-History vollmüllen würden.
• Externe Trigger: Aufgaben, die unabhängig davon laufen sollen, ob der Agent anderweitig aktiv ist.

Vorteile von Cron

• Präzises Timing: 5-Feld oder 6-Feld (Sekunden) Cron-Ausdrücke mit Zeitzonen-Unterstützung.
• Eingebaute Lastverteilung: Wiederkehrende Zur-vollen-Stunde-Zeitpläne werden standardmäßig um bis zu 5 Minuten versetzt.
• Kontrolle pro Job: Versatz mit --stagger <Dauer> überschreiben oder exaktes Timing mit --exact erzwingen.
• Session-Isolation: Läuft in cron:<jobId> ohne die Main-History zu verschmutzen.
• Modell-Overrides: Günstigeres oder leistungsstärkeres Modell pro Job verwenden.
• Zustellkontrolle: Isolierte Jobs nutzen standardmäßig announce (Zusammenfassung); bei Bedarf none wählen.
• Sofortige Zustellung: Announce-Modus postet direkt, ohne auf den Heartbeat zu warten.
• Kein Agent-Kontext nötig: Läuft auch wenn die Main-Session idle oder komprimiert ist.
• Einmalige Unterstützung: --at für präzise Zeitstempel in der Zukunft.

Cron-Beispiel: Tägliches Morgen-Briefing

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"

Das läuft um exakt 7:00 Uhr New Yorker Zeit, nutzt Opus für Qualität und stellt eine Zusammenfassung direkt per WhatsApp zu.

Cron-Beispiel: Einmalige Erinnerung

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

Siehe Cron-Jobs für die vollständige CLI-Referenz.

Entscheidungs-Flussdiagramm

Muss die Aufgabe zu einem EXAKTEN Zeitpunkt laufen?
  JA -> Nutze Cron
  NEIN -> Weiter...

Braucht die Aufgabe Isolation von der Main-Session?
  JA -> Nutze Cron (isoliert)
  NEIN -> Weiter...

Kann diese Aufgabe mit anderen periodischen Checks gebündelt werden?
  JA -> Nutze Heartbeat (zur HEARTBEAT.md hinzufügen)
  NEIN -> Nutze Cron

Ist das eine einmalige Erinnerung?
  JA -> Nutze Cron mit --at
  NEIN -> Weiter...

Braucht es ein anderes Modell oder Thinking-Level?
  JA -> Nutze Cron (isoliert) mit --model/--thinking
  NEIN -> Nutze Heartbeat

Beides kombinieren

Das effizienteste Setup nutzt beides:

1. Heartbeat übernimmt die Routineüberwachung (Posteingang, Kalender, Benachrichtigungen) in einem gebündelten Turn alle 30 Minuten.
2. Cron übernimmt präzise Zeitpläne (tägliche Berichte, wöchentliche Reviews) und einmalige Erinnerungen.

Beispiel: Effizientes Automatisierungs-Setup

HEARTBEAT.md (alle 30 Min geprüft):

# Heartbeat-Checkliste

- Posteingang auf dringende E-Mails prüfen
- Kalender auf Termine in den nächsten 2h prüfen
- Anstehende Aufgaben überprüfen
- Leichter Check-in, falls seit 8+ Stunden ruhig

Cron-Jobs (präzises Timing):

# Tägliches Morgen-Briefing um 7 Uhr
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Wöchentliches Projekt-Review montags um 9 Uhr
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

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

Lobster: Deterministische Workflows mit Freigaben

Lobster ist die Workflow-Runtime für mehrstufige Tool-Pipelines, die deterministische Ausführung und explizite Freigaben brauchen. Nutze es, wenn die Aufgabe mehr als ein einzelner Agent-Turn ist und du einen fortsetzbaren Workflow mit menschlichen Checkpoints willst.

Wann Lobster passt

• Mehrstufige Automatisierung: Du brauchst eine feste Pipeline von Tool-Aufrufen, keinen einmaligen Prompt.
• Freigabe-Gates: Nebeneffekte sollen pausieren, bis du freigibst, und dann weiterlaufen.
• Fortsetzbare Läufe: Einen pausierten Workflow fortsetzen, ohne frühere Schritte erneut auszuführen.

Wie es mit Heartbeat und Cron zusammenspielt

• Heartbeat/Cron entscheiden, wann ein Lauf stattfindet.
• Lobster definiert, welche Schritte passieren, sobald der Lauf startet.

Für geplante Workflows nutze Cron oder Heartbeat, um einen Agent-Turn auszulösen, der Lobster aufruft. Für Ad-hoc-Workflows rufe Lobster direkt auf.

Betriebshinweise (aus dem Code)

• Lobster läuft als lokaler Subprozess (lobster CLI) im Tool-Modus und gibt einen JSON-Umschlag zurück.
• Wenn das Tool needs_approval zurückgibt, setzt du mit einem resumeToken und approve-Flag fort.
• Das Tool ist ein optionales Plugin; aktiviere es additiv über tools.alsoAllow: ["lobster"] (empfohlen).
• Lobster erwartet, dass die lobster CLI im PATH verfügbar ist.

Siehe Lobster für vollständige Nutzung und Beispiele.

Main-Session vs Isolierte Session

Sowohl Heartbeat als auch Cron können mit der Main-Session interagieren, aber auf unterschiedliche Weise:

Wann Main-Session-Cron nutzen

Nutze --session main mit --system-event, wenn du willst:

• Dass die Erinnerung/das Event im Main-Session-Kontext erscheint
• Dass der Agent es beim nächsten Heartbeat mit vollem Kontext bearbeitet
• Keinen separaten isolierten Lauf

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

Wann isoliertes Cron nutzen

Nutze --session isolated, wenn du willst:

• Einen sauberen Start ohne vorherigen Kontext
• Andere Modell- oder Thinking-Einstellungen
• Announce-Zusammenfassungen direkt an einen Channel
• History, die die Main-Session nicht vollmüllt

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

Kostenüberlegungen

Tipps:

• Halte HEARTBEAT.md klein, um den Token-Overhead zu minimieren.
• Bündele ähnliche Checks im Heartbeat statt in mehreren Cron-Jobs.
• Nutze target: "none" beim Heartbeat, wenn du nur interne Verarbeitung willst.
• Nutze isoliertes Cron mit einem günstigeren Modell für Routineaufgaben.

Verwandt

• Heartbeat – vollständige Heartbeat-Konfiguration
• Cron-Jobs – vollständige Cron-CLI- und API-Referenz
• System – System-Events + Heartbeat-Steuerung