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 und führt openclaw automations als bevorzugte CLI-Oberfläche. openclaw cron bleibt der kompatible Name für dieselben Scheduler-Funktionen. Nicht jede bereits installierte OpenClaw-Version kennt jedoch den neuen Befehl: In der für dieses Tutorial lokal geprüften Version ist nur openclaw cron verfügbar. Deshalb verwendet die Anleitung durchgehend diesen belegten Aufruf.

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 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 den aktuellen Funktionsumfang. Die lokale Hilfe entscheidet, welche Befehlsnamen und Optionen deine installierte Version tatsächlich akzeptiert. Falls openclaw automations --help bei dir funktioniert, kannst du die aktuellen Automations-Befehle verwenden; die folgenden Beispiele bleiben mit dem Cron-Namen reproduzierbar.

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 erfolgreich 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, die Session main und einen absoluten Ausführungszeitpunkt ungefähr zehn Minuten nach dem Anlegen zeigen. Der Scheduler löst den relativen Wert +10m beim Erstellen des Jobs in einen konkreten Zeitpunkt auf.

Die Run-Historie rufst du so ab:

openclaw cron runs --id <job-id>

Nach dem geplanten Zeitpunkt sollte dort ein abgeschlossener Lauf erscheinen. Ein erfolgreich ausgeführter One-shot-Job kann anschließend aus der normalen Jobliste verschwinden, weil er wie vorgesehen gelöscht wurde. 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; die lokale Hilfe deiner installierten Version muss 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>

Entferne einen nicht mehr benötigten Testjob mit openclaw cron rm <job-id>.

Heartbeats konfigurieren

Ein Heartbeat ist kein Ersatz für einen exakten Zeitplan. Er startet einen periodischen Agent-Turn in der Hauptsession, damit regelmäßige Prüfungen gebündelt werden können. Einige Minuten Abweichung sollten bei solchen Aufgaben unproblematisch sein.

Geplante Heartbeats hängen vom Automations-Scheduler ab. Wenn cron.enabled deaktiviert oder die Umgebungsvariable OPENCLAW_SKIP_CRON=1 gesetzt ist, führt das Gateway keine geplanten Heartbeats aus. Manuelle oder ereignisgesteuerte Heartbeat-Wakes bleiben davon unberührt.

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 tatsächlich ein Heartbeat ausgeführt wird, prüfst du getrennt anhand des Gateway-Verhaltens und der Runtime-Ausgaben.

Die aktuelle Runtime verwaltet für jeden Heartbeat-fähigen Agent einen systemeigenen Automation-Job. Er ist mit folgendem Befehl sichtbar:

openclaw cron list --all

Der Eintrag trägt einen Namen nach dem Muster Heartbeat (agent-id). Bearbeite diesen systemverwalteten Job nicht direkt. Die gewünschte Taktung konfigurierst du über agents.defaults.heartbeat.every beziehungsweise die agentenspezifische Heartbeat-Konfiguration.

In einem Standard-Workspace legt OpenClaw unter anderem eine HEARTBEAT.md an. Dort beschreibst du die Checkliste für den Heartbeat. 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.

Heartbeat-Hinweise gehen standardmäßig als Direktnachricht an den erkannten Operator. Stelle für die gewünschte Messaging-Oberfläche eine konkrete Owner-Zuordnung über commands.ownerAllowFrom oder eine konkrete allowFrom-Freigabe des Kanals sicher. Eine reine Wildcard-Freigabe identifiziert keinen Operator und reicht für diese Standardzustellung nicht aus.

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. Im Gegensatz zu Automation-Ausführungen erzeugen Heartbeat-Turns keinen Background-Task-Record.

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, die Konfiguration und den Scheduler:

openclaw config get agents.defaults.heartbeat.every
openclaw config validate
openclaw cron status
openclaw cron list --all

Wenn kein Heartbeat beobachtbar ist, kontrolliere danach:

• Ist der Gateway aktiv?
• Ist der Automations-Scheduler aktiviert?
• Ist OPENCLAW_SKIP_CRON nicht auf 1 gesetzt?
• Erscheint der systemverwaltete Eintrag Heartbeat (agent-id) in der vollständigen Jobliste?
• Verwendest du den beabsichtigten Agent und dessen richtigen Workspace?
• Ist dort eine passende HEARTBEAT.md vorhanden?
• Ist für Benachrichtigungen ein konkreter Operator statt nur einer Wildcard-Freigabe hinterlegt?

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 und verwenden dafür ebenfalls den Automations-Scheduler.

Die robuste Aufteilung lautet: Feste Termine und getrennte Intervalle kommen in Automation-Jobs; allgemeine periodische Kontrollen übernimmt der Heartbeat. Prüfe nach jeder Änderung die gespeicherte Definition, den Scheduler-Zustand, einen tatsächlichen Lauf und das fachliche Ergebnis. 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