Geplande taken

Cron is de ingebouwde scheduler van de Gateway. Hij bewaart taken, wekt de agent op het juiste moment en kan uitvoer terugleveren aan een chatkanaal of Webhook-eindpunt.

# Snel aan de slag

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

openclaw cron list
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

# Hoe Cron werkt

• Cron draait binnen het Gateway-proces (niet binnen het model).
• Taakdefinities blijven bewaard in ~/.openclaw/cron/jobs.json, zodat herstarts schema's niet verliezen.
• De runtime-uitvoeringsstatus blijft ernaast bewaard in ~/.openclaw/cron/jobs-state.json. Als je cron-definities in git bijhoudt, houd dan jobs.json bij en zet jobs-state.json in gitignore.
• Na de splitsing kunnen oudere OpenClaw-versies jobs.json lezen, maar ze kunnen taken als nieuw behandelen omdat runtime-velden nu in jobs-state.json staan.
• Wanneer jobs.json wordt bewerkt terwijl de Gateway draait of is gestopt, vergelijkt OpenClaw de gewijzigde schemavelden met metadata van openstaande runtime-slots en wist het verouderde nextRunAtMs-waarden. Herschrijvingen die alleen opmaak of sleutelvolgorde wijzigen, behouden de openstaande slot.
• Alle cron-uitvoeringen maken records voor achtergrondtaken aan.
• Bij het opstarten van de Gateway worden verlopen geïsoleerde agent-turn-taken opnieuw gepland buiten het kanaalverbindingsvenster in plaats van meteen opnieuw afgespeeld, zodat het opstarten van Discord/Telegram en het instellen van native opdrachten responsief blijven na herstarts.
• Eenmalige taken (--at) worden standaard automatisch verwijderd na succes.
• Geïsoleerde cron-uitvoeringen sluiten naar beste vermogen bijgehouden browsertabbladen/processen voor hun cron:<jobId>-sessie wanneer de uitvoering is voltooid, zodat losgekoppelde browserautomatisering geen verweesde processen achterlaat.
• Geïsoleerde cron-uitvoeringen die de smalle cron-zelfopruimingsmachtiging ontvangen, kunnen nog steeds scheduler-status en een zelfgefilterde lijst van hun huidige taak lezen, zodat status-/Heartbeat-controles hun eigen schema kunnen inspecteren zonder bredere cron-mutatierechten te krijgen.
• Geïsoleerde cron-uitvoeringen bewaken ook tegen verouderde bevestigingsantwoorden. Als het eerste resultaat alleen een tussentijdse statusupdate is (on it, pulling everything together en vergelijkbare hints) en geen onderliggende subagent-uitvoering nog verantwoordelijk is voor het definitieve antwoord, vraagt OpenClaw eenmaal opnieuw om het daadwerkelijke resultaat voordat dit wordt afgeleverd.
• Geïsoleerde cron-uitvoeringen geven de voorkeur aan gestructureerde metadata voor uitvoeringsweigering uit de ingebedde uitvoering en vallen daarna terug op bekende markers voor definitieve samenvatting/uitvoer, zoals SYSTEM_RUN_DENIED en INVALID_REQUEST, zodat een geblokkeerde opdracht niet als geslaagde uitvoering wordt gerapporteerd.
• Geïsoleerde cron-uitvoeringen behandelen ook agentfouten op uitvoeringsniveau als taakfouten, zelfs wanneer er geen antwoordpayload wordt geproduceerd, zodat model-/providerfouten fouttellers verhogen en foutmeldingen activeren in plaats van de taak als succesvol af te ronden.
• Wanneer een geïsoleerde agent-turn-taak timeoutSeconds bereikt, breekt Cron de onderliggende agent-uitvoering af en geeft die een kort opruimvenster. Als de uitvoering niet leegloopt, wist Gateway-beheerde opruiming geforceerd het sessie-eigendom van die uitvoering voordat Cron de timeout vastlegt, zodat wachtrijwerk in chats niet achterblijft achter een verouderde verwerkende sessie.

# Schematypen

Tijdstempels zonder tijdzone worden als UTC behandeld. Voeg --tz America/New_York toe voor planning op lokale kloktijd.

Terugkerende expressies bovenaan het uur worden automatisch met maximaal 5 minuten gespreid om belastingspieken te verminderen. Gebruik --exact om precieze timing af te dwingen of --stagger 30s voor een expliciet venster.

# Dag-van-de-maand en dag-van-de-week gebruiken OR-logica

Cron-expressies worden geparseerd door croner. Wanneer zowel de velden dag-van-de-maand als dag-van-de-week geen jokertekens zijn, matcht croner wanneer een van beide velden matcht, niet beide. Dit is standaard Vixie-cron-gedrag.

# 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

Dit vuurt ongeveer 5-6 keer per maand af in plaats van 0-1 keer per maand. OpenClaw gebruikt hier Croners standaard OR-gedrag. Gebruik Croners +-modifier voor dag-van-de-week (0 9 15 * +1) om beide voorwaarden te vereisen, of plan op één veld en bewaak het andere in de prompt of opdracht van je taak.

