cron-mastery✓ Pass

SKILL.md Content

---
name: cron-mastery
description: Master OpenClaw's timing systems. Use for scheduling reliable reminders, setting up periodic maintenance (janitor jobs), and understanding when to use Cron vs Heartbeat for time-sensitive tasks.
---

# Cron Mastery

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

This skill provides the definitive guide for managing time in OpenClaw. 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

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

### Standard Reminder Pattern (JSON)

Use this payload structure for "remind me in X minutes" tasks:

```json
{
  "name": "Remind: Drink Water",
  "schedule": {
    "kind": "at",
    "atMs": <CURRENT_MS + DELAY_MS>
  },
  "payload": {
    "kind": "agentTurn",
    "message": "⏰ Reminder: Drink water!",
    "deliver": true
  },
```  

*Note: Even with `wakeMode: "next-heartbeat"`, the cron system forces an event injection at `atMs`. Use `mode: "now"` in the `cron:wake` tool if you need to force an immediate wake outside of a job payload.*

### ⚠️ The Delivery Rule (CRITICAL)
When scheduling an `agentTurn` via Cron that is meant to provide an update to the user:
- **ALWAYS** set `"deliver": true` in the payload.
- Without `"deliver": true`, the sub-agent will run the task but the output will NEVER be seen by the human. It will be "talking in a dark room."

## 2. The Janitor (Auto-Cleanup)

One-shot cron jobs (kind: `at`) disable themselves after running but stay in the list as "ghosts" (`enabled: false`, `lastStatus: ok`). To prevent clutter, install the **Daily Janitor**.

### Setup Instructions

1.  **Check current jobs:** `cron:list` (includeDisabled: true)
2.  **Create the Janitor:**
    *   **Name:** `Daily Cron Cleanup`
    *   **Schedule:** Every 24 hours (`everyMs: 86400000`)
    *   **Payload:** An agent turn that runs a specific prompt.

### The Janitor Prompt (Agent Turn)

> "Time for the 24-hour cron sweep. List all cron jobs including disabled ones. If you find any jobs that are `enabled: false` and have `lastStatus: ok` (finished one-shots), delete them to keep the list clean. Do not delete active recurring jobs. Log what you deleted."

## 3. Reference: Timezone Lock

For cron to work, the agent **must** know its time.
*   **Action:** Add the user's timezone to `MEMORY.md`.
*   **Example:** `Timezone: Cairo (GMT+2)`
*   **Validation:** If a user says "remind me at 9 PM," confirm: "9 PM Cairo time?" before scheduling.

## 4. The Self-Wake Rule (Behavioral)

**Problem:** If you say "I'll wait 30 seconds" and end your turn, you go to sleep. You cannot wake up without an event.
**Solution:** If you need to "wait" across turns, you **MUST** schedule a Cron job.

*   **Wait < 1 minute (interactive):** Only allowed if you keep the tool loop open (using `act:wait`).
*   **Wait > 1 minute (async):** Use Cron with `wakeMode: "now"`.

**Example Payload for "Checking back in 30s":**
```json
{
  "schedule": { "kind": "at", "atMs": <NOW + 30000> },
  "payload": { "kind": "agentTurn", "message": "⏱️ 30s check-in. Report status." },
  "wakeMode": "now"
}
```

## Troubleshooting

*   **"My reminder didn't fire":** Check `cron:list`. If the job exists but didn't fire, check the system clock vs `atMs`.
*   **"I have 50 old jobs":** Run the Janitor manually immediately.

License

Declared license: MIT

MIT License

Copyright (c) 2026 openclaw

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.