Scheduled tasks

Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output back to a chat channel or webhook endpoint.

# Quick start

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>

# How cron works

• Cron runs inside the Gateway process (not inside the model).
• Job definitions persist at ~/.openclaw/cron/jobs.json so restarts do not lose schedules.
• Runtime execution state persists next to it in ~/.openclaw/cron/jobs-state.json. If you track cron definitions in git, track jobs.json and gitignore jobs-state.json.
• After the split, older OpenClaw versions can read jobs.json but may treat jobs as fresh because runtime fields now live in jobs-state.json.
• When jobs.json is edited while the Gateway is running or stopped, OpenClaw compares the changed schedule fields with pending runtime slot metadata and clears stale nextRunAtMs values. Pure formatting or key-order-only rewrites preserve the pending slot.
• All cron executions create background task records.
• On Gateway startup, overdue isolated agent-turn jobs are rescheduled out of the channel-connect window instead of replaying immediately, so Discord/Telegram startup and native-command setup stay responsive after restarts.
• One-shot jobs (--at) auto-delete after success by default.
• Isolated cron runs best-effort close tracked browser tabs/processes for their cron:<jobId> session when the run completes, so detached browser automation does not leave orphaned processes behind.
• Isolated cron runs that receive the narrow cron self-cleanup grant can still read scheduler status and a self-filtered list of their current job, so status/heartbeat checks can inspect their own schedule without gaining broader cron mutation access.
• Isolated cron runs also guard against stale acknowledgement replies. If the first result is just an interim status update (on it, pulling everything together, and similar hints) and no descendant subagent run is still responsible for the final answer, OpenClaw re-prompts once for the actual result before delivery.
• Isolated cron runs prefer structured execution-denial metadata from the embedded run, then fall back to known final summary/output markers such as SYSTEM_RUN_DENIED and INVALID_REQUEST, so a blocked command is not reported as a green run.
• Isolated cron runs also treat run-level agent failures as job errors even when no reply payload is produced, so model/provider failures increment error counters and trigger failure notifications instead of clearing the job as successful.
• When an isolated agent-turn job reaches timeoutSeconds, cron aborts the underlying agent run and gives it a short cleanup window. If the run does not drain, Gateway-owned cleanup force-clears that run's session ownership before cron records the timeout, so queued chat work is not left behind a stale processing session.

# Schedule types

Timestamps without a timezone are treated as UTC. Add --tz America/New_York for local wall-clock scheduling.

Recurring top-of-hour expressions are automatically staggered by up to 5 minutes to reduce load spikes. Use --exact to force precise timing or --stagger 30s for an explicit window.

# Day-of-month and day-of-week use OR logic

Cron expressions are parsed by croner. When both the day-of-month and day-of-week fields are non-wildcard, croner matches when either field matches — not both. This is standard Vixie cron behavior.

# 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

This fires ~5–6 times per month instead of 0–1 times per month. OpenClaw uses Croner's default OR behavior here. To require both conditions, use Croner's + day-of-week modifier (0 9 15 * +1) or schedule on one field and guard the other in your job's prompt or command.

# Execution styles

# Payload options for isolated jobs

--model uses the selected allowed model as that job's primary model. It is not the same as a chat-session /model override: configured fallback chains still apply when the job primary fails. If the requested model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of silently falling back to the job's agent/default model selection.

Cron jobs can also carry payload-level fallbacks. When present, that list replaces the configured fallback chain for the job. Use fallbacks: [] in the job payload/API when you want a strict cron run that tries only the selected model. If a job has --model but neither payload nor configured fallbacks, OpenClaw passes an explicit empty fallback override so the agent primary is not appended as a hidden extra retry target.

Model-selection precedence for isolated jobs is:

1. Gmail hook model override (when the run came from Gmail and that override is allowed)
2. Per-job payload model
3. User-selected stored cron session model override
4. Agent/default model selection

Fast mode follows the resolved live selection too. If the selected model config has params.fastMode, isolated cron uses that by default. A stored session fastMode override still wins over config in either direction.

If an isolated run hits a live model-switch handoff, cron retries with the switched provider/model and persists that live selection for the active run before retrying. When the switch also carries a new auth profile, cron persists that auth profile override for the active run too. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping forever.