# Uitvoeringsstijlen

# Payloadopties voor geïsoleerde taken

--model gebruikt het geselecteerde toegestane model als het primaire model van die taak. Het is niet hetzelfde als een /model-overschrijving voor een chatsessie: geconfigureerde fallbackketens blijven van toepassing wanneer het primaire taakmodel faalt. Als het aangevraagde model niet is toegestaan of niet kan worden opgelost, laat Cron de uitvoering mislukken met een expliciete validatiefout in plaats van stil terug te vallen op de agent-/standaardmodelselectie van de taak.

Als oudere of handmatig bewerkte jobs.json-items payload.model opslaan als "default", "null", een lege tekenreeks of JSON null, voer dan openclaw doctor --fix uit. Doctor verwijdert die ongeldige bewaarde overschrijvingssentinels; runtime ondersteunt ze niet als fallback-aliassen. Laat het modelveld weg om de normale agent-/standaardmodelselectie te gebruiken.

Cron-taken kunnen ook fallbacks op payloadniveau bevatten. Wanneer die aanwezig zijn, vervangt die lijst de geconfigureerde fallbackketen voor de taak. Gebruik fallbacks: [] in de taakpayload/API wanneer je een strikte cron-uitvoering wilt die alleen het geselecteerde model probeert. Als een taak --model heeft maar geen payload- of geconfigureerde fallbacks, geeft OpenClaw een expliciete lege fallback-overschrijving door, zodat het primaire agentmodel niet als verborgen extra retrydoel wordt toegevoegd.

Modelselectieprioriteit voor geïsoleerde taken is:

1. Gmail-hookmodeloverschrijving (wanneer de uitvoering afkomstig is van Gmail en die overschrijving is toegestaan)
2. model per taakpayload
3. Door de gebruiker geselecteerde opgeslagen modeloverschrijving voor de cron-sessie
4. Agent-/standaardmodelselectie

Fast-modus volgt ook de opgeloste live selectie. Als de geselecteerde modelconfiguratie params.fastMode heeft, gebruikt geïsoleerde Cron die standaard. Een opgeslagen sessieoverschrijving voor fastMode wint nog steeds van de configuratie in beide richtingen.

Als een geïsoleerde uitvoering een live model-switch-handoff raakt, probeert Cron opnieuw met de overgeschakelde provider/het overgeschakelde model en bewaart het die live selectie voor de actieve uitvoering voordat opnieuw wordt geprobeerd. Wanneer de switch ook een nieuw auth-profiel bevat, bewaart Cron die auth-profieloverschrijving ook voor de actieve uitvoering. Retries zijn begrensd: na de eerste poging plus 2 switch-retries breekt Cron af in plaats van eindeloos te blijven lopen.

Voordat een geïsoleerde cron-uitvoering de agentrunner binnengaat, controleert OpenClaw bereikbare lokale provider-eindpunten voor geconfigureerde providers met api: "ollama" en api: "openai-completions" waarvan baseUrl local loopback, private-network of .local is. Als dat eindpunt niet beschikbaar is, wordt de uitvoering vastgelegd als skipped met een duidelijke provider-/modelfout in plaats van een modelaanroep te starten. Het eindpuntresultaat wordt 5 minuten gecachet, zodat veel vervallen taken die dezelfde defecte lokale Ollama-, vLLM-, SGLang- of LM Studio-server gebruiken één kleine probe delen in plaats van een verzoekenstorm te veroorzaken. Overgeslagen provider-preflight-uitvoeringen verhogen de backoff voor uitvoeringsfouten niet; schakel failureAlert.includeSkipped in wanneer je herhaalde skip-meldingen wilt.

# Aflevering en uitvoer

Gebruik --announce --channel telegram --to "-1001234567890" voor aflevering aan een kanaal. Gebruik voor Telegram-forumonderwerpen -1001234567890:topic:123; directe RPC-/config-aanroepers kunnen ook delivery.threadId als tekenreeks of getal doorgeven. Slack-/Discord-/Mattermost-doelen moeten expliciete prefixes gebruiken (channel:<id>, user:<id>). Matrix-room-ID's zijn hoofdlettergevoelig; gebruik het exacte room-ID of de vorm room:!room:server van Matrix.

Wanneer announce-aflevering channel: "last" gebruikt of channel weglaat, kan een doel met providerprefix zoals telegram:123 het kanaal selecteren voordat Cron terugvalt op sessiegeschiedenis of één geconfigureerd kanaal. Alleen prefixes die door de geladen Plugin worden aangekondigd, zijn providerselectoren. Als delivery.channel expliciet is, moet de doelprefix dezelfde provider noemen; bijvoorbeeld channel: "whatsapp" met to: "telegram:123" wordt geweigerd in plaats van WhatsApp de Telegram-ID als telefoonnummer te laten interpreteren. Doelsoort- en serviceprefixes zoals channel:<id>, user:<id>, imessage:<handle> en sms:<number> blijven kanaaleigen doelsyntaxis, geen providerselectoren.

