Geplante Aufgaben

Cron ist der integrierte Scheduler des Gateways. Er speichert Jobs dauerhaft, weckt den Agent zum richtigen Zeitpunkt und kann Ausgaben an einen Chat-Kanal, einen Webhook oder an kein Ziel übermitteln.

Schnellstart

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Erinnerung" \  --session main \  --system-event "Erinnerung: Entwurf der Cron-Dokumentation prüfen" \  --wake now \  --delete-after-run

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

openclaw cron runs --id <job-id>

Funktionsweise von Cron

• Cron wird innerhalb des Gateway-Prozesses ausgeführt, nicht innerhalb des Modells. Das Gateway muss laufen, damit Zeitpläne ausgelöst werden.
• Jobdefinitionen, Laufzeitstatus und Ausführungsverlauf werden dauerhaft in der gemeinsam genutzten SQLite-Zustandsdatenbank von OpenClaw gespeichert, sodass Zeitpläne bei Neustarts nicht verloren gehen.
• Jede Cron-Ausführung erstellt einen Datensatz für eine Hintergrundaufgabe.
• Einmalige Jobs (--at) werden nach erfolgreicher Ausführung standardmäßig automatisch gelöscht; übergeben Sie --keep-after-run, um sie beizubehalten.
• Zeitbudget pro Ausführung: --timeout-seconds, sofern festgelegt. Andernfalls werden isolierte/abgekoppelte Agent-Turn-Jobs durch den eigenen 60-Minuten-Watchdog von Cron begrenzt, bevor das zugrunde liegende Agent-Turn-Zeitlimit (agents.defaults.timeoutSeconds, standardmäßig 48 Stunden) überhaupt greifen würde; Befehlsjobs haben standardmäßig ein Zeitlimit von 10 Minuten und Skript-Payloads von 5 Minuten.
• Beim Start des Gateways werden überfällige isolierte Agent-Turn-Jobs neu geplant, statt sofort erneut ausgeführt zu werden. Dadurch bleibt die Bootstrap-Arbeit für Modell und Tools außerhalb des Zeitfensters für den Kanalaufbau.
• Wenn Sie openclaw agent über System-Cron oder einen anderen externen Scheduler steuern, versehen Sie ihn mit einer Eskalation zum erzwungenen Beenden, obwohl die CLI SIGTERM/SIGINT bereits verarbeitet. Gateway-gestützte Ausführungen fordern das Gateway auf, angenommene Ausführungen abzubrechen; --local-Ausführungen erhalten dasselbe Abbruchsignal. Bevorzugen Sie bei GNU timeout timeout -k 60 600 openclaw agent ... gegenüber einfachem timeout 600 ... — der Wert -k dient als Rückfallebene, falls der Prozess nicht rechtzeitig beendet werden kann. Verwenden Sie für systemd-Units ein SIGTERM-Stoppsignal mit einem Kulanzzeitfenster (TimeoutStopSec) vor dem endgültigen Beenden. Wird eine --run-id erneut verwendet, während die ursprüngliche Gateway-Ausführung noch aktiv ist, wird das Duplikat als laufend gemeldet, statt eine zweite Ausführung zu starten.

Zeitplantypen

Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie --tz America/New_York hinzu, um ein --at-Datum mit Uhrzeit ohne Offset in dieser IANA-Zeitzone zu interpretieren oder einen Cron-Ausdruck darin auszuwerten. Cron-Ausdrücke ohne --tz verwenden die Zeitzone des Gateway-Hosts. --tz ist nicht zusammen mit --every oder --on-exit gültig.

Wiederkehrende Ausdrücke zur vollen Stunde (Minute 0 mit einem Platzhalter im Stundenfeld) werden automatisch um bis zu 5 Minuten versetzt, um Lastspitzen zu reduzieren. Verwenden Sie --exact, um eine präzise Zeitsteuerung zu erzwingen, oder --stagger 30s für ein explizites Zeitfenster (nur Cron-Zeitpläne).

Migration von Heartbeat-Aufgaben

Der ältere Heartbeat-Arbeitsbereich unterstützte einen strukturierten tasks:-Block. Führen Sie nach dem Upgrade openclaw doctor --fix aus, um jeden Eintrag in einen gewöhnlichen bearbeitbaren Cron-Job der Hauptsitzung umzuwandeln. Doctor behält das Intervall und den vorherigen Zeitpunkt der letzten Ausführung bei, erstellt die Jobs vor dem Entfernen des Blocks und führt dieselben Deklarationsschlüssel bei erneuter Ausführung sicher zusammen.

