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

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

Die aktuelle Dokumentation verwendet openclaw automations für den eingebauten Scheduler. openclaw cron bleibt ein Alias für dieselben Befehle. Die Beispiele in diesem Tutorial verwenden den kürzeren Cron-Namen; du kannst ihn in einer aktuellen Installation durch openclaw automations ersetzen.

Voraussetzungen prüfen

Automations laufen im Gateway-Prozess. Das Gateway muss zum geplanten Zeitpunkt aktiv sein. Ein ausgeschalteter Rechner führt einen Job nicht pünktlich aus.

Prüfe zuerst Konfiguration, Gateway und Scheduler:

openclaw config validate
openclaw config get cron.enabled
openclaw cron status
openclaw cron list

config validate sollte eine gültige Konfiguration melden. cron.enabled darf nicht false sein, wenn geplante Jobs ausgeführt werden sollen. cron status zeigt den Zustand des Schedulers, während cron list die aktiven Jobs auflistet. Wenn 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 zeigt, welche Optionen deine installierte Version akzeptiert.

Schreibende Config-Befehle funktionieren nicht, wenn OpenClaw seine Konfiguration als unveränderlich behandelt. Das gilt bei OPENCLAW_CONFIG_READONLY=1 und bei OPENCLAW_NIX_MODE=1. Lesende Befehle wie config get und config validate bleiben verfügbar. Änderungen nimmst du in diesem Fall über das System vor, das die Konfiguration verwaltet.

Einen sicheren Testjob anlegen

Beginne mit einer harmlosen Erinnerung, die zehn Minuten nach dem Anlegen lä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 der 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 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 die relative Dauer beim Erstellen in einen konkreten Zeitpunkt auf.

Die Run-Historie rufst du so ab:

openclaw cron runs <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. Automation-Ausführungen erzeugen außerdem Background-Task-Records.

Ein abgeschlossener Lauf bestätigt noch nicht, dass das fachliche Ergebnis stimmt. Prüfe deshalb auch, 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:

Position	Bedeutung
1	Minute
2	Stunde
3	Tag im Monat
4	Monat
5	Wochentag

Häufig verwendete Muster sind:

Ausdruck	Bedeutung
0 7 * * *	täglich um 07:00 Uhr
*/15 * * * *	alle 15 Minuten
0 9 * * 1-5	montags bis freitags um 09:00 Uhr
0 2 * * 0	sonntags um 02:00 Uhr

Für einen Redaktionslauf an Werktagen um 09:00 Uhr legst du Zeitplan und 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

Notiere auch hier die ausgegebene Job-ID. Prüfe zuvor mit openclaw cron create --help, ob deine Version die Optionen --cron und --tz aufführt.

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

Kontrolliere den Job anschließend:

openclaw cron show <job-id>
openclaw cron list

Die Ausgabe sollte den Cron-Ausdruck und Europe/Berlin zeigen. Falls die Nutzlast harmlos ist, kannst du den Job sofort testweise auslösen:

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

Entferne einen nicht mehr benötigten Testjob mit:

openclaw cron rm <job-id>

Heartbeats konfigurieren

Ein Heartbeat ist eine systemverwaltete Automation. Er startet periodische Agent-Turns in der Hauptsession, damit OpenClaw Routineprüfungen bündeln und bei Handlungsbedarf einen Hinweis ausgeben kann. Für Aufgaben mit einer exakten Ausführungszeit ist ein eigener Automation-Job geeigneter.

Geplante Heartbeats hängen vom Automations-Scheduler ab. Wenn cron.enabled auf false steht oder OPENCLAW_SKIP_CRON=1 in der Startumgebung des Gateways gesetzt ist, führt das Gateway keine geplanten Heartbeats aus. Manuelle und ereignisgesteuerte Heartbeat-Wakes bleiben möglich.

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 Wert. Ob anschließend tatsächlich ein Heartbeat ausgeführt wird, prüfst du getrennt.

Für jeden Heartbeat-fähigen Agent verwaltet die Runtime einen systemeigenen Automation-Job:

openclaw cron list --all

Der Eintrag trägt einen Namen nach dem Muster Heartbeat (agent-id). Bearbeite ihn nicht direkt. Die gewünschte Taktung konfigurierst du über agents.defaults.heartbeat.every oder die Heartbeat-Konfiguration des betreffenden Agents.

In einem Standard-Workspace legt OpenClaw unter anderem eine HEARTBEAT.md an. Dort beschreibst du die Checkliste. Bei einem eigenen Workspace musst du sicherstellen, dass der Agent auf den beabsichtigten Workspace zeigt und die Datei dort vorhanden ist. Mehr dazu steht in 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. Abhängig von den Tool-Berechtigungen kann ein Agent Dateien verändern, externe APIs aufrufen oder Nachrichten senden. 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.

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

