⚡ Automation

Make your agent work while you sleep. Cron jobs, heartbeats, and webhooks.

⏰

Cron Jobs

Schedule your agent to run tasks at specific times. Perfect for morning briefings, daily reports, and regular check-ins.

Example: Morning Briefing at 8am

{
  "name": "Morning Briefing",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",
    "tz": "Australia/Brisbane"
  },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Give me a morning briefing with weather, calendar, and top tasks.",
    "deliver": true
  }
}

Schedule Types

Cron Expression

Standard cron syntax for recurring schedules

"expr": "0 9 * * MON-FRI" 9am weekdays
One-time (at)

Run once at a specific timestamp

"kind": "at", "atMs": 1706745600000 Exact moment
Interval (every)

Run at regular intervals

"kind": "every", "everyMs": 3600000 Every hour

Common Cron Expressions

0 8 * * *Every day at 8am
0 9 * * MON-FRIWeekdays at 9am
0 */4 * * *Every 4 hours
30 17 * * FRIFridays at 5:30pm
0 0 1 * *First of each month
💓

Heartbeats

Periodic check-ins that let your agent be proactive. Create a HEARTBEAT.md file with tasks to check.

Example HEARTBEAT.md

# Heartbeat Checklist

## Check (rotate through 2-4x daily):
- [ ] Unread emails that need attention?
- [ ] Calendar events in next 24h?
- [ ] Client websites still up?

## When to reach out:
- Important email arrived
- Event coming up (<2h)
- Something urgent found

## When to stay quiet (HEARTBEAT_OK):
- Late night (23:00-08:00)
- Nothing new since last check
- Just checked <30 minutes ago

Heartbeat vs Cron: When to Use Each

💓 Use Heartbeat When:
  • Multiple checks can batch together
  • You need conversational context
  • Timing can drift slightly
  • Reduce API calls by combining checks
⏰ Use Cron When:
  • Exact timing matters
  • Task needs isolation
  • One-shot reminders
  • Output should deliver directly
🔗

Webhooks

Trigger your agent from external events. Receive HTTP requests and route them to your agent.

Gmail Push Notifications

Get notified instantly when important emails arrive using Google Pub/Sub:

openclaw webhooks gmail setup --account you@example.com

Custom Webhook Server

Create a simple webhook handler that triggers your agent:

// webhook-handler.mjs
import { exec } from 'child_process';

const server = Bun.serve({
  port: 3847,
  async fetch(req) {
    const body = await req.json();
    
    // Trigger agent with the webhook data
    exec(`openclaw agent --session-key main --message "${body.message}"`);
    
    return new Response('OK');
  }
});

console.log('Webhook server running on :3847');

Use Cases

📧 Email notifications 🛒 Order alerts 📊 Analytics triggers 🔔 IoT events 🚨 Monitoring alerts 📝 Form submissions

🚀 Quick Examples

Daily SEO Check

Monitor client websites every morning

0 7 * * *

Weekly Report

Generate summary every Friday

0 17 * * FRI

Reminder

One-time reminder in 20 mins

kind: "at"

Status Check

Check system health hourly

0 * * * *