cron-mastery: The Definitive Guide to Scheduling in OpenClaw

With 10,800+ downloads and 104 installs, cron-mastery is the authoritative timing reference for OpenClaw. It solves one of the most common agent reliability issues: the difference between "I'll check when I can" (heartbeat) and "I will run at exactly this time" (cron) — and which one to use for each scheduling scenario.

The Problem It Solves

OpenClaw has two timing systems, and confusing them causes silent failures. The most common mistake: using heartbeat for time-sensitive reminders.

Set a reminder for "in 10 minutes" using heartbeat with a 30-minute check interval — the reminder fires 30 minutes late, or not at all if the heartbeat drifts. Ask an agent to "remind me at 3pm" and it schedules a heartbeat check — which might run at 3:28pm depending on when the last check ran.

cron-mastery teaches the distinction with a single rule:

Heartbeats drift. Cron is precise.

Core Concept

The risk with heartbeat is drift — if the heartbeat interval is 30 minutes, a "remind me in 10 minutes" task will be missed or late. The risk with cron is clutter — every one-shot reminder creates a job that needs cleanup. cron-mastery gives you patterns for both.

Deep Dive

Setting Reliable Reminders (2026.2.15+ Standard)

The skill mandates a critical rule: never use act:wait or internal loops for delays longer than 1 minute. Use cron:add with a one-shot at schedule instead.

Push Notification Reminder Pattern (AgentTurn):

{
  "name": "Remind: Water",
  "schedule": { "kind": "at", "at": "2026-02-06T01:30:00Z" },
  "payload": {
    "kind": "agentTurn",
    "message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Drink water, Momo!"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "1027899060"
  }
}

Silent Background Log (systemEvent):

{
  "name": "Log: System Pulse",
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": {
    "kind": "systemEvent",
    "text": "[PULSE] System healthy."
  },
  "sessionTarget": "main"
}

AgentTurn vs. systemEvent — Critical Distinction

This is the most important concept in the skill:

If you want a reminder to ping your phone, you must use agentTurn. A systemEvent reminder will fire, log to history, and the user will never know unless they check the chat manually.

The "Strict" prompt pattern in agentTurn prevents the AI from adding commentary:

"DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n[your message]"

Without this, the agent might say "Sure! Here's your reminder: ..." — breaking push notification formatting.

Scheduler Tick Precision

Cron is precise, but not perfectly so. Execution depends on the Gateway Heartbeat — typically every 10-60 seconds. A job set for :00 seconds fires on the first gateway tick after that time. Expect up to ~30 seconds of variance.

For most use cases (reminders, reports), this is acceptable. For sub-minute precision requirements, heartbeat is insufficient too — no OpenClaw timing system operates below ~10 second granularity.

Timezone Lock

The skill covers timezone-safe scheduling:

{
  "schedule": {
    "kind": "at",
    "at": "2026-03-17T09:00:00+08:00"
  }
}

Always include timezone offset in at schedules. ISO 8601 with explicit offset (+08:00 for China Standard Time, -05:00 for US Eastern) is unambiguous. Relying on server timezone leads to DST-related failures.

Auto-Cleanup (deleteAfterRun)

One-shot reminders should clean themselves up:

{
  "name": "One-time: Project deadline alert",
  "schedule": { "kind": "at", "at": "2026-03-20T09:00:00+08:00" },
  "deleteAfterRun": true,
  ...
}

deleteAfterRun: true removes the cron job after it fires once. Without this, you accumulate stale one-shot jobs in your cron list.

The Janitor Pattern (Legacy Maintenance)

For pre-2026.2.15 setups, manual janitor jobs cleaned up stale cron entries. As of v2026.2.14, OpenClaw's gateway handles automatic maintenance recompute — but the pattern is still needed for recurring jobs with deleteAfterRun: false:

{
  "name": "Janitor: Weekly cleanup",
  "schedule": { "kind": "every", "everyMs": 604800000 },
  "payload": {
    "kind": "systemEvent",
    "text": "Clean up stale one-shot cron jobs older than 7 days"
  },
  "sessionTarget": "main"
}

Why sessionTarget: "main"? Sub-agents (isolated) have restricted tool policies and can't call gateway or delete other cron jobs. Always target main for maintenance tasks.

Use Cases by Pattern

How to Install

clawhub install cron-mastery

No API keys required. Activates automatically when scheduling or reminder topics arise.

Practical Tips

1. Always use agentTurn for reminders that need to reach the user's phone — systemEvent is invisible unless they're looking at the chat
2. Include timezone offset in every at schedule — never rely on server timezone
3. Set deleteAfterRun: true on all one-shot jobs — prevents cron list clutter
4. Target sessionTarget: "main" for any job that needs gateway or cron access — sub-agents are restricted
5. Test with a 1-minute at schedule first — verify the full pipeline (cron fires → agent turn → notification received) before setting real deadlines

Considerations

• ~30s precision variance: Cron fires on the next gateway tick after the scheduled time. Don't use cron for sub-minute precision requirements.
• Version-specific behavior: The skill covers 2026.2.15+ semantics. If your OpenClaw gateway is older, some patterns (especially agentTurn delivery modes) may not be available.
• Cron list management: Heavy use of reminders without deleteAfterRun: true creates a growing cron list. Periodic audits with cron:list help keep it clean.

The Bigger Picture

Reliable scheduling is foundational to any agent that manages time-sensitive tasks — reminders, reports, maintenance, monitoring. cron-mastery turns OpenClaw's two timing systems from a source of confusion into a precise, well-understood toolkit. Once you internalize the heartbeat/cron distinction and the agentTurn/systemEvent distinction, you can build scheduling logic that reliably reaches users when it matters, not whenever the next heartbeat happens to fire.

View the skill on ClawHub: cron-mastery