Gateway Crons

OpenClaw's built-in cron system spawns isolated agent sessions on a schedule. Each run is a full agentTurn — the agent wakes up, reads its context, does work, and exits.

Configuration

{
  "name": "email-monitor",
  "schedule": { "kind": "cron", "expr": "*/15 * * * *" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "model": "sonnet",
    "message": "Check email for anything requiring attention. Report findings to #ops."
  },
  "delivery": { "mode": "announce" }
}

Key fields:

• schedule.kind — "cron" (cron expression), "every" (fixed interval in ms), or "at" (one-shot)
• sessionTarget — Always "isolated" for background jobs (spins up a fresh session)
• payload.model — Match model to task complexity (see below)
• delivery.mode — "announce" sends results to the configured channel

Circuit Breaker Protocol

Crons fail — API outages, rate limits, transient errors. Without a circuit breaker, a failing cron burns tokens retrying something that won't work.

CLOSED (normal) ──[failure]──→ OPEN (disabled)
                                    │
                              [cooldown expires]
                                    │
                                    ▼
                              HALF-OPEN (test)
                                ├─ success → CLOSED
                                └─ failure → OPEN (longer cooldown)

In practice:

1. CLOSED — Normal operation.
2. On failure — Log in daily note. Increment failure counter.
3. 3+ consecutive failures → OPEN — Stop retrying. Alert the operator.
4. After cooldown → HALF-OPEN — Try once. Success → CLOSED. Failure → OPEN with longer cooldown.

Key insight: Stateless agents can't count consecutive failures across runs. Circuit breaker state needs to live in a file (memory/cron-health.json) that the cron reads at the start of each run.

Light Context Mode

Gateway crons inject the full workspace context (AGENTS.md, SOUL.md, TOOLS.md, etc.) on every run. For mechanical crons that don't need personality or complex rules, this wastes 10,000–15,000 tokens per run.

Light context mode skips workspace file injection:

{
  "payload": {
    "kind": "agentTurn",
    "model": "haiku",
    "lightContext": true,
    "message": "Check if there are new emails. If yes, summarize. If no, reply NO_REPLY."
  }
}

Use light context when:

• The prompt is self-contained (no references to standing orders)
• The task is mechanical (check → report)
• The cron runs frequently (savings compound)

Don't use when:

• The task requires voice or judgment (governance, social)
• Standing orders in AGENTS.md affect the task
• The agent needs learned patterns from SOUL.md

See Light Context Mode for full details, migration checklist, and cost impact tables.

Model Selection for Crons

Not every cron needs your best model:

Task type	Model	Example
Check-and-report	Haiku / Flash	Email polling, API health
Analyze-and-summarize	Sonnet	Morning briefing, opportunity scanning
Judge-and-act	Opus	Governance voting, complex decision-making

For crons where most runs find nothing, use the scout/dispatch pattern — cheap model scans, expensive model only runs when there's work.

The "Script + Cron = System" Lesson

A script without a cron is a tool, not automation. Every automation project needs two answers:

1. What does it do? (the script/prompt)
2. When does it run? (the schedule)

If you've built the script but haven't scheduled it, you've done half the work. Conversely, a cron without error handling is a time bomb — it fails silently, you assume it's running, and you discover the gap weeks later.

Automation that breaks and stays broken is worse than no automation, because you assume coverage you don't have.