Diese migrierten Jobs verwenden öffentliche systemEvent-Payloads, sodass openclaw cron list, get, edit und remove sowie das Cron-Tool sie wie andere Jobs verwalten. Ihre Ausführung verwendet den abgesicherten Wake-Vorgang für Heartbeat-Aufgaben: Aktive Stunden, Mindestabstände, Überlastungsschutz und Wiederholungsversuche bei Auslastung gelten weiterhin, während Cron den unabhängigen Takt jeder Aufgabe steuert. Jobs, die im selben Zusammenfassungszeitfenster fällig sind, können sich einen Heartbeat-Turn teilen. Ein geplanter Termin außerhalb der aktiven Heartbeat-Zeiten wird übersprungen und beim nächsten Termin des Jobs erneut versucht.

Der Heartbeat-Arbeitsbereich enthält jetzt ausschließlich Überwachungstext. Heartbeats der Laufzeit interpretieren tasks:-Text nicht als Zeitpläne; erstellen Sie neue wiederkehrende Aufgaben mit Cron.

Stream-Quellen

Ein Stream-Zeitplan führt einen vom Operator erstellten argv-Befehl unter dem Gateway dauerhaft aus und löst den Job anhand seiner stdout- und stderr-Zeilen aus. Stream-Zeitpläne sind ereignisgesteuert, niemals zeitlich fällig und erfordern cron.triggers.enabled: true, da der langlebige Befehl derselben unbeaufsichtigten Vertrauensklasse wie Trigger-Skripte angehört. Durch Deaktivieren oder Entfernen des Jobs wird der Prozess beendet; beim Herunterfahren des Gateways wird auf den Abbau des Prozessbaums gewartet. Schnelle Fehler führen zu Neustarts mit dem integrierten Fehler-Backoff von Cron. Nach fünf aufeinanderfolgenden Ausführungen, die jeweils kürzer als 60 Sekunden dauern, verbleibt der Job in einem Fehlerstatus und verwendet den normalen Pfad für Fehlerwarnungen; aktivieren Sie den Job manuell erneut, um die Neustartbegrenzung zurückzusetzen.

openclaw cron add \  --name "Build-Ereignisstream" \  --stream-command '["node","scripts/build-events.mjs"]' \  --stream-mode match \  --stream-match '^(failed|recovered):' \  --stream-batch-ms 250 \  --session isolated \  --message "Diese Build-Ereignisse untersuchen."

mode: "line" (Standardwert) akzeptiert jede Zeile. mode: "match" akzeptiert nur Zeilen, die dem kompilierten regulären Ausdruck match entsprechen. Ein Stapel wird nach batchMs ohne Aktivität (standardmäßig 250 ms, begrenzt auf 50–5000) oder bei maxBatchBytes (standardmäßig 16384, begrenzt auf 1024–65536) geschlossen. Bei Erreichen der Bytegrenze endet der Stapel mit [truncated]. Der Übereinstimmungsmodus wertet vollständige Zeilen stets anhand ihres gesamten Textes aus, auch über maxBatchBytes hinaus (nur der übermittelte Stapel wird gekürzt); eine an der begrenzten Rohdaten-Aufnahmegrenze abgeschnittene Zeile ist lediglich ein Präfix und wird daher als nicht übereinstimmend behandelt, statt ein am Ende verankertes Muster auf dem abgeschnittenen Text auszulösen. Der Stapel wird an den Text des Systemereignisses oder die Agent-Turn-Nachricht angehängt. Befehls-Payloads werden für Stream-Zeitpläne abgelehnt, da die Prozesszuständigkeit zwischen Quellbefehl und Payload-Befehl mehrdeutig wäre.

Pro Job werden nur eine Payload-Auslösung und ein begrenzter ausstehender Stapel beibehalten. Zeilen, die während der Ausführung eines Payloads oder vor Ablauf des integrierten 30-sekündigen Trigger-Intervalls eintreffen, werden in diesem ausstehenden Stapel zusammengeführt, statt eine unbegrenzte Warteschlange aufzubauen. Eine einzelne serialisierte Instanz protokolliert durch Sperren verworfene Ausführungen, Payload-Fehler und Dispatches bei inaktiver Ausführung in streamDroppedBatches; begrenzte Zusammenführungen erhöhen streamCoalescedBatches. Fehlgeschlagene Payloads werden nicht erneut versucht, da sie möglicherweise nicht idempotent sind. Eine logische Quellidentität bleibt über Neustarts überwachter untergeordneter Prozesse hinweg stabil, wird jedoch geändert, wenn die Quelle deaktiviert, entfernt oder ersetzt wird. Dadurch können Stapel aus der ausgemusterten Quelle selbst nach einer Änderung von A zu B und zurück zu A nicht ausgelöst werden. Nach Abschluss eines Stopps bleiben verspätete Callbacks eines alten untergeordneten Prozesses wirkungslos. V1 enthält keine native WebSocket-Quelle; überbrücken Sie eine solche Quelle mit einem argv-Befehl wie websocat wss://example.invalid/events.

