cron-mastery

# Cron Mastery

**Rule #1: Heartbeats drift. Cron is precise.**

This skill provides the definitive guide for managing time in OpenClaw 2026.2.15+. It solves the "I missed my reminder" problem by enforcing a strict separation between casual checks (heartbeat) and hard schedules (cron).

## The Core Principle

| System | Behavior | Best For | Risk |
| :--- | :--- | :--- | :--- |
| **Heartbeat** | "I'll check in when I can" (e.g., every 30-60m) | Email checks, casual news summaries, low-priority polling. | **Drift:** A "remind me in 10m" task will fail if the heartbeat is 30m. |
| **Cron** | "I will run at exactly X time" | Reminders ("in 5 mins"), daily reports, system maintenance. | **Clutter:** Creates one-off jobs that need cleanup. |

## 1. Setting Reliable Reminders (2026.2.15+ Standard)

**Rule:** Never use `act:wait` or internal loops for long delays (>1 min). Use `cron:add` with a one-shot `at` schedule.

### Precision & The "Scheduler Tick"
While Cron is precise, execution depends on the **Gateway Heartbeat** (typically every 10-60s). A job set for `:00` seconds will fire on the first "tick" after that time. Expect up to ~30s of variance depending on your gateway config.

### Modern One-Shot Reminder Pattern
Use this payload structure for "remind me in X minutes" tasks. 

**Key Features (v2026.2.15+):**
- **Payload Choice:** Use **AgentTurn** with **Strict Instructions** for push notifications (reminders that ping your phone). Use **systemEvent** only for silent logs or background state updates.
- **Reliability:** `nextRunAtMs` corruption and "Add-then-Update" deadlocks are resolved.
- **Auto-Cleanup:** One-shot jobs auto-delete after success (`deleteAfterRun: true`).

**CRITICAL: Push Notifications vs. Silent Logs**

- **systemEvent (Silent):** Injects text into the chat history. Great for background logs, but **WILL NOT** ping the user's phone on Telegram/WhatsApp.
- **AgentTurn (Proactive):** Wakes an agent to deliver the message. **REQUIRED** for push no...