OpenClaw Tutorial Teil 7: Cron-Jobs, Heartbeats & Automationen

Automatisierung ist der Punkt, an dem OpenClaw selbstständig auf Zeitpläne reagiert. Für solche Abläufe sind zwei Mechanismen wichtig: Automations für geplante Ausführungen und Heartbeats für regelmäßige Routineprüfungen.

Die aktuelle Dokumentation bezeichnet den eingebauten Scheduler als Automations. Die CLI-Oberfläche openclaw automations verwaltet diese Jobs; openclaw cron bleibt ein Alias. Dieses Tutorial verwendet den Cron-Alias, weil er auch in der lokal geprüften OpenClaw-Version verfügbar ist und zum Titel der Reihe passt.

Voraussetzungen prüfen

Der Scheduler läuft im Gateway-Prozess. Das Gateway muss deshalb zum geplanten Zeitpunkt aktiv sein. Ein ausgeschalteter Rechner führt einen Job nicht pünktlich aus.

Prüfe zuerst die Konfiguration und den Scheduler:

openclaw config validate
openclaw cron status
openclaw cron list

config validate sollte eine gültige Konfiguration melden. cron status zeigt den Zustand des Schedulers, während cron list die derzeit aktiven Jobs auflistet. Wenn bereits hier keine Verbindung zum Gateway zustande kommt, behebe zuerst den Gateway-Zugriff.

Kontrolliere außerdem die Befehle deiner installierten Version:

openclaw cron --help
openclaw cron create --help

Die offizielle Dokumentation beschreibt die aktuelle Funktionalität. Die lokale Hilfe zeigt, welche Optionen deine installierte Version tatsächlich akzeptiert.

Bei einem Nix-Setup gilt eine Besonderheit: Wenn OPENCLAW_NIX_MODE=1 gesetzt ist, behandelt OpenClaw seine JSON-Konfiguration als unveränderlich. Lesende Befehle wie config get und config validate funktionieren weiterhin. Änderungen musst du dann in der deklarativen Nix-Konfiguration vornehmen.

Einen sicheren Testjob anlegen

Beginne mit einer harmlosen Erinnerung, die zehn Minuten nach dem Anlegen läuft. Ein relativer Zeitpunkt verhindert, dass das Tutorial-Beispiel nach einigen Monaten abläuft:

openclaw cron create \
  --name 'Automation-Test' \
  --at '+10m' \
  --session main \
  --system-event 'Automation-Test: Antworte ausschließlich mit Test erfolgreich.' \
  --wake now \
  --delete-after-run

Die Ausgabe sollte eine Job-ID enthalten. Notiere sie für die folgenden Prüfungen.

Wenn du einen absoluten Zeitpunkt verwendest, gib ihn als ISO-Zeit mit Offset oder Z an, etwa 2027-02-01T16:00:00Z. Prüfe unmittelbar vor dem Anlegen, dass dieser Zeitpunkt noch in der Zukunft liegt. Z steht für UTC.

One-shot-Jobs werden nach erfolgreicher Ausführung standardmäßig gelöscht. --delete-after-run macht diese Absicht im Beispiel ausdrücklich sichtbar. Mit --keep-after-run kannst du einen ausgeführten One-shot-Job behalten.

Jobdefinition und Ausführung kontrollieren

Prüfe den gerade angelegten Job mit seiner ID:

openclaw cron get <job-id>
openclaw cron show <job-id>

Die gespeicherte Definition sollte den Namen Automation-Test, den relativen Ausführungszeitpunkt und die Session main zeigen. Die Run-Historie rufst du so ab:

openclaw cron runs --id <job-id>

Nach dem geplanten Zeitpunkt sollte dort ein abgeschlossener Lauf erscheinen. Jede Automation-Ausführung erzeugt laut aktueller Dokumentation außerdem einen Background-Task-Record.

Ein technisch erfolgreicher Lauf belegt nur, dass OpenClaw die Ausführung beendet hat. Prüfe zusätzlich, ob die erwartete Antwort Test erfolgreich. erzeugt wurde.

Wenn du den Test nicht abwarten möchtest, entfernst du den Job wieder:

openclaw cron rm <job-id>

Einen wiederkehrenden Job anlegen

Ein klassischer Cron-Ausdruck besteht aus fünf Feldern:

Häufig verwendete Muster sind:

Für einen Redaktionslauf an Werktagen um 09:00 Uhr legst du den Zeitplan und die Zeitzone ausdrücklich fest:

openclaw cron create \
  --name 'Redaktionsschluss' \
  --cron '0 9 * * 1-5' \
  --tz 'Europe/Berlin' \
  --session main \
  --system-event 'Redaktionsschluss: Priorisiere die Themen und erstelle die Tages-Queue.' \
  --wake now