Wenn ein Stream-Job zusätzlich trigger.script verwendet, wird die Sperre einmal pro geschlossenem Stapel ausgeführt. Der aktuelle Stapel ist als tiefgehend eingefrorener trigger.streamBatch-String neben trigger.state verfügbar. fire: false verwirft diesen Stapel nach dem dauerhaften Speichern des Sperrstatus. fire: true behält die vorhandene Semantik der Trigger-Nachricht bei und hängt anschließend den Stapel an das resultierende Payload an. Ein Stream-Job kann stattdessen ein Skript-Payload ohne Bedingungssperre verwenden; dieses Skript empfängt den Stapel über denselben trigger.streamBatch-Wert. Die Kombination eines Skript-Payloads mit einer Bedingungssperre wird abgelehnt, da beide den dauerhaft gespeicherten trigger.state-Slot beanspruchen würden.

Dynamischer Takt (Steuerung)

Wiederkehrende Jobs können pacing.min und/oder pacing.max auf Dauerangaben wie 15m oder 4h setzen; mindestens eine Grenze ist erforderlich. Verwenden Sie --pacing-min und --pacing-max zusammen mit cron add|edit (--clear-pacing entfernt beide Grenzen).

Während eines isolierten Laufs kann ein getakteter Job das Tool cron mit action: "next_check" und in: "30m" aufrufen. Der Vorschlag gilt nur für diesen aktuell laufenden Job und wird ab dem erfolgreichen Abschluss des Laufs gemessen. OpenClaw begrenzt ihn stillschweigend auf die konfigurierten Grenzen.

Eine Taktung ohne Vorschlag lässt den normalen Zeitplan unverändert. Fehlgeschlagene, wegen Zeitüberschreitung abgebrochene und übersprungene Läufe verwerfen den Vorschlag, sodass das bestehende Wiederholungs- und Fehler-Backoff-Verhalten Vorrang hat. Das manuelle Erzwingen eines wiederkehrenden Jobs erfolgt außerhalb des regulären Ablaufs und behält dessen ausstehenden natürlichen oder getakteten Zeitpunkt bei. Bei bedingungsausgelösten Jobs bleibt das integrierte Mindestintervall auch dann eine Untergrenze, wenn ein Vorschlag eine frühere Prüfung anfordert.

Monatstag und Wochentag verwenden ODER-Logik

Cron-Ausdrücke werden von croner geparst. Wenn sowohl das Feld für den Monatstag als auch das für den Wochentag keine Platzhalter enthalten, gilt für croner eine Übereinstimmung, wenn eines der beiden Felder übereinstimmt, nicht beide. Dies entspricht dem Standardverhalten von Vixie cron.

# Beabsichtigt: „9 Uhr am 15., aber nur wenn es ein Montag ist“# Tatsächlich: „9 Uhr an jedem 15. UND 9 Uhr an jedem Montag“0 9 15 * 1

Dies wird ungefähr 5–6-mal pro Monat statt 0–1-mal pro Monat ausgelöst. Um beide Bedingungen vorauszusetzen, verwenden Sie den Wochentagsmodifikator + von croner (0 9 15 * +1) oder planen Sie nach einem Feld und prüfen Sie das andere im Prompt oder Befehl Ihres Jobs.

Ereignisauslöser (Bedingungswächter)

Ein Ereignisauslöser ergänzt einen every-, cron- oder stream-Zeitplan um ein Bedingungsskript ohne Benutzeroberfläche. Zeitpläne werten es bei Fälligkeit aus; Stream-Zeitpläne werten es für jeden abgeschlossenen Batch aus. Cron führt die normale Nutzlast nur aus, wenn das Skript fire: true zurückgibt:

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // Wird nur ausgelöst, wenn sich der beobachtete Status von der letzten Auswertung unterscheidet.    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "Untersuchen Sie die Änderung des CI-Status." },}

Das Skript muss { fire, message?, state? } zurückgeben. Der vorherige JSON-Zustand ist als tief eingefrorenes trigger.state verfügbar; Stream-Gates erhalten außerdem den aktuellen Batch als trigger.streamBatch. Geben Sie einen neuen state-Wert zurück, um ihn zu persistieren. Der Zustand ist auf 16 KB begrenzt. Wenn ein auslösendes Ergebnis message enthält, hängt Cron es vor der Ausführung an den Systemereignistext oder die Agent-Turn-Nachricht an. once: true deaktiviert den Job nach seiner ersten erfolgreich ausgelösten Nutzlast.

