Automation
Geplante Aufgaben
Cron ist der integrierte Scheduler des Gateway. Er persistiert Jobs, weckt den Agenten zum richtigen Zeitpunkt und kann Ausgaben an einen Chat-Kanal oder Webhook-Endpunkt zurückliefern.
Schnellstart
Einmalige Erinnerung hinzufügen
openclaw cron create "2026-02-01T16:00:00Z" \ --name "Reminder" \ --session main \ --system-event "Reminder: check the cron docs draft" \ --wake now \ --delete-after-runIhre Jobs prüfen
openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>Ausführungshistorie ansehen
openclaw cron runs --id <job-id>Funktionsweise von Cron
- Cron läuft innerhalb des Gateway-Prozesses (nicht innerhalb des Modells).
- Jobdefinitionen, Laufzeitstatus und Ausführungshistorie werden in der gemeinsamen SQLite-Zustandsdatenbank von OpenClaw persistiert, sodass Neustarts keine Zeitpläne verlieren.
- Führen Sie beim Upgrade
openclaw doctor --fixaus, um ältere Dateien~/.openclaw/cron/jobs.json,jobs-state.jsonundruns/*.jsonlin SQLite zu importieren und sie mit dem Suffix.migratedumzubenennen. Fehlerhafte Job-Zeilen werden zur Laufzeit übersprungen und zur späteren Reparatur oder Prüfung nachjobs-quarantine.jsonkopiert. cron.storebenennt weiterhin den logischen Cron-Store-Schlüssel und den doctor-Importpfad. Nach dem Import ändert das Bearbeiten dieser JSON-Datei keine aktiven Cron-Jobs mehr; verwenden Sie stattdessenopenclaw cron add|edit|removeoder die Cron-RPC-Methoden des Gateway.- Alle Cron-Ausführungen erstellen Datensätze für Hintergrundaufgaben.
- Beim Start des Gateway werden überfällige isolierte Agent-Turn-Jobs aus dem Kanalverbindungsfenster heraus neu geplant, statt sofort erneut abgespielt zu werden, damit Discord/Telegram-Start und native Befehlseinrichtung nach Neustarts reaktionsfähig bleiben.
- Einmalige Jobs (
--at) werden nach erfolgreicher Ausführung standardmäßig automatisch gelöscht. - Isolierte Cron-Ausführungen schließen nach bestem Aufwand nachverfolgte Browser-Tabs/-Prozesse für ihre Sitzung
cron:<jobId>, wenn die Ausführung abgeschlossen ist, damit losgelöste Browser-Automatisierung keine verwaisten Prozesse zurücklässt. - Isolierte Cron-Ausführungen, die die eingeschränkte Cron-Selbstbereinigungsberechtigung erhalten, können weiterhin den Scheduler-Status, eine selbst gefilterte Liste ihres aktuellen Jobs und die Ausführungshistorie dieses Jobs lesen, sodass Status-/Heartbeat-Prüfungen ihren eigenen Zeitplan einsehen können, ohne breiteren Zugriff auf Cron-Mutationen zu erhalten.
- Isolierte Cron-Ausführungen schützen außerdem vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur eine vorläufige Statusaktualisierung ist (
on it,pulling everything togetherund ähnliche Hinweise) und kein nachgelagerter Subagentenlauf mehr für die endgültige Antwort verantwortlich ist, fordert OpenClaw einmal erneut das eigentliche Ergebnis an, bevor es zugestellt wird. - Isolierte Cron-Ausführungen verwenden strukturierte Metadaten zu Ausführungsverweigerungen aus dem eingebetteten Lauf, einschließlich Node-Host-
UNAVAILABLE-Wrappern, deren verschachtelte Fehlermeldung mitSYSTEM_RUN_DENIEDoderINVALID_REQUESTbeginnt, sodass ein blockierter Befehl nicht als erfolgreicher Lauf gemeldet wird, während gewöhnliche Assistentenprosa nicht als Verweigerung behandelt wird. - Isolierte Cron-Ausführungen behandeln außerdem Fehler des Agenten auf Laufebene als Jobfehler, selbst wenn keine Antwortnutzlast erzeugt wird, sodass Modell-/Provider-Fehler Fehlerzähler erhöhen und Fehlerbenachrichtigungen auslösen, statt den Job als erfolgreich abzuschließen.
- Wenn ein isolierter Agent-Turn-Job
timeoutSecondserreicht, bricht Cron den zugrunde liegenden Agentenlauf ab und gibt ihm ein kurzes Bereinigungsfenster. Wenn der Lauf nicht abläuft, löscht die Gateway-eigene Bereinigung die Sitzungszuständigkeit dieses Laufs zwangsweise, bevor Cron das Timeout protokolliert, damit wartende Chat-Arbeit nicht hinter einer veralteten Verarbeitungssitzung zurückbleibt. - Wenn ein isolierter Agent-Turn vor dem Start des Runners oder vor dem ersten Modellaufruf hängen bleibt, protokolliert Cron ein phasenspezifisches Timeout wie
setup timed out before runner startoderstalled before first model call (last phase: context-engine). Diese Watchdogs decken eingebettete Provider und CLI-gestützte Provider ab, bevor deren externer CLI-Prozess tatsächlich gestartet wird, und sind unabhängig von langentimeoutSeconds-Werten begrenzt, damit Cold-Start-/Auth-/Kontextfehler schnell sichtbar werden, statt auf das gesamte Job-Budget zu warten. - Wenn Sie System-Cron oder einen anderen externen Scheduler verwenden, um
openclaw agentauszuführen, umschließen Sie ihn mit einer Hard-Kill-Eskalation, obwohl die CLISIGTERM/SIGINTverarbeitet. Gateway-gestützte Läufe bitten das Gateway, angenommene Läufe abzubrechen; lokale und eingebettete Fallback-Läufe erhalten dasselbe Abbruchsignal. Für GNUtimeoutbevorzugen Sietimeout -k 60 600 openclaw agent ...gegenüber einfachemtimeout 600 ...; der Wert-kist die Supervisor-Absicherung, falls der Prozess nicht ablaufen kann. Behalten Sie für systemd-Units dieselbe Struktur bei, indem Sie einSIGTERM-Stoppsignal plus ein Kulanzfenster wieTimeoutStopSecvor einem finalen Kill verwenden. Wenn ein Wiederholungsversuch eine--run-idwiederverwendet, während der ursprüngliche Gateway-Lauf noch aktiv ist, wird das Duplikat als laufend gemeldet, statt einen zweiten Lauf zu starten.
Zeitplantypen
| Art | CLI-Flag | Beschreibung |
|---|---|---|
at |
--at |
Einmaliger Zeitstempel (ISO 8601 oder relativ wie 20m) |
every |
--every |
Festes Intervall |
cron |
--cron |
Cron-Ausdruck mit 5 oder 6 Feldern und optionalem --tz |
Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie --tz America/New_York für lokale Wanduhr-Zeitplanung hinzu.
Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu reduzieren. Verwenden Sie --exact, um eine präzise Zeitplanung zu erzwingen, oder --stagger 30s für ein explizites Fenster.
Tag des Monats und Wochentag verwenden ODER-Logik
Cron-Ausdrücke werden von croner geparst. Wenn sowohl das Feld für den Tag des Monats als auch das Feld für den Wochentag keine Wildcards sind, stimmt croner überein, wenn eines der Felder passt, nicht beide. Dies ist standardmäßiges Vixie-Cron-Verhalten.
# 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 * 1Dies löst etwa 5- bis 6-mal pro Monat aus statt 0- bis 1-mal pro Monat. OpenClaw verwendet hier Croners standardmäßiges ODER-Verhalten. Um beide Bedingungen zu verlangen, verwenden Sie Croners Wochentagsmodifikator + (0 9 15 * +1) oder planen Sie auf einem Feld und prüfen Sie das andere in der Eingabeaufforderung oder dem Befehl Ihres Jobs.
Ausführungsstile
| Stil | --session-Wert |
Läuft in | Am besten für |
|---|---|---|---|
| Hauptsitzung | main |
Dedizierte Cron-Wake-Lane | Erinnerungen, Systemereignisse |
| Isoliert | isolated |
Dediziertes cron:<jobId> |
Berichte, Hintergrundarbeiten |
| Aktuelle Sitzung | current |
Zum Erstellungszeitpunkt gebunden | Kontextbewusste wiederkehrende Arbeit |
| Eigene Sitzung | session:custom-id |
Persistente benannte Sitzung | Workflows, die auf Historie aufbauen |
Hauptsitzung vs. isoliert vs. eigene Sitzung
Jobs der Hauptsitzung reihen ein Systemereignis in eine Cron-eigene Ausführungslane ein und wecken optional den Heartbeat (--wake now oder --wake next-heartbeat). Sie können den letzten Zustellungskontext der Ziel-Hauptsitzung für Antworten verwenden, hängen aber keine routinemäßigen Cron-Turns an die menschliche Chat-Lane an und verlängern nicht die tägliche/Leerlauf-Reset-Aktualität für die Zielsitzung. Isolierte Jobs führen einen dedizierten Agenten-Turn mit einer frischen Sitzung aus. Eigene Sitzungen (session:xxx) persistieren Kontext über Läufe hinweg und ermöglichen Workflows wie tägliche Standups, die auf vorherigen Zusammenfassungen aufbauen.
Cron-Ereignisse der Hauptsitzung sind eigenständige Systemereignis-Erinnerungen. Sie enthalten nicht automatisch die Anweisung „Read HEARTBEAT.md“ aus der Standard-Heartbeat-Eingabeaufforderung. Wenn eine wiederkehrende Erinnerung HEARTBEAT.md berücksichtigen soll, sagen Sie das ausdrücklich im Cron-Ereignistext oder in den eigenen Anweisungen des Agenten.
Was „frische Sitzung“ für isolierte Jobs bedeutet
Für isolierte Jobs bedeutet „frische Sitzung“ eine neue Transcript-/Sitzungs-ID für jeden Lauf. OpenClaw kann sichere Präferenzen wie Denk-/Schnell-/Ausführlich-Einstellungen, Labels und explizit vom Benutzer ausgewählte Modell-/Auth-Overrides übernehmen, erbt aber keinen umgebenden Konversationskontext aus einer älteren Cron-Zeile: Kanal-/Gruppenrouting, Sende- oder Warteschlangenrichtlinie, Elevation, Ursprung oder ACP-Laufzeitbindung. Verwenden Sie current oder session:<id>, wenn ein wiederkehrender Job bewusst auf demselben Konversationskontext aufbauen soll.
Laufzeitbereinigung
Für isolierte Jobs umfasst der Laufzeitabbau jetzt eine Best-Effort-Browserbereinigung für diese Cron-Sitzung. Bereinigungsfehler werden ignoriert, damit das eigentliche Cron-Ergebnis weiterhin Vorrang hat.
Isolierte Cron-Ausführungen entsorgen außerdem alle gebündelten MCP-Laufzeitinstanzen, die für den Job erstellt wurden, über den gemeinsamen Laufzeitbereinigungspfad. Dies entspricht der Art, wie MCP-Clients der Hauptsitzung und eigener Sitzungen abgebaut werden, sodass isolierte Cron-Jobs keine stdio-Kindprozesse oder langlebigen MCP-Verbindungen über Läufe hinweg leaken.
Subagenten- und Discord-Zustellung
Wenn isolierte Cron-Ausführungen Subagenten orchestrieren, bevorzugt die Zustellung außerdem die finale Ausgabe des Nachfahren gegenüber veraltetem vorläufigem Text des Elternlaufs. Wenn Nachfahren noch laufen, unterdrückt OpenClaw diese partielle Elternaktualisierung, statt sie anzukündigen.
Für reine Text-Ankündigungsziele in Discord sendet OpenClaw den kanonischen finalen Assistententext einmal, statt sowohl gestreamte/zwischenzeitliche Textnutzlasten als auch die finale Antwort erneut abzuspielen. Medien und strukturierte Discord-Nutzlasten werden weiterhin als separate Nutzlasten zugestellt, damit Anhänge und Komponenten nicht verworfen werden.
Befehlsnutzlasten
Verwenden Sie Befehlsnutzlasten für deterministische Skripte, die innerhalb des Gateway-Schedulers laufen sollen, ohne einen modellgestützten isolierten Agenten-Turn zu starten. Befehlsjobs werden auf dem Gateway-Host ausgeführt, erfassen stdout/stderr, protokollieren den Lauf in der Cron-Historie und verwenden dieselben Zustellmodi announce, webhook und none wie isolierte Jobs.
openclaw cron create "*/15 * * * *" \ --name "Queue depth probe" \ --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"]', wenn Sie eine exakte argv-Ausführung ohne Shell-Parsing wünschen. Optionale Felder --command-env KEY=VALUE, --command-input, --timeout-seconds, --no-output-timeout-seconds und --output-max-bytes steuern die Prozessumgebung, stdin und Ausgabegrenzen.
Wenn stdout nicht leer ist, ist dieser Text das zugestellte Ergebnis. Wenn stdout leer ist und stderr nicht leer ist, wird stderr zugestellt. Wenn beide Streams vorhanden sind, stellt Cron einen kleinen stdout:- / stderr:-Block zu. Ein Exit-Code von null zeichnet den Lauf als ok auf; ein Exit-Code ungleich null, ein Signal, ein Timeout oder ein Timeout wegen fehlender Ausgabe zeichnet error auf und kann Fehlerbenachrichtigungen auslösen. Ein Befehl, der nur NO_REPLY ausgibt, verwendet die normale Unterdrückung des Cron-Stille-Tokens und postet nichts zurück in den Chat.
Payload-Optionen für isolierte Jobs
--messagestringrequiredPrompt-Text (für isolierte Jobs erforderlich).
--modelstringModell-Override; verwendet das ausgewählte erlaubte Modell für den Job.
--fallbacksstringFallback-Modellliste pro Job, zum Beispiel --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5. Übergeben Sie --fallbacks "" für einen strikten Lauf ohne Fallbacks.
--clear-fallbacksbooleanEntfernt bei cron edit den Fallback-Override pro Job, sodass der Job der konfigurierten Fallback-Reihenfolge folgt. Kann nicht mit --fallbacks kombiniert werden.
--clear-modelbooleanEntfernt bei cron edit den Modell-Override pro Job, sodass der Job der normalen Cron-Reihenfolge für die Modellauswahl folgt (ein gespeicherter Cron-Session-Override, falls gesetzt, andernfalls das Agent-/Standardmodell). Kann nicht mit --model kombiniert werden.
--thinkingstringOverride für das Thinking-Level.
--clear-thinkingbooleanEntfernt bei cron edit den Thinking-Override pro Job, sodass der Job der normalen Cron-Reihenfolge für Thinking folgt. Kann nicht mit --thinking kombiniert werden.
--light-contextbooleanÜberspringt die Injektion der Workspace-Bootstrap-Datei.
--toolsstringBeschränkt, welche Tools der Job verwenden kann, zum Beispiel --tools exec,read.
--model verwendet das ausgewählte erlaubte Modell als primäres Modell dieses Jobs. Es ist nicht dasselbe wie ein /model-Override einer Chat-Session: konfigurierte Fallback-Ketten gelten weiterhin, wenn das primäre Modell des Jobs fehlschlägt. Wenn das angeforderte Modell nicht erlaubt ist oder nicht aufgelöst werden kann, lässt Cron den Lauf mit einem ausdrücklichen Validierungsfehler fehlschlagen, statt still auf die Agent-/Standardmodellauswahl des Jobs zurückzufallen.
Cron-Jobs können auch fallbacks auf Payload-Ebene enthalten. Wenn vorhanden, ersetzt diese Liste die konfigurierte Fallback-Kette für den Job. Verwenden Sie fallbacks: [] im Job-Payload/API, wenn Sie einen strikten Cron-Lauf möchten, der nur das ausgewählte Modell ausprobiert. Wenn ein Job --model, aber weder Payload- noch konfigurierte Fallbacks hat, übergibt OpenClaw einen ausdrücklichen leeren Fallback-Override, damit das primäre Agent-Modell nicht als verborgenes zusätzliches Wiederholungsziel angehängt wird.
Preflight-Prüfungen für lokale Provider durchlaufen konfigurierte Fallbacks, bevor ein Cron-Lauf als skipped markiert wird; fallbacks: [] hält diesen Preflight-Pfad strikt.
Die Reihenfolge der Modellauswahl für isolierte Jobs ist:
- Gmail-Hook-Modell-Override (wenn der Lauf von Gmail kam und dieser Override erlaubt ist)
modelim Payload pro Job- Vom Benutzer ausgewählter gespeicherter Cron-Session-Modell-Override
- Agent-/Standardmodellauswahl
Der Schnellmodus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die ausgewählte Modellkonfiguration params.fastMode hat, verwendet isolierter Cron dies standardmäßig. Ein gespeicherter Session-Override für fastMode hat weiterhin in beide Richtungen Vorrang vor der Konfiguration. Der Auto-Modus verwendet den Schwellenwert params.fastAutoOnSeconds des ausgewählten Modells, wenn vorhanden, andernfalls standardmäßig 60 Sekunden.
Wenn ein isolierter Lauf eine Live-Modellwechsel-Übergabe erreicht, wiederholt Cron den Versuch mit dem gewechselten Provider/Modell und persistiert diese Live-Auswahl vor der Wiederholung für den aktiven Lauf. Wenn der Wechsel auch ein neues Auth-Profil enthält, persistiert Cron diesen Auth-Profil-Override ebenfalls für den aktiven Lauf. Wiederholungen sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Wiederholungen bricht Cron ab, statt endlos zu schleifen.
Bevor ein isolierter Cron-Lauf den Agent-Runner erreicht, prüft OpenClaw erreichbare lokale Provider-Endpunkte für konfigurierte api: "ollama"- und api: "openai-completions"-Provider, deren baseUrl loopback, ein privates Netzwerk oder .local ist. Wenn dieser Endpunkt nicht verfügbar ist, wird der Lauf als skipped mit einem klaren Provider-/Modellfehler aufgezeichnet, statt einen Modellaufruf zu starten. Das Endpunktergebnis wird 5 Minuten lang zwischengespeichert, sodass viele fällige Jobs, die denselben nicht erreichbaren lokalen Ollama-, vLLM-, SGLang- oder LM-Studio-Server verwenden, eine kleine Prüfung teilen, statt einen Anfragesturm zu erzeugen. Übersprungene Provider-Preflight-Läufe erhöhen das Backoff für Ausführungsfehler nicht; aktivieren Sie failureAlert.includeSkipped, wenn Sie wiederholte Benachrichtigungen über Überspringungen wünschen.
Zustellung und Ausgabe
| Modus | Was passiert |
|---|---|
announce |
Stellt finalen Text per Fallback an das Ziel zu, falls der Agent nicht gesendet hat |
webhook |
POSTet Payload des abgeschlossenen Ereignisses an eine URL |
none |
Keine Fallback-Zustellung durch den Runner |
Verwenden Sie --announce --channel telegram --to "-1001234567890" für die Zustellung an einen Kanal. Für Telegram-Forenthemen verwenden Sie -1001234567890:topic:123; OpenClaw akzeptiert auch die Telegram-eigene Kurzform -1001234567890:123. Direkte RPC-/Konfigurationsaufrufer können delivery.threadId als String oder Zahl übergeben. Slack-/Discord-/Mattermost-Ziele sollten explizite Präfixe verwenden (channel:<id>, user:<id>). Matrix-Raum-IDs beachten Groß-/Kleinschreibung; verwenden Sie die exakte Raum-ID oder die Form room:!room:server aus Matrix.
Wenn die announce-Zustellung channel: "last" verwendet oder channel auslässt, kann ein Provider-präfixiertes Ziel 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 angekündigt werden, sind Provider-Selektoren. Wenn delivery.channel explizit ist, muss das Zielpräfix denselben Provider benennen; zum Beispiel wird channel: "whatsapp" mit to: "telegram:123" abgelehnt, statt WhatsApp die Telegram-ID als Telefonnummer interpretieren zu lassen. Zielart- und Dienstpräfixe wie channel:<id>, user:<id>, imessage:<handle> und sms:<number> bleiben kanaleigene Zielsyntax, keine Provider-Selektoren.
Für isolierte Jobs wird die Chat-Zustellung geteilt. Wenn eine Chat-Route verfügbar ist, kann der Agent das Tool message verwenden, auch wenn der Job --no-deliver nutzt. Wenn der Agent an das konfigurierte/aktuelle Ziel sendet, überspringt OpenClaw die Fallback-Ankündigung. Andernfalls steuern announce, webhook und none nur, was der Runner nach dem Agent-Turn mit der finalen Antwort macht.
Wenn ein Agent eine isolierte Erinnerung aus einem aktiven Chat erstellt, speichert OpenClaw das beibehaltene Live-Zustellziel für die Fallback-announce-Route. Interne Session-Schlüssel können kleingeschrieben sein; Provider-Zustellziele werden nicht aus diesen Schlüsseln rekonstruiert, wenn aktueller Chat-Kontext verfügbar ist.
Implizite announce-Zustellung verwendet konfigurierte Kanal-Allowlists, um veraltete Ziele zu validieren und umzuleiten. Genehmigungen aus dem DM-Pairing-Store sind keine Empfänger für Fallback-Automatisierung; setzen Sie delivery.to oder konfigurieren Sie den allowFrom-Eintrag des Kanals, wenn ein geplanter Job proaktiv an eine DM senden soll.
Ausgabesprache
Cron-Jobs leiten keine Antwortsprache aus Kanal, Locale oder vorherigen Nachrichten ab. Setzen Sie die Sprachregel in die geplante Nachricht oder Vorlage:
openclaw cron edit <jobId> \ --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."Bei Vorlagendateien behalten Sie die Sprachanweisung im gerenderten Prompt und
prüfen Sie, dass Platzhalter wie {{language}} ausgefüllt sind, bevor der Job läuft. Wenn
die Ausgabe Sprachen mischt, formulieren Sie die Regel ausdrücklich, zum Beispiel: "Use Chinese
for narrative text and keep technical terms in English."
Fehlerbenachrichtigungen folgen einem separaten Zielpfad:
cron.failureDestinationlegt einen globalen Standard für Fehlerbenachrichtigungen fest.job.delivery.failureDestinationüberschreibt dies pro Job.- Wenn keines von beiden gesetzt ist und der Job bereits über
announcezustellt, fallen Fehlerbenachrichtigungen jetzt auf dieses primäre announce-Ziel zurück. delivery.failureDestinationwird nur bei Jobs mitsessionTarget="isolated"unterstützt, außer der primäre Zustellmodus istwebhook.failureAlert.includeSkipped: truenimmt einen Job oder eine globale Cron-Benachrichtigungsrichtlinie in wiederholte Benachrichtigungen über übersprungene Läufe auf. Übersprungene Läufe behalten einen separaten Zähler für aufeinanderfolgende Überspringungen, sodass sie das Backoff für Ausführungsfehler nicht beeinflussen.
CLI-Beispiele
Einmalige Erinnerung
openclaw cron add \ --name "Calendar check" \ --at "20m" \ --session main \ --system-event "Next heartbeat: check calendar." \ --wake nowWiederkehrender isolierter Job
openclaw cron create "0 7 * * *" \ "Summarize overnight updates." \ --name "Morning brief" \ --tz "America/Los_Angeles" \ --session isolated \ --announce \ --channel slack \ --to "channel:C1234567890"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 \ --announceWebhook-Ausgabe
openclaw cron create "0 18 * * 1-5" \ "Summarize today's deploys as JSON." \ --name "Deploy digest" \ --webhook "https://example.invalid/openclaw/cron"Befehlsausgabe
openclaw cron create "*/15 * * * *" \ --name "Queue depth probe" \ --command "scripts/check-queue.sh" \ --command-cwd "/srv/app" \ --announce \ --channel telegram \ --to "-1001234567890"Webhooks
Gateway kann HTTP-Webhook-Endpunkte für externe Trigger bereitstellen. Aktivieren Sie dies in der Konfiguration:
{ hooks: { enabled: true, token: "shared-secret", path: "/hooks", },}Authentifizierung
Jede Anfrage muss das Hook-Token per Header enthalten:
Authorization: Bearer <token>(empfohlen)x-openclaw-token: <token>
Query-String-Token werden abgelehnt.
POST /hooks/wake
Stellt ein Systemereignis für die Haupt-Session in die Warteschlange:
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"}'textstringrequiredEreignisbeschreibung.
modestringdefault: nownow oder next-heartbeat.
POST /hooks/agent
Führt einen isolierten Agent-Turn 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"}'Felder: message (erforderlich), name, agentId, wakeMode, deliver, channel, to, model, fallbacks, thinking, timeoutSeconds.
OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJadWdlb3JkbmV0ZSBIb29rcyAoUE9TVCAvaG9va3MvPG5hbWU
)">
Benutzerdefinierte Hook-Namen werden über hooks.mappings in der Konfiguration aufgelöst. Zuordnungen können beliebige Payloads mit Vorlagen oder Code-Transformationen in wake- oder agent-Aktionen transformieren.
Gmail-PubSub-Integration
Verbinden Sie Gmail-Posteingangsauslöser über Google PubSub mit OpenClaw.
Einrichtung per Assistent (empfohlen)
openclaw webhooks gmail setup --account openclaw@gmail.comDies schreibt die hooks.gmail-Konfiguration, aktiviert die Gmail-Voreinstellung und verwendet Tailscale Funnel für den Push-Endpunkt.
Automatischer Gateway-Start
Wenn hooks.enabled=true und hooks.gmail.account gesetzt ist, startet der Gateway beim Booten gog gmail watch serve und erneuert die Watch automatisch. Setzen Sie OPENCLAW_SKIP_GMAIL_WATCHER=1, um dies zu deaktivieren.
Manuelle einmalige Einrichtung
GCP-Projekt auswählen
Wählen Sie das GCP-Projekt aus, dem der von gog verwendete OAuth-Client gehört:
gcloud auth logingcloud config set project <project-id>gcloud services enable gmail.googleapis.com pubsub.googleapis.comTopic erstellen und Gmail-Push-Zugriff gewähren
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.publisherWatch starten
gog gmail watch start \ --account openclaw@gmail.com \ --label INBOX \ --topic projects/<project-id>/topics/gog-gmail-watchGmail-Modellüberschreibung
{ hooks: { gmail: { model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", thinking: "off", }, },}Jobs verwalten
# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Force run a job now and wait for its terminal statusopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # View one exact runopenclaw cron runs --id <jobId> --run-id <runId> # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agentopenclaw cron run <jobId> kehrt zurück, nachdem der manuelle Lauf in die Warteschlange gestellt wurde. Verwenden Sie --wait für Shutdown-Hooks, Wartungsskripte oder andere Automatisierung, die blockieren muss, bis der eingereihte Lauf abgeschlossen ist. Der Wartemodus pollt die exakt zurückgegebene runId; er beendet sich mit 0 bei Status ok und mit einem Wert ungleich null bei error, skipped oder einem Warte-Timeout.
Das Agent-Tool cron gibt kompakte Job-Zusammenfassungen (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) von 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 es ausgelassen wird, bleibt die bestehende vollständige Antwort mit Zustellungsvorschauen erhalten.
openclaw cron create ist ein Alias für openclaw cron add, und neue Jobs können einen positionsbasierten Zeitplan ("0 9 * * 1", "every 1h", "20m" oder einen ISO-Zeitstempel) verwenden, gefolgt von einem positionsbasierten Agent-Prompt. Verwenden Sie --webhook <url> bei cron add|create oder cron edit, um die Nutzlast des abgeschlossenen Laufs per POST an einen HTTP-Endpunkt zu senden. Webhook-Zustellung kann nicht mit Chat-Zustellungsflags wie --announce, --channel, --to, --thread-id oder --account kombiniert werden. Bei cron edit entfernen --clear-channel, --clear-to, --clear-thread-id und --clear-account diese Routing-Felder einzeln (jeweils abgelehnt zusammen mit dem passenden Set-Flag), was sich davon unterscheidet, dass --no-deliver die Runner-Fallback-Zustellung deaktiviert.
Konfiguration
{ cron: { enabled: true, store: "~/.openclaw/cron/jobs.json", maxConcurrentRuns: 8, 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 }, },}maxConcurrentRuns begrenzt sowohl geplante Cron-Dispatches als auch die isolierte Agent-Turn-Ausführung und ist standardmäßig 8. Isolierte Cron-Agent-Turns verwenden intern die dedizierte Ausführungsspur cron-nested der Warteschlange; wenn Sie diesen Wert erhöhen, können unabhängige Cron-LLM-Läufe parallel fortschreiten, statt nur ihre äußeren Cron-Wrapper zu starten. Die gemeinsame Nicht-Cron-Spur nested wird durch diese Einstellung nicht erweitert.
cron.store ist ein logischer Store-Schlüssel und ein Legacy-Doctor-Importpfad. Führen Sie openclaw doctor --fix aus, um bestehende JSON-Stores in SQLite zu importieren und zu archivieren; zukünftige Cron-Änderungen sollten über die CLI oder Gateway-API erfolgen.
Cron deaktivieren: cron.enabled: false oder OPENCLAW_SKIP_CRON=1.
Retry-Verhalten
Einmaliger Retry: Vorübergehende Fehler (Rate Limit, Überlastung, Netzwerk, Serverfehler) werden bis zu 3 Mal mit exponentiellem Backoff erneut versucht. Dauerhafte Fehler deaktivieren sofort.
Wiederkehrender Retry: exponentieller Backoff (30s bis 60m) zwischen Retries. Der Backoff wird nach dem nächsten erfolgreichen Lauf zurückgesetzt.
Wartung
cron.sessionRetention (Standard 24h) bereinigt isolierte Run-Session-Einträge. cron.runLog.keepLines begrenzt die beibehaltenen SQLite-Run-History-Zeilen pro Job; maxBytes bleibt aus Konfigurationskompatibilität mit älteren dateibasierten Run-Logs erhalten.
Fehlerbehebung
Befehlsleiter
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctorCron wird nicht ausgelöst
- Prüfen Sie
cron.enabledund die Env-VarOPENCLAW_SKIP_CRON. - Stellen Sie sicher, dass der Gateway kontinuierlich läuft.
- Prüfen Sie bei
cron-Zeitplänen die Zeitzone (--tz) gegenüber der Host-Zeitzone. reason: not-duein der Run-Ausgabe bedeutet, dass der manuelle Lauf mitopenclaw cron run <jobId> --duegeprüft wurde und der Job noch nicht fällig war.
Cron wurde ausgelöst, aber keine Zustellung
- Der Zustellungsmodus
nonebedeutet, dass kein Runner-Fallback-Senden erwartet wird. Der Agent kann mit demmessage-Tool weiterhin direkt senden, wenn eine Chat-Route verfügbar ist. - Fehlendes/ungültiges Zustellungsziel (
channel/to) bedeutet, dass ausgehende Zustellung übersprungen wurde. - Bei Matrix können kopierte oder Legacy-Jobs mit kleingeschriebenen
delivery.to-Room-IDs fehlschlagen, weil Matrix-Room-IDs Groß-/Kleinschreibung unterscheiden. Bearbeiten Sie den Job auf den exakten Wert!room:serveroderroom:!room:serveraus Matrix. - Channel-Auth-Fehler (
unauthorized,Forbidden) bedeuten, dass die Zustellung durch Anmeldedaten blockiert wurde. - Wenn der isolierte Lauf nur das stille Token (
NO_REPLY/no_reply) zurückgibt, unterdrückt OpenClaw die direkte ausgehende Zustellung und auch den Fallback-Pfad der eingereihten Zusammenfassung, sodass nichts zurück in den Chat gepostet wird. - Wenn der Agent dem Benutzer selbst eine Nachricht senden soll, prüfen Sie, dass der Job eine nutzbare Route hat (
channel: "last"mit einem vorherigen Chat oder einen expliziten Channel/ein explizites Ziel).
Cron oder Heartbeat scheint /new-artigen Rollover zu verhindern
- Tägliche und Leerlauf-Reset-Freshness basiert nicht auf
updatedAt; siehe Sitzungsverwaltung. - Cron-Wakeups, Heartbeat-Läufe, Exec-Benachrichtigungen und Gateway-Buchführung können die Sitzungszeile für Routing/Status aktualisieren, verlängern aber weder
sessionStartedAtnochlastInteractionAt. - Für Legacy-Zeilen, die erstellt wurden, bevor diese Felder existierten, kann OpenClaw
sessionStartedAtaus dem Transcript-JSONL-Sitzungsheader wiederherstellen, wenn die Datei noch verfügbar ist. Legacy-Leerlaufzeilen ohnelastInteractionAtverwenden diese wiederhergestellte Startzeit als ihre Leerlauf-Baseline.
Zeitzonen-Fallstricke
- Cron ohne
--tzverwendet die Zeitzone des Gateway-Hosts. at-Zeitpläne ohne Zeitzone werden als UTC behandelt.- Heartbeat-
activeHoursverwendet die konfigurierte Zeitzonenauflösung.
Verwandt
- Automatisierung — alle Automatisierungsmechanismen auf einen Blick
- Hintergrundaufgaben — Task-Ledger für Cron-Ausführungen
- Heartbeat — periodische Turns der Hauptsitzung
- Zeitzone — Zeitzonenkonfiguration