Prüfe zuvor, ob openclaw cron create --help die Optionen --cron und --tz aufführt. Die lokal geprüfte CLI weist --cron als Zeitplanoption aus; der vollständige lokale Hilfetext muss für die verwendete Version auch --tz bestätigen.

Europe/Berlin ist eine IANA-Zeitzone und folgt der Sommerzeit. Eine feste UTC-Uhrzeit verschiebt sich dagegen relativ zur deutschen Ortszeit, wenn die Zeitumstellung erfolgt.

Kontrolliere den neuen Job anschließend:

openclaw cron show 'Redaktionsschluss'
openclaw cron list

Die Ausgabe sollte den Cron-Ausdruck und Europe/Berlin zeigen. Falls die Nutzlast harmlos und für einen manuellen Test geeignet ist, kannst du den Job mit seiner ID sofort auslösen:

openclaw cron run <job-id>
openclaw cron runs --id <job-id>

Heartbeats konfigurieren

Ein Heartbeat ist kein Ersatz für einen exakten Zeitplan. Er gibt einem Agent in regelmäßigen Abständen Gelegenheit, eine Checkliste abzuarbeiten. Einige Minuten Abweichung sollten bei solchen Aufgaben unproblematisch sein.

Lies vor jeder Änderung den bisherigen Wert aus und notiere die Ausgabe:

openclaw config get agents.defaults.heartbeat.every

Ein Intervall von einer Stunde setzt du so:

openclaw config set agents.defaults.heartbeat.every '1h'
openclaw config validate
openclaw config get agents.defaults.heartbeat.every

Der letzte Befehl bestätigt den gespeicherten Konfigurationswert. Ob anschließend ein Heartbeat tatsächlich ausgeführt wird, prüfst du getrennt anhand des Verhaltens beziehungsweise der Runtime-Ausgaben deines Gateways.

In einem Standard-Workspace legt OpenClaw unter anderem eine HEARTBEAT.md an. Dort beschreibst du die Checkliste, die während eines Heartbeats abgearbeitet werden soll. Bei einem eigenen Workspace musst du sicherstellen, dass der Agent auf den beabsichtigten Workspace zeigt und diese Datei dort tatsächlich vorhanden ist. Wie OpenClaw seine Workspace-Dateien nutzt, erklärt Teil 6: Workspace einrichten.

Eine zurückhaltende Checkliste könnte so aussehen:

Bei jedem Heartbeat:
- Prüfe, ob ein offener Artikel blockiert ist.
- Prüfe, ob neue relevante Hinweise vorliegen.
- Melde dich nur, wenn eine konkrete Aktion erforderlich ist.

Halte die Aufgaben eindeutig und begrenzt. Automatisch geladene Anweisungen können je nach Tool-Berechtigungen Dateien verändern, externe APIs aufrufen oder Nachrichten vorbereiten. Beginne deshalb mit reinen Prüfaufgaben und erweitere die Befugnisse erst nach einem kontrollierten Test.

Jeder tatsächlich ausgeführte Agent-Lauf kann Modell-, Tool- und API-Kosten verursachen. Für allgemeine Routineprüfungen sind Intervalle wie 30m, 1h oder 2h meist geeigneter als ein Fünf-Minuten-Takt.

Heartbeat-Änderung zurücknehmen

Wenn vor dem Test bereits ein Wert konfiguriert war, stellst du ihn mit demselben Befehl wieder her:

openclaw config set agents.defaults.heartbeat.every '<vorheriger-wert>'
openclaw config validate

War der Schlüssel zuvor nicht gesetzt, entfernst du die neue Vorgabe wieder:

openclaw config unset agents.defaults.heartbeat.every
openclaw config validate

Um Heartbeats bewusst zu deaktivieren, dokumentiert OpenClaw den Wert 0m:

openclaw config set agents.defaults.heartbeat.every '0m'
openclaw config validate

Bei einem Nix-Setup nimmst du Änderung und Rückweg in der deklarativen Nix-Quelle vor.

Cron oder Heartbeat?

Nutze eine Automation, wenn eine Aufgabe zu einer bestimmten Uhrzeit laufen soll, einen eigenen Zeitplan benötigt oder als einmalige Ausführung geplant ist. Die Run-Historie hilft anschließend bei der Kontrolle.

Ein Heartbeat passt besser, wenn ein Agent regelmäßig mehrere kleine Routineprüfungen bündeln soll und eine leichte zeitliche Abweichung akzeptabel ist. Ohne Handlungsbedarf kann der Lauf still enden.