Before an isolated cron run enters the agent runner, OpenClaw checks reachable local provider endpoints for configured api: "ollama" and api: "openai-completions" providers whose baseUrl is loopback, private-network, or .local. If that endpoint is down, the run is recorded as skipped with a clear provider/model error instead of starting a model call. The endpoint result is cached for 5 minutes, so many due jobs using the same dead local Ollama, vLLM, SGLang, or LM Studio server share one small probe instead of creating a request storm. Skipped provider-preflight runs do not increment execution-error backoff; enable failureAlert.includeSkipped when you want repeated skip notifications.

# Delivery and output

Use --announce --channel telegram --to "-1001234567890" for channel delivery. For Telegram forum topics, use -1001234567890:topic:123; direct RPC/config callers may also pass delivery.threadId as a string or number. Slack/Discord/Mattermost targets should use explicit prefixes (channel:<id>, user:<id>). Matrix room IDs are case-sensitive; use the exact room ID or room:!room:server form from Matrix.

When announce delivery uses channel: "last" or omits channel, a provider-prefixed target such as telegram:123 can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If delivery.channel is explicit, the target prefix must name the same provider; for example, channel: "whatsapp" with to: "telegram:123" is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes such as channel:<id>, user:<id>, imessage:<handle>, and sms:<number> remain channel-owned target syntax, not provider selectors.

For isolated jobs, chat delivery is shared. If a chat route is available, the agent can use the message tool even when the job uses --no-deliver. If the agent sends to the configured/current target, OpenClaw skips the fallback announce. Otherwise announce, webhook, and none only control what the runner does with the final reply after the agent turn.

When an agent creates an isolated reminder from an active chat, OpenClaw stores the preserved live delivery target for the fallback announce route. Internal session keys may be lowercase; provider delivery targets are not reconstructed from those keys when current chat context is available.

Implicit announce delivery uses configured channel allowlists to validate and reroute stale targets. DM pairing-store approvals are not fallback automation recipients; set delivery.to or configure the channel allowFrom entry when a scheduled job should proactively send to a DM.

Failure notifications follow a separate destination path:

• cron.failureDestination sets a global default for failure notifications.
• job.delivery.failureDestination overrides that per job.
• If neither is set and the job already delivers via announce, failure notifications now fall back to that primary announce target.
• delivery.failureDestination is only supported on sessionTarget="isolated" jobs unless the primary delivery mode is webhook.
• failureAlert.includeSkipped: true opts a job or global cron alert policy into repeated skipped-run alerts. Skipped runs keep a separate consecutive skip counter, so they do not affect execution-error backoff.

# CLI examples

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 can expose HTTP webhook endpoints for external triggers. Enable in config:

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

# Authentication

Every request must include the hook token via header:

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

Query-string tokens are rejected.

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 integration

Wire Gmail inbox triggers to OpenClaw via Google PubSub.

# Wizard setup (recommended)

openclaw webhooks gmail setup --account [email protected]

This writes hooks.gmail config, enables the Gmail preset, and uses Tailscale Funnel for the push endpoint.

# Gateway auto-start

When hooks.enabled=true and hooks.gmail.account is set, the Gateway starts gog gmail watch serve on boot and auto-renews the watch. Set OPENCLAW_SKIP_GMAIL_WATCHER=1 to opt out.

# Manual one-time setup

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 model override

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

# Managing jobs

# 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

# Configuration

{
  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 limits both scheduled cron dispatch and isolated agent-turn execution. Isolated cron agent turns use the queue's dedicated cron-nested execution lane internally, so raising this value lets independent cron LLM runs progress in parallel instead of only starting their outer cron wrappers. The shared non-cron nested lane is not widened by this setting.

The runtime state sidecar is derived from cron.store: a .json store such as ~/clawd/cron/jobs.json uses ~/clawd/cron/jobs-state.json, while a store path without a .json suffix appends -state.json.

If you hand-edit jobs.json, leave jobs-state.json out of source control. OpenClaw uses that sidecar for pending slots, active markers, last-run metadata, and the schedule identity that tells the scheduler when an externally edited job needs a fresh nextRunAtMs.

Disable cron: cron.enabled: false or OPENCLAW_SKIP_CRON=1.

# Troubleshooting

# Command ladder

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

# Related

• Automation & Tasks — all automation mechanisms at a glance
• Background Tasks — task ledger for cron executions
• Heartbeat — periodic main-session turns
• Timezone — timezone configuration