fire: false persistiert Auswertungszustand und Zähler und plant anschließend neu, ohne einen Verlaufseintrag für den Lauf zu erstellen. Wenn ein ausgelöster Nutzlastlauf fehlschlägt, wird das zurückgegebene state nicht persistiert – die nächste Auswertung sieht den vorherigen Zustand und kann erneut auslösen. Schreiben Sie Skripte daher als schreibgeschützte Prüfungen und belassen Sie Aktionen in der Nutzlast. Auslöserzeitpläne haben ein integriertes Mindestintervall von 30 Sekunden. Jede Auswertung verfügt über ein Echtzeitbudget von 30 Sekunden und bis zu 5 Tool-Aufrufe.

Konzipieren Sie Wächter rund um handlungsrelevante Zustände, nicht nur um Erfolg: Ein Wächter, der verstummt, wenn seine Prüfung fehlschlägt oder wegen Zeitüberschreitung abgebrochen wird, wirkt trotz seines Defekts intakt. Vergleichen Sie die Beobachtung mit trigger.state und geben Sie einen aktuellen Zustand zurück, um Duplikate zu vermeiden; verlassen Sie sich nicht auf Modell- oder Prozessspeicher. Gestalten Sie message beim Auslösen eigenständig verständlich, da es zum vollständigen Ereigniskontext des ausgelösten Laufs wird.

Erstellen Sie einen Wächter aus einer lokalen Skriptdatei (- liest das Skript von der Standardeingabe):

openclaw cron add \  --name "PR-CI-Wächter" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Reagieren Sie auf die Änderung des CI-Status" \  --session isolated

Nutzlasten

Jeder Job enthält genau eine durch ein Flag ausgewählte Nutzlastart:

Eine zusätzliche Nutzlastart, heartbeat, ist systemverwaltet: Das Gateway gleicht pro Agent mit aktiviertem Heartbeat einen Heartbeat-Überwachungsjob ab (siehe Heartbeat). Er erscheint in cron list --all, kann jedoch nicht über die CLI oder API erstellt oder bearbeitet werden. Die Heartbeat-Konfiguration wird beim Start, beim Neuladen der Konfiguration oder durch openclaw doctor --fix in den persistierten Überwachungszeitplan übertragen. Wenn Cron deaktiviert ist, wird die Überwachung nicht ausgeführt und es läuft kein ersatzweiser Heartbeat-Timer.

Agent-Turn-Optionen

Neue Jobs, die Tools ausführen können, speichern immer eine explizite Tool-Richtlinie. Von einem Agenten erstellte Jobs sind auf die Tools beschränkt, die dem erstellenden Turn zur Verfügung stehen, und der Agent kann die gespeicherte Liste nicht erweitern. Von einem authentifizierten Operator ohne --tools erstellte Jobs speichern eine uneingeschränkte *-Richtlinie; cron edit --clear-tools stellt diese explizite uneingeschränkte Richtlinie wieder her. Bestehende Jobs, die vor der Einführung expliziter Tool-Richtlinien erstellt wurden, behalten ihr aktuelles Verhalten, bis ihre Tool-Richtlinie ausdrücklich bearbeitet oder der Job neu erstellt wird.

--model legt das primäre Modell des Jobs fest; es ersetzt keine /model-Überschreibung einer Sitzung, sodass konfigurierte Fallback-Ketten weiterhin zusätzlich angewendet werden. Ein nicht auflösbares oder unzulässiges Modell lässt den Lauf mit einem ausdrücklichen Validierungsfehler fehlschlagen, statt stillschweigend auf das Standardmodell zurückzufallen. Wenn ein Job --model, aber keine explizite oder konfigurierte Fallback-Liste besitzt, übergibt OpenClaw eine leere Fallback-Überschreibung, statt das primäre Modell des Agenten stillschweigend als verborgenes Wiederholungsziel anzuhängen.

Priorität der Modellauswahl für isolierte Jobs, von der höchsten zur niedrigsten:

1. Nutzlastbezogenes model (explizite Konfiguration; ein unzulässiges Modell lässt den Lauf fehlschlagen)
2. Modellüberschreibung des Gmail-Hooks (nur wenn der Lauf von Gmail stammt und diese Überschreibung zulässig ist)
3. Vom Benutzer ausgewählte, gespeicherte Modellüberschreibung der Cron-Sitzung
4. Agenten-/Standardmodellauswahl

Der schnelle Modus folgt der aufgelösten aktuellen Auswahl. Wenn die ausgewählte Modellkonfiguration params.fastMode enthält, verwendet isoliertes Cron dies standardmäßig; eine gespeicherte fastMode-Überschreibung der Sitzung (danach ein fastModeDefault des Agenten) hat in beiden Richtungen weiterhin Vorrang vor der Modellkonfiguration. Der automatische Modus verwendet den params.fastAutoOnSeconds-Grenzwert des Modells, standardmäßig 60 Sekunden.

Wenn ein Lauf auf eine Übergabe durch einen aktuellen Modellwechsel trifft, wiederholt Cron den Versuch mit dem gewechselten Provider/Modell und persistiert diese Auswahl (sowie ein etwaiges neues Authentifizierungsprofil) für den aktiven Lauf. Wiederholungsversuche sind begrenzt: Nach dem ersten Versuch und 2 Wiederholungen aufgrund eines Wechsels bricht Cron ab, statt eine Schleife zu erzeugen.

Bevor ein isolierter Lauf beginnt, prüft OpenClaw erreichbare lokale Endpunkte für konfigurierte api: "ollama"- und api: "openai-completions"-Provider, deren baseUrl Loopback, ein privates Netzwerk oder .local ist. Diese Vorabprüfung durchläuft die konfigurierte Fallback-Kette des Jobs und markiert den Lauf erst dann als skipped, wenn alle Kandidaten nicht erreichbar sind; --fallbacks "" beschränkt diesen Durchlauf strikt auf das primäre Modell. Bei einem ausgefallenen Endpunkt wird der Lauf mit einem eindeutigen Fehler als skipped erfasst, statt einen Modellaufruf zu starten. Das Ergebnis wird pro Endpunkt (nicht pro Job oder Modell) 5 Minuten zwischengespeichert, sodass viele fällige Jobs, die denselben ausgefallenen lokalen Ollama-/vLLM-/SGLang-/LM-Studio-Server verwenden, nur eine Prüfung statt eines Anfragesturms verursachen. Durch die Vorabprüfung übersprungene Läufe erhöhen das Backoff für Ausführungsfehler nicht; setzen Sie failureAlert.includeSkipped, um wiederholte Überspringungswarnungen zu aktivieren.

Befehlsnutzlasten

Befehlsnutzlasten führen deterministische Skripte innerhalb des Gateway-Schedulers aus, ohne einen modellgestützten Turn zu starten. Sie werden auf dem Gateway-Host ausgeführt, erfassen Standardausgabe/Standardfehlerausgabe, zeichnen den Lauf im Cron-Verlauf auf und verwenden dieselben Zustellmodi announce, webhook und none wie Agent-Turn-Jobs.

openclaw cron create "*/15 * * * *" \  --name "Prüfung der Warteschlangentiefe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> speichert argv: ["sh", "-lc", <shell>]. Verwenden Sie --command-argv '["node","scripts/report.mjs"]' für die exakte Ausführung von argv ohne Shell-Parsing. Die optionalen Optionen --command-env KEY=VALUE (wiederholbar), --command-input, --timeout-seconds (standardmäßig 10 Minuten), --no-output-timeout-seconds und --output-max-bytes steuern die Prozessumgebung, die Standardeingabe und die Ausgabegrenzen.

Der zugestellte Text wird aus der Prozessausgabe abgeleitet: Eine nicht leere Standardausgabe hat Vorrang; wenn die Standardausgabe leer und die Standardfehlerausgabe nicht leer ist, wird die Standardfehlerausgabe zugestellt; wenn beide vorhanden sind, sendet Cron einen kleinen stdout:-/stderr:-Block. Der Exit-Code 0 zeichnet den Lauf als ok auf; ein von null abweichender Exit-Code, ein Signal, eine Zeitüberschreitung oder eine Zeitüberschreitung ohne Ausgabe zeichnet error auf und kann Fehlerwarnungen auslösen. Ein Befehl, der nur NO_REPLY ausgibt, verwendet die normale Cron-Unterdrückung für stille Token und sendet nichts an den Chat zurück.

Skriptnutzlasten

Skript-Payloads werden ohne Benutzeroberfläche im selben Code-Mode-Executor wie Trigger-Skripte ausgeführt, ohne einen dialogorientierten Agent-Turn zu starten. Aktivieren Sie cron.triggers.enabled, bevor Sie sie erstellen oder ausführen; diese Schutzschranke für gefährliche Automatisierung gilt sowohl für Trigger-Skripte als auch für Skript-Payloads. Skript-Jobs unterstützen nur die Session-Ziele main und isolated.

openclaw cron create "0 * * * *" \  --name "Stündliche Warteschlangenprüfung" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

Verwenden Sie --script <file|->, um JavaScript aus einer Datei oder von stdin zu lesen. Das Zeitlimit beträgt standardmäßig 300 Sekunden und ist auf 900 begrenzt; das Tool-Budget beträgt standardmäßig 50 Aufrufe und ist auf 200 begrenzt. Diese Payload-Budgets sind von den kleineren Auswertungsbudgets der Trigger-Schutzschranke getrennt.

Das Skript kann ein Objekt mit diesen optionalen Feldern zurückgeben:

• notify: Text, der über den Zustellmodus announce, webhook oder none des Jobs zugestellt wird. Wenn das Feld fehlt, wird nichts zugestellt. Bei einem main-Job wird der Text zu einem Systemereignis.
• wake: "now" fordert unmittelbar nach dem Einreihen von notify (oder eines kompakten Abschlussereignisses) einen Heartbeat an; "next-heartbeat" reiht das Ereignis für den nächsten Heartbeat ein.
• state: JSON-Zustand, auf 16 KB begrenzt und nur nach einer erfolgreichen Ausführung gespeichert. Die nächste Ausführung erhält eine unveränderliche Kopie als trigger.state, entsprechend den Trigger-Skripten. Da dieser Namensraum nur einen Besitzer für den gespeicherten Zustand hat, kann ein Skript-Payload im selben Job nicht mit einem Bedingungstrigger kombiniert werden.
• nextCheck: Eine Dauer wie "15m". Sie ist nur für Jobs mit aktivierter Taktung gültig und verwendet dieselbe Taktungsbegrenzung wie Vorschläge von Agent-Turns.

Ausnahmen, Zeitüberschreitungen, ausgeschöpfte Tool-Budgets, ungültige Ergebnisse und nextCheck ohne Taktung sind normale Cron-Ausführungsfehler: Sie werden im Ausführungsverlauf, bei der Rückstufung und bei der Behandlung von Fehlerwarnungen berücksichtigt, ohne den zurückgegebenen Zustand zu speichern.

Ausführungsarten

Zustellung und Ausgabe

Verwenden Sie --announce --channel telegram --to "-1001234567890" für die Kanalzustellung. Verwenden Sie für Telegram-Forenthemen -1001234567890:topic:123; OpenClaw akzeptiert außerdem die Telegram-eigene Kurzform -1001234567890:123. Direkte RPC-/Konfigurationsaufrufer können delivery.threadId als Zeichenfolge oder Zahl übergeben. Ziele für Slack/Discord/Mattermost verwenden explizite Präfixe (channel:<id>, user:<id>). Bei Matrix-Raum-IDs wird zwischen Groß- und Kleinschreibung unterschieden; verwenden Sie die exakte Raum-ID oder die Form room:!room:server von Matrix.

Wenn die Ankündigungszustellung channel: "last" verwendet oder channel fehlt, kann ein Ziel mit Provider-Präfix wie telegram:123 den Kanal auswählen, bevor Cron auf den Session-Verlauf oder einen einzelnen konfigurierten Kanal zurückfällt. Nur Präfixe, die vom geladenen Plugin ausgewiesen werden, dienen als Provider-Selektoren. Wenn delivery.channel explizit angegeben ist, muss das Zielpräfix denselben Provider benennen; channel: "whatsapp" mit to: "telegram:123" wird abgelehnt, statt WhatsApp die Telegram-ID als Telefonnummer interpretieren zu lassen. Präfixe für Zielart und Dienst (channel:<id>, user:<id>, imessage:<handle>, sms:<number>) bleiben kanaleigene Zielsyntax und sind keine Provider-Selektoren.

Bei isolierten Jobs wird die Chat-Zustellung gemeinsam genutzt: Wenn eine Chat-Route verfügbar ist, kann der Agent das Tool message auch mit --no-deliver verwenden. Wenn der Agent an das konfigurierte/aktuelle Ziel sendet, überspringt OpenClaw die ersatzweise Ankündigung. Andernfalls steuern announce, webhook und none lediglich, wie der Runner nach dem Agent-Turn mit der endgültigen Antwort verfährt.

Wenn ein Agent aus einem aktiven Chat eine isolierte Erinnerung erstellt, speichert OpenClaw das erhaltene aktive Zustellziel für die ersatzweise Ankündigungsroute. Interne Session-Schlüssel können kleingeschrieben sein; Provider-Zustellziele werden nicht aus diesen Schlüsseln rekonstruiert, wenn der aktuelle Chat-Kontext verfügbar ist.

Die implizite Ankündigungszustellung verwendet konfigurierte Kanal-Zulassungslisten, um veraltete Ziele zu validieren und umzuleiten. Genehmigungen aus dem DM-Kopplungsspeicher sind keine Empfänger für ersatzweise Automatisierung; legen Sie delivery.to fest oder konfigurieren Sie den Kanaleintrag allowFrom, wenn ein geplanter Job proaktiv an eine DM senden soll.

Fehlerbenachrichtigungen

Fehlerbenachrichtigungen verwenden einen separaten Zielpfad:

• cron.failureDestination legt einen globalen Standard für Fehlerbenachrichtigungen fest.
• job.delivery.failureDestination überschreibt diesen pro Job.
• Wenn keiner von beiden festgelegt ist und der Job bereits über announce zustellt, greifen Fehlerbenachrichtigungen auf dieses primäre Ankündigungsziel zurück.
• delivery.failureDestination wird nur für sessionTarget="isolated"-Jobs unterstützt, sofern der primäre Zustellmodus nicht webhook ist.
• failureAlert.includeSkipped: true aktiviert für einen Job oder die globale Cron-Warnrichtlinie wiederholte Warnungen bei übersprungenen Ausführungen. Übersprungene Ausführungen verwenden einen separaten Zähler für aufeinanderfolgende Überspringungen und wirken sich daher nicht auf die Rückstufung bei Ausführungsfehlern aus.
• openclaw cron edit stellt die Warnkonfiguration pro Job bereit: --failure-alert/--no-failure-alert, --failure-alert-after <n>, --failure-alert-channel, --failure-alert-to, --failure-alert-cooldown, --failure-alert-include-skipped/--failure-alert-exclude-skipped, --failure-alert-mode und --failure-alert-account-id.

Ausgabesprache

Cron-Jobs leiten die Sprache einer Antwort nicht aus dem Kanal, dem Gebietsschema oder vorherigen Nachrichten ab. Fügen Sie die Sprachregel in die geplante Nachricht oder Vorlage ein:

openclaw cron edit <jobId> \  --message "Fassen Sie die Aktualisierungen zusammen. Antworten Sie auf Chinesisch; lassen Sie URLs, Code und Produktnamen unverändert."

Belassen Sie bei Vorlagendateien die Sprachanweisung im gerenderten Prompt und prüfen Sie vor der Ausführung des Jobs, ob Platzhalter wie {{language}} ausgefüllt sind. Falls die Ausgabe mehrere Sprachen vermischt, formulieren Sie die Regel ausdrücklich, beispielsweise: „Verwenden Sie Chinesisch für Fließtext und belassen Sie technische Begriffe auf Englisch.“

CLI-Beispiele

openclaw cron add \  --name "Kalenderprüfung" \  --at "20m" \  --session main \  --system-event "Nächster Heartbeat: Kalender prüfen." \  --wake now

openclaw cron create "0 7 * * *" \  "Fassen Sie die Aktualisierungen über Nacht zusammen." \  --name "Morgenübersicht" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "Tiefgehende Analyse" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Wöchentliche tiefgehende Analyse des Projektfortschritts." \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "Fassen Sie die heutigen Bereitstellungen als JSON zusammen." \  --name "Bereitstellungsübersicht" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "Prüfung der Warteschlangentiefe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

Jobs verwalten

# Aktivierte Jobs auflistenopenclaw cron list # Deaktivierte Jobs einschließenopenclaw cron list --all # Einen gespeicherten Job als JSON abrufenopenclaw cron get <jobId> # Einen Job einschließlich der aufgelösten Zustellroute anzeigenopenclaw cron show <jobId> # Aktivieren/deaktivieren, ohne zu löschenopenclaw cron enable <jobId>openclaw cron disable <jobId> # Einen Job bearbeitenopenclaw cron edit <jobId> --message "Aktualisierter Prompt" --model "opus" # Einen Job jetzt zwangsweise ausführenopenclaw cron run <jobId> # Einen Job jetzt zwangsweise ausführen und auf seinen Endstatus wartenopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Nur ausführen, wenn der Job fällig istopenclaw cron run <jobId> --due # Ausführungsverlauf anzeigenopenclaw cron runs --id <jobId> --limit 50 # Eine bestimmte Ausführung anzeigenopenclaw cron runs --id <jobId> --run-id <runId> # Einen Job löschenopenclaw cron remove <jobId> # Agentenauswahl (Multi-Agent-Konfigurationen)openclaw cron create "0 6 * * *" "Betriebswarteschlange prüfen" --name "Betriebsprüfung" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

Das Archivieren einer Sitzung (Control UI oder sessions.patch { archived: true } durch einen Aufrufer mit Operator-Administratorrechten) deaktiviert jeden aktivierten Cron-Job, der an diese Sitzung gebunden ist: ihre isolierte cron:<jobId>-Sitzung, ein session:<key>-Ziel oder eine sessionKey-Spur für Zustellung/Aktivierung. Durch das Wiederherstellen der Sitzung werden diese Jobs nicht erneut aktiviert; verwenden Sie openclaw cron enable <jobId>. Sitzungen mit einem aktivierten gebundenen Job zeigen in der Seitenleiste der Control UI ein Uhrsymbol an.

