Cron Jobs and Scheduled Tasks in OpenClaw

published

Automate Your AI Assistant with OpenClaw: Cron Jobs and Scheduled Tasks

Why Automate Your AI Assistant?

Imagine having an assistant that works tirelessly even when you're not around. Whether you're asleep, in a meeting, or just taking a break, your AI assistant can keep things running smoothly. With OpenClaw's scheduling capabilities, you can automate tasks like checking emails, setting reminders, monitoring systems, and more. This means you can focus on what truly matters while your AI handles the routine work.

In this guide, we'll explore how to set up scheduled tasks using OpenClaw's built-in cron system, allowing your AI to work for you around the clock.

The Two Scheduling Primitives in OpenClaw

OpenClaw offers two primary ways to schedule tasks:

1. Cron Expressions: Ideal for recurring tasks, such as daily, weekly, or monthly routines. For example, you can set up a task to run every Monday at 9 AM or every two hours.

2. One-Shot Timers: Perfect for one-time reminders or tasks. Need a reminder in 20 minutes or at a specific time? One-shot timers have got you covered.

Both types of schedules are managed through the cron tool.

Setting Up a Recurring Task

Let's say you want a morning briefing every weekday at 8 AM, Dublin time. Here's how you can set it up:

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" }
})

In this example, sessionTarget: "isolated" ensures that the task runs in a separate session, so it won't interrupt your current activities. The delivery.mode: "announce" setting sends the result back to your chat.

One-Shot Reminders

Need a quick reminder in 20 minutes or at a specific time? Here's how you can set it up:

// 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
})

For simple relative timers, you can calculate the timestamp like this:

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

Heartbeat vs. Cron: When to Use Each

• Use Cron When:

  • You need precise timing (e.g., 8:00 AM sharp).
  • The task requires isolation from your conversation history.
  • You want to use different model settings for the task.
  • It's a one-shot reminder.

• Use Heartbeat When:

  • Multiple checks can be batched together.
  • Slight timing variations are acceptable (e.g., every ~30 minutes).
  • You want to combine multiple checks (e.g., email + calendar + weather).

Practical Example: Weekly Report

Every Friday at 5 PM, generate a summary of your week's work:

javascript
cron.add({
  name: "Weekly Report",
  schedule: {
    kind: