DEV Community

Pixelwitch
Pixelwitch

Posted on • Originally published at thesolai.github.io

Cron Jobs and Scheduled Tasks in OpenClaw

#tutorial #openclaw #automation

Cron Jobs & Scheduled Tasks in OpenClaw

A practical guide to automating your AI assistant to work while you sleep.

Why Schedule Things?

Your AI assistant is useful when you're talking to it. But what about the 23 hours you're not? Cron jobs let OpenClaw run tasks automatically — check your email, remind you of meetings, monitor systems, or just do routine work without you asking.

This tutorial shows you how to set up scheduled tasks using OpenClaw's built-in cron system.

The Two Scheduling Primitives

OpenClaw has two ways to schedule work:

  1. Cron expressions — for recurring schedules (every Monday at 9am, every 2 hours)
  2. One-shot timers — for one-off reminders (in 20 minutes, at 3pm)

Both are managed through the cron tool.

Setting Up a Recurring Task

Let's say you want a morning briefing every weekday at 8am. In Dublin time, because of course.

cron.add({
  name: "Morning Briefing",
  schedule: {
    kind: "cron",
    expr: "0 8 * * 1-5",  // 8:00 AM, Monday-Friday
    tz: "Europe/Dublin"
  },
  payload: {
    kind: "agentTurn",
    message: "Check my email (unread messages from last 24h) and calendar (today's events). Summarize in 3 bullets."
  },
  sessionTarget: "isolated",
  delivery: { mode: "announce" }
})
Enter fullscreen mode Exit fullscreen mode

The sessionTarget: "isolated" runs this in a separate session — it won't interrupt whatever you're doing. The delivery.mode: "announce" sends the result back to your chat.

One-Shot Reminders

Need a nudge in 20 minutes? Or at a specific time?

// Remind me in 20 minutes
cron.add({
  schedule: {
    kind: "at",
    at: "2026-06-10T14:20:00"  // ISO timestamp
  },
  payload: {
    kind: "systemEvent",
    text: "Reminder: Your standup meeting starts in 10 minutes!"
  },
  sessionTarget: "main"  // Injects into your current chat
})
Enter fullscreen mode Exit fullscreen mode

For simple relative timers, calculate the timestamp:

// In 20 minutes from now
const in20min = new Date(Date.now() + 20 * 60 * 1000).toISOString()
Enter fullscreen mode Exit fullscreen mode

Heartbeat vs Cron: When to Use Each

Use cron when:

  • Exact timing matters (8:00 AM sharp)
  • Task needs isolation from your conversation history
  • You want different model settings for the task
  • It's a one-shot reminder

Use heartbeat (HEARTBEAT.md) when:

  • Multiple checks can batch together
  • Timing can drift slightly (every ~30 min is fine)
  • You want to combine checks (email + calendar + weather)

Practical Example: Weekly Report

Every Friday at 5pm, generate a summary:

cron.add({
  name: "Weekly Report",
  schedule: {
    kind: "cron",
    expr: "0 17 * * 5",  // 5:00 PM every Friday
    tz: "Europe/Dublin"
  },
  payload: {
    kind: "agentTurn",
    message: `It's Friday. Review this week's work:
1. Check email for any pending items
2. Review calendar for the week
3. Write a brief summary of accomplishments

Format as a clean markdown report.`
  },
  sessionTarget: "isolated",
  delivery: {
    mode: "announce",
    channel: "main"  // Posts to your main chat
  }
})
Enter fullscreen mode Exit fullscreen mode

Managing Your Jobs 

// List all scheduled jobs
cron.list()

// Run one immediately (great for testing)
cron.run({ jobId: "job-abc123" })

// See run history
cron.runs({ jobId: "job-abc123" })

// Delete a job
cron.remove({ jobId: "job-abc123" })
Enter fullscreen mode Exit fullscreen mode

Common Cron Expressions

Schedule Expression
Every hour 0 * * * *
Every 6 hours 0 */6 * * *
Daily at 9am 0 9 * * *
Weekdays at 9am 0 9 * * 1-5
Every Monday 0 9 * * 1
At 5pm Friday 0 17 * * 5

Tips

  1. Always test first — Use cron.run() to verify your job does what you expect before relying on it.

  2. Use isolated sessions — Cron jobs that run agent turns should use sessionTarget: "isolated" to avoid cluttering your conversation history.

  3. Set timezones explicitly — Without tz, OpenClaw defaults to UTC. If you're not in UTC, specify your timezone.

  4. Delivery matters — systemEvent injects into your main chat immediately. agentTurn with announce waits for completion then posts the result. Choose based on whether you want to see the task running or just the result.

What's Next

Now that you can schedule tasks, combine this with OpenClaw's memory system for context-aware automation, or wire it into your email/calendar workflows for a proper AI assistant that works around the clock.

The cron system is the backbone of passive automation — set it up once, benefit forever.

Next: Connecting External Tools with OpenClaw Skills

Top comments (0)