openclaw cron run <jobId> kehrt nach dem Einreihen der manuellen Ausführung zurück. Verwenden Sie --wait für Hooks beim Herunterfahren, Wartungsskripte oder andere Automatisierungen, die blockieren müssen, bis die eingereihte Ausführung abgeschlossen ist. Der zurückgegebene runId wird dabei abgefragt (Standard-Zeitüberschreitung 10m, Abfrageintervall 2s). Der Befehl wird für den Status ok mit 0 beendet und für error, skipped oder eine Wartezeitüberschreitung mit einem von null verschiedenen Wert.

Das Agentenwerkzeug cron gibt kompakte Jobzusammenfassungen (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) aus cron(action: "list") zurück; verwenden Sie cron(action: "get", jobId: "...") für eine vollständige Jobdefinition. Direkte Gateway-Aufrufer können compact: true an cron.list übergeben; wenn dieser Wert weggelassen wird, bleibt die vollständige Antwort mit Zustellvorschauen erhalten.

openclaw cron create ist ein Alias für openclaw cron add. Neue Jobs können einen positionellen Zeitplan ("0 9 * * 1", "every 1h", "20m" oder einen ISO-Zeitstempel) verwenden, gefolgt von einem positionellen Agenten-Prompt. Verwenden Sie --webhook <url> mit cron add|create oder cron edit, um die Nutzlast der abgeschlossenen Ausführung per POST an einen HTTP-Endpunkt zu senden. Die Webhook-Zustellung kann nicht mit Chat-Zustellungsflags (--announce, --channel, --to, --thread-id, --account) kombiniert werden. Bei cron edit, --clear-channel, --clear-to, --clear-thread-id und --clear-account werden diese Routingfelder einzeln entfernt (jedes wird zusammen mit dem zugehörigen Setz-Flag abgelehnt) – im Unterschied zu --no-deliver, das nur die Fallback-Zustellung des Runners deaktiviert.

Webhooks

Das Gateway kann HTTP-Webhook-Endpunkte für externe Auslöser bereitstellen. Aktivieren Sie sie in der Konfiguration:

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

Authentifizierung

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

• Authorization: Bearer <token> (empfohlen)
• x-openclaw-token: <token>

Tokens in Abfragezeichenfolgen werden abgelehnt.

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

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Posteingang zusammenfassen","name":"E-Mail","model":"openai/gpt-5.6-sol"}'

Gmail-PubSub-Integration

Verbinden Sie Gmail-Posteingangsauslöser über Google PubSub mit OpenClaw.

Einrichtung mit dem Assistenten (empfohlen)

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

Dadurch wird die hooks.gmail-Konfiguration geschrieben, die Gmail-Voreinstellung aktiviert und standardmäßig Tailscale Funnel für den Push-Endpunkt (--tailscale funnel|serve|off) verwendet.

Automatischer Start des Gateways

Wenn hooks.enabled=true und hooks.gmail.account festgelegt sind, startet das Gateway beim Hochfahren gog gmail watch serve und erneuert die Überwachung automatisch. Legen Sie OPENCLAW_SKIP_GMAIL_WATCHER=1 fest, um dies zu deaktivieren.

Einmalige manuelle Einrichtung

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

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

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

Gmail-Modellüberschreibung

{  hooks: {    gmail: {      model: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

Verwenden Sie für nicht vertrauenswürdige Posteingänge das verfügbare Modell der neuesten Generation und besten Stufe Ihres Providers. Der obige Wert ist ein Beispiel; das Modell muss in Ihrem konfigurierten Katalog und Ihrer Zulassungsliste vorhanden sein.

Konfiguration

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken wird bei Cron-Webhook-POSTs als Authorization: Bearer <token> gesendet.

cron.store ist ein logischer Speicherschlüssel und ein Doctor-Migrationspfad, keine aktive JSON-Datei zur manuellen Bearbeitung. Jobdaten befinden sich in SQLite; verwenden Sie für Änderungen die CLI oder die Gateway-API.

Cron deaktivieren: cron.enabled: false oder OPENCLAW_SKIP_CRON=1.

Fehlerbehebung

Befehlsfolge

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Verwandte Themen

• Automatisierung — alle Automatisierungsmechanismen auf einen Blick
• Hintergrundaufgaben — Aufgabenprotokoll für Cron-Ausführungen
• Heartbeat — regelmäßige Durchläufe der Hauptsitzung
• Zeitzone — Zeitzonenkonfiguration