heartbeat-config

Heartbeat & Scheduled Tasks

When configuring scheduled tasks for OpenClaw agents, use the cron jobs system.

Cron Jobs Configuration

Scheduled tasks live in ~/.openclaw/cron/jobs.json:

{
  "version": 1,
  "jobs": [
    {
      "id": "unique-uuid",
      "agentId": "main",
      "name": "Daily Morning Report",
      "enabled": true,
      "schedule": {
        "kind": "cron",
        "expr": "0 9 * * *",
        "tz": "Europe/Istanbul"
      },
      "sessionTarget": "isolated",
      "wakeMode": "now",
      "payload": {
        "kind": "agentTurn",
        "message": "Generate the daily morning report. Include GA4 traffic, Stripe revenue, and top pages.",
        "timeoutSeconds": 120
      },
      "delivery": {
        "mode": "announce"
      }
    }
  ]
}

Common Cron Patterns

Pattern	Schedule
0 9 * * *	Every day at 9:00 AM
0 9,18 * * *	Twice daily at 9 AM and 6 PM
*/30 * * * *	Every 30 minutes
0 */2 * * *	Every 2 hours
0 9 * * 1-5	Weekdays at 9 AM
0 9 * * 1	Every Monday at 9 AM

Key Fields

• agentId: Which agent handles this job. Usually "main".
• sessionTarget: "isolated" creates a fresh session. Use this for reports.
• wakeMode: "now" triggers immediately at scheduled time.
• delivery.mode: "announce" sends output to Telegram.
• timeoutSeconds: Max execution time. 120s for reports, 60s for quick checks.

Best Practices

• Keep message payloads specific. "Generate report" is vague. "Run node tools/ga4-report.cjs and send results" is clear.
• Use "isolated" sessions for scheduled tasks so they don't pollute the main conversation.
• Set reasonable timeouts. API calls can be slow — 120s is safe for most reports.
• Always include timezone. Cron runs in UTC by default.
• Restart gateway after editing jobs.json: openclaw gateway restart

Disabling Heartbeats

To disable all scheduled tasks, set heartbeat.interval: 0 in config.json and clear jobs.json: