OpenClaw Cron Jobs: Aufgaben automatisieren in Minuten

Quick start

Hier erfährst du, wie du mit dem Gateway-Scheduler schnell deine ersten Aufgaben automatisierst.

# Add a one-shot reminder
openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

# Check your jobs
openclaw cron list

# See run history
openclaw cron runs --id <job-id>

How cron works

Cron ist direkt in den Gateway-Prozess integriert und sorgt dafür, dass deine Jobs auch nach einem Neustart zuverlässig ausgeführt werden.

• Cron läuft innerhalb des Gateway-Prozesses (nicht innerhalb des Modells).
• Job-Definitionen werden unter ~/.openclaw/cron/jobs.json gespeichert, damit Zeitpläne bei Neustarts erhalten bleiben.
• Der Laufzeitstatus wird daneben in ~/.openclaw/cron/jobs-state.json gesichert. Wenn du Cron-Definitionen in GitHub verwaltest, solltest du jobs.json tracken und jobs-state.json in die gitignore aufnehmen.
• Nach der Aufteilung können ältere OpenClaw-Versionen jobs.json zwar lesen, behandeln Jobs jedoch möglicherweise als neu, da Laufzeitfelder nun in jobs-state.json liegen.
• Alle Cron-Ausführungen erstellen Einträge für Hintergrundaufgaben.
• Einmalige Jobs (--at) werden standardmäßig nach erfolgreicher Ausführung automatisch gelöscht.
• Isolierte Cron-Läufe schließen nach Abschluss bestmöglich die verfolgten Browser-Tabs oder Prozesse für ihre cron:<jobId>-Sitzung, damit keine verwaisten Prozesse zurückbleiben.
• Isolierte Cron-Läufe schützen zudem vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur ein Zwischenstatus ist (wie „bin dran“ oder „bereite alles vor“) und kein untergeordneter Sub-Agent mehr für das Endergebnis zuständig ist, fragt OpenClaw einmalig nach dem tatsächlichen Ergebnis, bevor es ausgeliefert wird.

Die Aufgabenbereinigung für Cron liegt in der Verantwortung der Laufzeit: Ein aktiver Cron-Task bleibt so lange aktiv, wie die Cron-Laufzeit den Job als laufend führt, selbst wenn noch eine alte Kind-Sitzung existiert. Sobald die Laufzeit den Job nicht mehr verwaltet und das 5-minütige Kulanzfenster abgelaufen ist, kann die Wartung den Task als lost markieren.

Schedule types

Du kannst zwischen verschiedenen Zeitplan-Typen wählen, um deine Aufgaben präzise zu steuern.

Art	CLI-Flag	Beschreibung
at	--at	Einmaliger Zeitstempel (ISO 8601 oder relativ wie 20m)
every	--every	Festes Intervall
cron	--cron	5- oder 6-teiliger Cron-Ausdruck mit optionalem --tz

Zeitstempel ohne Zeitzone werden als UTC behandelt. Nutze --tz America/New_York für lokale Zeitplanung.

Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu vermeiden. Nutze --exact für präzises Timing oder --stagger 30s für ein explizites Zeitfenster.

Tag-des-Monats und Wochentag nutzen OR-Logik

Cron-Ausdrücke werden von croner geparst. Wenn sowohl der Tag-des-Monats als auch der Wochentag keine Platzhalter sind, greift die Regel, wenn eines der beiden Felder zutrifft – nicht beide. Dies entspricht dem Standardverhalten von Vixie-Cron.

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

Dies wird etwa 5–6 Mal pro Monat ausgelöst anstatt 0–1 Mal. OpenClaw verwendet hier das Standard-OR-Verhalten von Croner. Um beide Bedingungen zu erzwingen, nutze den + Wochentags-Modifikator von Croner (0 9 15 * +1) oder plane nach einem Feld und filtere das andere in deinem Prompt oder Befehl.

Execution styles

Wähle den passenden Ausführungsstil für deine Anforderungen, von einfachen Erinnerungen bis hin zu komplexen Workflows.

Stil	--session-Wert	Läuft in	Ideal für
Main session	main	Nächster Heartbeat-Turn	Erinnerungen, System-Events
Isolated	isolated	Dediziert cron:<jobId>	Berichte, Hintergrundaufgaben
Current session	current	Gebunden bei Erstellung	Kontextbezogene wiederkehrende Arbeit
Custom session	session:custom-id	Persistente benannte Sitzung	Workflows mit Historie

Main session-Jobs fügen ein System-Event hinzu und wecken optional den Heartbeat (--wake now oder --wake next-heartbeat). Isolated-Jobs führen einen dedizierten Agenten-Turn mit einer frischen Sitzung aus. Custom sessions (session:xxx) speichern den Kontext über Läufe hinweg, was Workflows wie tägliche Standups ermöglicht, die auf vorherigen Zusammenfassungen aufbauen.

Bei isolierten Jobs umfasst das Aufräumen der Laufzeit nun auch eine bestmögliche Browser-Bereinigung für diese Cron-Sitzung. Fehler beim Aufräumen werden ignoriert, damit das eigentliche Cron-Ergebnis gewinnt.

Wenn isolierte Cron-Läufe Sub-Agenten steuern, bevorzugt die Auslieferung ebenfalls die finale Ausgabe gegenüber veralteten Zwischentexten des übergeordneten Prozesses. Falls Unterprozesse noch laufen, unterdrückt OpenClaw das partielle Update des übergeordneten Prozesses, anstatt es anzukündigen.

Payload-Optionen für isolierte Jobs

• --message: Prompt-Text (erforderlich für isoliert)
• --model / --thinking: Überschreibungen für Modell und Thinking-Level
• --light-context: Überspringt das Einfügen der Workspace-Bootstrap-Datei
• --tools exec,read: Schränkt die verfügbaren Tools für den Job ein

--model verwendet das ausgewählte erlaubte Modell für diesen Job. Wenn das angeforderte Modell nicht erlaubt ist, protokolliert Cron eine Warnung und greift stattdessen auf die Standard-Modellauswahl des Agenten zurück. Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache Modell-Überschreibung ohne explizite pro-Job-Fallback-Liste fügt das primäre Agenten-Modell nicht mehr als zusätzlichen Retry-Zielwert hinzu.

Die Rangfolge der Modellauswahl für isolierte Jobs ist:

1. Gmail-Hook-Modell-Überschreibung (wenn der Lauf von Gmail stammt und die Überschreibung erlaubt ist)
2. Per-Job-Payload model
3. Gespeicherte Cron-Sitzungs-Modell-Überschreibung
4. Agenten-/Standard-Modellauswahl

Der Fast-Modus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die gewählte Modellkonfiguration params.fastMode enthält, verwendet isolierter Cron dies standardmäßig. Eine gespeicherte Sitzungs-Überschreibung für fastMode hat jedoch Vorrang vor der Konfiguration.

Wenn ein isolierter Lauf auf einen Live-Modellwechsel trifft, versucht Cron es erneut mit dem gewechselten Anbieter/Modell und speichert diese Live-Auswahl vor dem erneuten Versuch. Wenn der Wechsel auch ein neues Auth-Profil mit sich bringt, speichert Cron auch diese Auth-Profil-Überschreibung. Die Wiederholungsversuche sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Retries bricht Cron ab, anstatt in einer Endlosschleife zu landen.

AI Setup Assistant

Zustellung und Ausgabe

Hier erfährst du, wie OpenClaw die Ergebnisse deiner Aufgaben verarbeitet und an den gewünschten Ort übermittelt. Die folgende Tabelle gibt dir einen Überblick über die verfügbaren Modi für deine Workflows:

Modus	Was passiert
announce	Sendet eine Zusammenfassung an den Zielkanal (Standard für isolated)
webhook	Führt einen POST-Request mit dem Ergebnis-Payload an eine URL aus
none	Nur intern, keine Zustellung

Verwende —announce —channel telegram —to “-1001234567890” für die Zustellung an einen Kanal. Für Telegram-Forum-Themen nutzt du das Format -1001234567890:topic:123. Ziele wie Slack, Discord oder Mattermost benötigen explizite Präfixe wie channel:<id> oder user:<id>.

Bei isolierten Jobs, die über einen cron gesteuert werden, übernimmt der Runner den finalen Zustellungspfad. Der Agent wird dazu aufgefordert, eine Zusammenfassung als Klartext zurückzugeben, welche anschließend über announce, webhook oder intern über none verarbeitet wird. Der Befehl —no-deliver übergibt die Zustellung nicht an den Agenten zurück, sondern hält den Lauf intern.

Wenn die ursprüngliche Aufgabe explizit anweist, eine Nachricht an einen externen Empfänger zu senden, sollte der Agent in seiner Ausgabe vermerken, an wen oder wohin diese Nachricht gehen soll, anstatt zu versuchen, sie direkt zu versenden.

Fehlerbenachrichtigungen folgen einem separaten Zielpfad:

1. cron.failureDestination legt einen globalen Standard für Fehlerbenachrichtigungen fest.
2. job.delivery.failureDestination überschreibt diesen Wert für den jeweiligen Job.
3. Wenn keine der Optionen gesetzt ist und der Job bereits über announce zustellt, fallen Fehlerbenachrichtigungen auf dieses primäre Ziel zurück.
4. delivery.failureDestination wird nur bei Jobs mit sessionTarget=“isolated” unterstützt, es sei denn, der primäre Zustellungsmodus ist webhook.

CLI Beispiele

Hier siehst du, wie du OpenClaw CLI Befehle für verschiedene Szenarien einsetzt, um deine Aufgaben effizient zu verwalten.

Einmalige Erinnerung (Hauptsitzung):

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

Wiederkehrender isolierter Job mit Zustellung:

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

Isolierter Job mit Modell- und Thinking-Override:

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

AI Setup Assistant

Webhooks

Das Gateway kann HTTP-webhook-Endpunkte für externe Trigger bereitstellen. Aktiviere diese Funktion in deiner Konfiguration:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Authentifizierung

Jede Anfrage muss das hook-Token über einen Header enthalten:

1. Authorization: Bearer <token> (empfohlen)
2. x-openclaw-token: <token>

Token in der Query-String werden abgelehnt.

POST /hooks/wake

Reihe ein Systemereignis für die Hauptsitzung ein:

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

1. text (erforderlich): Beschreibung des Ereignisses
2. mode (optional): now (Standard) oder next-heartbeat

POST /hooks/agent

Führe einen isolierten Agent-Durchlauf aus:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'

Felder: message (erforderlich), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

Zugeordnete hooks (POST /hooks/<name>)

Benutzerdefinierte hook-Namen werden über hooks.mappings in der Konfiguration aufgelöst. Mappings können beliebige Payloads mithilfe von Vorlagen oder Code-Transformationen in wake- oder agent-Aktionen umwandeln.

Sicherheit

1. Halte hook-Endpunkte hinter einem Loopback, Tailnet oder einem vertrauenswürdigen Reverse Proxy.
2. Verwende ein dediziertes hook-Token; verwende keine Gateway-Authentifizierungstoken wieder.
3. Platziere hooks.path auf einem dedizierten Unterpfad; / wird abgelehnt.
4. Setze hooks.allowedAgentIds, um das explizite agentId-Routing einzuschränken.
5. Belasse hooks.allowRequestSessionKey=false, es sei denn, du benötigst vom Aufrufer gewählte Sitzungen.
6. Wenn du hooks.allowRequestSessionKey aktivierst, setze zusätzlich hooks.allowedSessionKeyPrefixes, um die erlaubten Sitzungsschlüssel-Formen zu begrenzen.
7. hook-Payloads werden standardmäßig mit Sicherheitsgrenzen umschlossen.

Gmail PubSub Integration

Verbinde Gmail-Posteingangs-Trigger mit OpenClaw über Google PubSub.

Voraussetzungen: gcloud CLI, gog (gogcli), aktivierte OpenClaw hooks, Tailscale für den öffentlichen HTTPS-Endpunkt.

Wizard-Einrichtung (empfohlen)

openclaw webhooks gmail setup --account openclaw@gmail.com

Dies schreibt die hooks.gmail-Konfiguration, aktiviert das Gmail-Preset und verwendet Tailscale Funnel für den Push-Endpunkt.

Gateway-Autostart

Wenn hooks.enabled=true und hooks.gmail.account gesetzt sind, startet das Gateway beim Booten gog gmail watch serve und erneuert die Überwachung automatisch. Setze OPENCLAW_SKIP_GMAIL_WATCHER=1, um dies zu deaktivieren.

Manuelle einmalige Einrichtung

1. Wähle das GCP-Projekt aus, das den von gog verwendeten OAuth-Client besitzt:

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

2. Erstelle ein Topic und gewähre Gmail Push-Zugriff:

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

3. Starte die Überwachung:

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Gmail Modell-Überschreibung

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Jobs verwalten

Wenn du automatisierte Abläufe in OpenClaw cron effizient steuern möchtest, kannst du die folgenden Befehle nutzen, um deine Aufgaben direkt über das CLI zu kontrollieren.

1. Liste alle vorhandenen Jobs mit openclaw cron list auf.
2. Bearbeite einen spezifischen Job mit openclaw cron edit <jobId> —message “Updated prompt” —model “opus”.
3. Starte einen Job sofort manuell mit openclaw cron run <jobId>.
4. Führe einen Job nur aus, wenn er laut Zeitplan fällig ist, indem du openclaw cron run <jobId> —due verwendest.
5. Überprüfe die Historie der letzten Ausführungen mit openclaw cron runs —id <jobId> —limit 50.
6. Entferne einen nicht mehr benötigten Job mit openclaw cron remove <jobId>.
7. Weise bei Setups mit mehreren Agenten einen Job einem bestimmten Agenten zu: *openclaw cron add —name “Ops sweep” —cron “0 6 * * ” —session isolated —message “Check ops queue” —agent ops.
8. Entferne die Agenten-Zuweisung eines Jobs mit openclaw cron edit <jobId> —clear-agent.

# List all jobs
openclaw cron list

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

Hinweis zur Modellauswahl:

• Mit openclaw cron add|edit —model … änderst du das für den Job ausgewählte Modell.
• Wenn das Modell zulässig ist, wird genau dieser Provider bzw. dieses Modell für den isolierten Agenten-Lauf verwendet.
• Ist das Modell nicht zulässig, gibt cron eine Warnung aus und greift auf die Standard-Modellauswahl des Agenten zurück.
• Konfigurierte Fallback-Ketten bleiben aktiv, aber ein einfaches —model-Override ohne explizite Fallback-Liste pro Job wird nicht mehr stillschweigend als zusätzliches Ziel für Wiederholungsversuche an den primären Agenten weitergereicht.

Konfiguration

Du kannst das Verhalten deiner Jobs über die zentrale Konfigurationsdatei anpassen, um Parameter wie Wiederholungsversuche oder Speicherorte für Logs festzulegen.

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

Der Sidecar-Prozess für den Laufzeitstatus wird von cron.store abgeleitet: Ein .json-Speicher wie ~/clawd/cron/jobs.json nutzt ~/clawd/cron/jobs-state.json, während ein Pfad ohne .json-Endung automatisch -state.json anhängt.

Um cron zu deaktivieren, setze cron.enabled: false oder verwende die Umgebungsvariable OPENCLAW_SKIP_CRON=1.

Einmalige Wiederholung: Bei vorübergehenden Fehlern (Rate Limit, Überlastung, Netzwerk, Serverfehler) erfolgen bis zu 3 Wiederholungsversuche mit exponentiellem Backoff. Dauerhafte Fehler führen zur sofortigen Deaktivierung.

Wiederkehrende Wiederholung: Hier kommt ein exponentielles Backoff (30s bis 60m) zwischen den Versuchen zum Einsatz. Das Backoff wird nach dem nächsten erfolgreichen Lauf zurückgesetzt.

Wartung: Über cron.sessionRetention (Standardwert 24h) werden Einträge isolierter Lauf-Sitzungen bereinigt. Die Parameter cron.runLog.maxBytes und cron.runLog.keepLines sorgen für die automatische Bereinigung der Log-Dateien.

Fehlerbehebung

Wenn du Probleme mit deinem Setup hast, kannst du diese Befehle nutzen, um den Status von OpenClaw zu prüfen und Fehler in deinem Gateway oder bei deinen Aufgaben zu finden.

1. Nutze die folgenden Befehle, um den Systemstatus und die Logs zu überprüfen:

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

Cron-Jobs werden nicht ausgeführt

Wenn deine geplanten Aufgaben nicht starten, liegt das meist an einer falschen Konfiguration oder einem gestoppten Dienst. Überprüfe die folgenden Punkte, um sicherzustellen, dass OpenClaw cron-Aufgaben korrekt verarbeitet:

1. Überprüfe die Umgebungsvariable cron.enabled sowie die Variable OPENCLAW_SKIP_CRON.
2. Stelle sicher, dass das Gateway durchgehend läuft.
3. Vergleiche bei cron-Zeitplänen die Zeitzone (--tz) mit der Zeitzone deines Hosts.
4. Wenn in der Ausgabe der Status reason: not-due erscheint, bedeutet das, dass der manuelle Test mit openclaw cron run <jobId> --due ergeben hat, dass der Job zum aktuellen Zeitpunkt noch nicht fällig war.

Cron-Job ausgeführt, aber keine Zustellung

Manchmal wird ein Job zwar korrekt verarbeitet, aber das Ergebnis erreicht nicht das Ziel. Prüfe diese Bedingungen, um den Fehler einzugrenzen:

1. Wenn der Zustellungsmodus auf none steht, wird keine externe Nachricht erwartet.
2. Ein fehlendes oder ungültiges Zustellungsziel (channel/to) führt dazu, dass der Versand übersprungen wird.
3. Authentifizierungsfehler des Kanals (unauthorized, Forbidden) deuten darauf hin, dass die Zustellung aufgrund ungültiger Zugangsdaten blockiert wurde.
4. Wenn ein isolierter Lauf nur das stille Token (NO_REPLY / no_reply) zurückgibt, unterdrückt OpenClaw die direkte Zustellung sowie den Fallback-Pfad für die Zusammenfassung, sodass keine Nachricht im Chat erscheint.
5. Bei isolierten Jobs, die einem cron-Job gehören, solltest du nicht erwarten, dass der Agent das Message-Tool als Fallback nutzt. Der Runner ist für die finale Zustellung verantwortlich; --no-deliver hält das Ergebnis intern, anstatt einen direkten Versand zu erlauben.

Fallstricke bei Zeitzonen

Die korrekte Einstellung der Zeit ist entscheidend für die Ausführung deiner Aufgaben. Beachte diese Details bei der Konfiguration:

1. Ein cron-Job ohne --tz verwendet automatisch die Zeitzone des Gateway-Hosts.
2. at-Zeitpläne ohne explizite Zeitzonenangabe werden standardmäßig als UTC behandelt.
3. Die activeHours des Heartbeats nutzen die konfigurierte Zeitzonenauflösung.

Verwandte Themen

Hier findest du weiterführende Informationen zu den Automatisierungsfunktionen und der Konfiguration von OpenClaw.

1. Automation & Tasks — Alle Automatisierungsmechanismen auf einen Blick.
2. Background Tasks — Aufgabenprotokoll für cron-Ausführungen.
3. Heartbeat — Periodische Hauptsitzungs-Turns.
4. Timezone — Konfiguration der Zeitzonen.

AI Setup Assistant