Eine Aufgabe alle zehn Minuten und eine zweite Aufgabe täglich um 01:00 Uhr gehören in getrennte Automation-Jobs. Ein globaler Heartbeat mit eigener Uhrzeitlogik wäre schwerer zu prüfen und zu warten.

Praxisbeispiel für einen Redaktionsbetrieb

Ein konservatives Setup verbindet einen Automation-Job für den festen Redaktionsschluss mit einem moderaten Heartbeat für allgemeine Kontrollen.

Der Werktagsjob läuft um 09:00 Uhr deutscher Ortszeit:

openclaw cron create \
  --name 'Redaktionsschluss' \
  --cron '0 9 * * 1-5' \
  --tz 'Europe/Berlin' \
  --session main \
  --system-event 'Redaktionsschluss: Prüfe den Kandidaten-Pool, priorisiere die Themen und erstelle die Tages-Queue.' \
  --wake now

Der Heartbeat prüft stündlich, ob abseits dieses Termins Handlungsbedarf entstanden ist:

openclaw config set agents.defaults.heartbeat.every '1h'
openclaw config validate

Die fachliche Checkliste legst du bei einem Standard-Workspace in HEARTBEAT.md ab. Cron-Nutzlast und Heartbeat-Checkliste sollten unterschiedliche Verantwortlichkeiten behalten: Der Cron-Job erzeugt die Tages-Queue zum festen Termin; der Heartbeat meldet nur neu entstandene Blockaden.

Fehlersuche bei Automations

Wenn ein Job nicht wie erwartet läuft, geh in dieser Reihenfolge vor:

openclaw cron status
openclaw cron list --all
openclaw cron get <job-id>
openclaw cron show <job-id>
openclaw cron runs --id <job-id>
openclaw config validate

Kontrolliere anschließend:

• War das Gateway zum geplanten Zeitpunkt aktiv?
• Liegt ein One-shot-Zeitpunkt tatsächlich in der Zukunft?
• Enthält ein absoluter ISO-Zeitpunkt einen Offset oder Z?
• Zeigt die Jobdefinition bei Ortszeiten die gewünschte IANA-Zeitzone?
• Verwendet der Cron-Ausdruck fünf Felder in der richtigen Reihenfolge?
• Existieren Agent und Session aus der Jobdefinition?
• Ist der Job deaktiviert und deshalb nur mit --all sichtbar?
• Wurde ein erfolgreicher One-shot-Job erwartungsgemäß gelöscht?
• Enthält die Run-Historie einen Fehler oder Timeout?
• Entspricht die erzeugte Ausgabe dem fachlich erwarteten Ergebnis?

Die aktuelle Dokumentation beschreibt unterschiedliche Laufzeitgrenzen für Agent-, Command- und Script-Jobs. Lege für potenziell lange Jobs mit --timeout-seconds ein bewusstes Zeitbudget fest, sofern die lokale Hilfe deiner Version diese Option ausweist.

Fehlersuche bei Heartbeats

Prüfe zuerst den gespeicherten Wert und die Konfiguration:

openclaw config get agents.defaults.heartbeat.every
openclaw config validate

Wenn kein Heartbeat beobachtbar ist, kontrolliere danach den Gateway-Betrieb, den ausgewählten Agent und dessen Workspace. Prüfe dort, ob HEARTBEAT.md vorhanden ist und eine ausführbare Checkliste enthält.

Läuft der Heartbeat, erledigt aber keine sinnvolle Arbeit, ist das Intervall meist nicht die Ursache. Formuliere dann ein klares Prüfkriterium, ein erwartetes Verhalten bei Handlungsbedarf und ausdrücklich das Verhalten für den Normalfall ohne Aktion.

Wichtigste Punkte

Automations übernehmen in OpenClaw feste, persistente und überprüfbare Zeitpläne. Heartbeats bündeln weniger zeitkritische Routineprüfungen eines Agents.

Die robuste Aufteilung lautet: Feste Termine und getrennte Intervalle kommen in Automation-Jobs; allgemeine periodische Kontrollen übernimmt der Heartbeat. Prüfe nach jeder Änderung sowohl die gespeicherte Definition als auch einen tatsächlichen Lauf. Bei Ortszeiten gehört die Zeitzone ausdrücklich in den Job.

Im anschließenden Teil 8: Multi-Agent-Setup und Sub-Agenten geht es um die Verteilung von Aufgaben zwischen mehreren OpenClaw-Agents.

Dies ist Teil 7 der OpenClaw-Tutorial-Reihe auf agentenlog.de. Alle Tutorials