Voor geïsoleerde taken wordt chataflevering gedeeld. Als er een chatroute beschikbaar is, kan de agent de tool message gebruiken, zelfs wanneer de taak --no-deliver gebruikt. Als de agent naar het geconfigureerde/huidige doel verzendt, slaat OpenClaw de fallback-announce over. Anders bepalen announce, webhook en none alleen wat de runner met het definitieve antwoord doet na de agentbeurt.

Wanneer een agent een geïsoleerde herinnering vanuit een actieve chat maakt, slaat OpenClaw het behouden live-afleverdoel op voor de fallback-announce-route. Interne sessiesleutels kunnen kleine letters bevatten; providerafleverdoelen worden niet opnieuw uit die sleutels opgebouwd wanneer de huidige chatcontext beschikbaar is.

Impliciete announce-aflevering gebruikt geconfigureerde kanaal-allowlists om verouderde doelen te valideren en om te leiden. Goedkeuringen uit de DM-pairingstore zijn geen ontvangers voor fallbackautomatisering; stel delivery.to in of configureer de kanaalvermelding allowFrom wanneer een geplande taak proactief naar een DM moet verzenden.

Foutmeldingen volgen een afzonderlijk bestemmingspad:

• cron.failureDestination stelt een globale standaard in voor foutmeldingen.
• job.delivery.failureDestination overschrijft dat per taak.
• Als geen van beide is ingesteld en de taak al via announce aflevert, vallen foutmeldingen nu terug op dat primaire announce-doel.
• delivery.failureDestination wordt alleen ondersteund voor taken met sessionTarget="isolated", tenzij de primaire aflevermodus webhook is.
• failureAlert.includeSkipped: true laat een taak of globaal Cron-waarschuwingsbeleid herhaalde waarschuwingen voor overgeslagen runs sturen. Overgeslagen runs houden een afzonderlijke teller voor opeenvolgende skips bij, zodat ze geen invloed hebben op backoff voor uitvoeringsfouten.

# CLI-voorbeelden

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

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"

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

# Webhooks

Gateway kan HTTP-Webhook-eindpunten beschikbaar maken voor externe triggers. Schakel dit in de configuratie in:

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

# Authenticatie

Elk verzoek moet het hooktoken via een header bevatten:

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

Tokens in querystrings worden geweigerd.

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"}'

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"}'

# Gmail PubSub-integratie

Verbind Gmail-inboxtriggers met OpenClaw via Google PubSub.

# Wizardconfiguratie (aanbevolen)

openclaw webhooks gmail setup --account [email protected]

Dit schrijft de hooks.gmail-configuratie, schakelt de Gmail-preset in en gebruikt Tailscale Funnel voor het push-eindpunt.

# Automatisch starten van Gateway

Wanneer hooks.enabled=true en hooks.gmail.account is ingesteld, start de Gateway gog gmail watch serve bij het opstarten en vernieuwt hij de watch automatisch. Stel OPENCLAW_SKIP_GMAIL_WATCHER=1 in om dit uit te schakelen.

# Handmatige eenmalige configuratie

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

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

# Gmail-modeloverride

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

# Taken beheren

# List all jobs
openclaw cron list

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# 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

# Configuratie

{
  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 },
  },
}

maxConcurrentRuns beperkt zowel geplande Cron-dispatch als uitvoering van geïsoleerde agentbeurten. Geïsoleerde Cron-agentbeurten gebruiken intern de speciale uitvoeringslane cron-nested van de wachtrij, dus door deze waarde te verhogen kunnen onafhankelijke Cron-LLM-runs parallel voortgang boeken in plaats van alleen hun buitenste Cron-wrappers te starten. De gedeelde niet-Cron-lane nested wordt door deze instelling niet verbreed.

De sidecar voor runtime-state wordt afgeleid van cron.store: een .json-store zoals ~/clawd/cron/jobs.json gebruikt ~/clawd/cron/jobs-state.json, terwijl een storepad zonder .json-suffix -state.json toevoegt.

Als je jobs.json handmatig bewerkt, laat jobs-state.json dan buiten bronbeheer. OpenClaw gebruikt die sidecar voor wachtende slots, actieve markeringen, metadata van de laatste run en de schema-identiteit die de scheduler vertelt wanneer een extern bewerkte taak een nieuwe nextRunAtMs nodig heeft.

Schakel Cron uit: cron.enabled: false of OPENCLAW_SKIP_CRON=1.

# Problemen oplossen

# Commandoladder

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

# Gerelateerd

• Automatisering en taken — alle automatiseringsmechanismen in één oogopslag
• Achtergrondtaken — takenlogboek voor Cron-uitvoeringen
• Heartbeat — periodieke beurten in de hoofdsessie
• Tijdzone — tijdzoneconfiguratie