Heartbeat prüfen

Kontrolliere zuerst Konfiguration und Scheduler-Eintrag:

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

Den letzten Heartbeat-Lauf zeigt die aktuelle CLI mit:

openclaw system heartbeat last

Damit trennst du drei Prüfpunkte voneinander: den gewünschten Konfigurationswert, den systemverwalteten Zeitplan und den tatsächlich zuletzt ausgeführten Heartbeat.

Fehlt der erwartete Eintrag Heartbeat (agent-id) trotz gültiger Heartbeat-Konfiguration, prüfe zunächst den allgemeinen Zustand:

openclaw doctor

Die aktuelle Dokumentation nennt openclaw doctor --fix als Reparaturweg für fehlende oder veraltete Heartbeat-Monitor-Einträge. Prüfe vor der reparierenden Variante die Ausgabe von doctor, da --fix den Runtime-Zustand verändert.

Heartbeat-Änderung zurücknehmen

Wenn vor dem Test bereits ein Wert konfiguriert war, stellst du ihn 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:

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

Um nur die wiederkehrende Heartbeat-Taktung bewusst zu deaktivieren, dokumentiert OpenClaw den Wert 0m:

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

Ereignisgesteuerte Heartbeat-Wakes können auch bei 0m weiterhin Agent-Turns auslösen. Bei einer extern verwalteten oder unveränderlichen Konfiguration nimmst du Änderung und Rückweg in der zuständigen Konfigurationsquelle vor.

Automation oder Heartbeat?

Nutze eine Automation, wenn eine Aufgabe zu einer bestimmten Uhrzeit laufen soll, einen eigenen Zeitplan benötigt oder einmalig ausgeführt werden soll. Die Run-Historie hilft bei der Kontrolle.

Ein Heartbeat passt, wenn ein Agent mehrere kleine Routineprüfungen bündeln soll und eine leichte zeitliche Abweichung akzeptabel ist. Ohne Handlungsbedarf kann der Lauf still enden. Anders als normale 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. Uhrzeitlogik innerhalb einer globalen Heartbeat-Checkliste wäre schwerer zu prüfen und zu warten.

Praxisbeispiel für einen Redaktionsbetrieb

Ein zurückhaltendes Setup verbindet einen Automation-Job für den festen Redaktionsschluss mit einem stündlichen 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. Beide Mechanismen behalten unterschiedliche Aufgaben: Der Automation-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 status
openclaw gateway status
openclaw cron status
openclaw cron list --all
openclaw cron get <job-id>
openclaw cron show <job-id>
openclaw cron runs <job-id>
openclaw config validate

Kontrolliere anschließend:

• War das Gateway zum geplanten Zeitpunkt aktiv?
• Ist cron.enabled aktiviert und OPENCLAW_SKIP_CRON nicht auf 1 gesetzt?
• Liegt ein One-shot-Zeitpunkt tatsächlich in der Zukunft?
• Enthält ein absoluter ISO-Zeitpunkt einen Offset oder Z?
• Zeigt die Jobdefinition die gewünschte IANA-Zeitzone?
• Verwendet der Cron-Ausdruck fünf Felder in der richtigen Reihenfolge?
• Kann OpenClaw den konfigurierten Agent auflösen?
• 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?
• Wurde der Lauf nur ausgeführt oder auch wie beabsichtigt zugestellt?
• Entspricht die erzeugte Ausgabe dem fachlich erwarteten Ergebnis?

Für längere Jobs kannst du mit --timeout-seconds ein Zeitbudget festlegen, sofern openclaw cron create --help diese Option in deiner Version aufführt.

Fehlersuche bei Heartbeats

Prüfe zuerst den gespeicherten Wert, den Scheduler und den letzten Lauf:

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

Wenn kein geplanter Heartbeat beobachtbar ist, kontrolliere danach:

• Ist das Gateway aktiv?
• Ist cron.enabled aktiviert?
• Ist OPENCLAW_SKIP_CRON in der Startumgebung des Gateways nicht auf 1 gesetzt?
• Erscheint 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 stattdessen ein klares Prüfkriterium, das erwartete Verhalten bei Handlungsbedarf und den Normalfall ohne Nachricht.

Wichtigste Punkte

Automations übernehmen feste, persistente und überprüfbare Zeitpläne. Heartbeats bündeln weniger zeitkritische Routineprüfungen eines Agents und verwenden dafür ebenfalls den Automations-Scheduler.

Feste Termine und unabhängige 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