Back
Openclaw-Series

14. OpenClaw Automation & Scheduled Tasks: Cron, Webhook, and Gmail Integration

This article introduces OpenClaw's automation capabilities, including Cron scheduled tasks, Webhook triggers, Gmail Pub/Sub integration, and more—enabling your AI assistant to work proactively rather than just respond passively.

For OpenClaw v2026.2 | This article is for users who want their AI assistant to work proactively rather than respond passively.

TL;DR: Cron scheduled tasks: "cron": [{"id": "daily", "schedule": "0 9 * * *", "message": "..."}]. Webhook trigger: POST /webhook/your-path. Gmail Pub/Sub for automatic email processing. Heartbeat for proactive checks. Example configs: daily briefing 0 8 * * 1-5, CI notification webhook, email filter gmail pub/sub.

Automation Overview

Types of Automation

Type Trigger Use Case
Cron Scheduled Daily reports, periodic checks
Webhook HTTP request External system integration
Gmail Pub/Sub New email Email automation
Heartbeat Periodic check Proactive reminders, suggestions

Architecture Diagram

flowchart TB
    subgraph Triggers["Trigger Sources"]
        CRON[Cron Schedule]
        WH[Webhook HTTP]
        GM[Gmail Pub/Sub]
        HB[Heartbeat]
    end
    
    subgraph Gateway["Gateway"]
        SCHED[Scheduler]
        ROUTE[Router]
        AGENT[Agent]
    end
    
    subgraph Actions["Actions"]
        MSG[Send Message]
        EXEC[Execute Task]
        NOTIF[Send Notification]
    end
    
    CRON --> SCHED
    WH --> ROUTE
    GM --> ROUTE
    HB --> SCHED
    
    SCHED --> AGENT
    ROUTE --> AGENT
    AGENT --> MSG
    AGENT --> EXEC
    AGENT --> NOTIF

Cron Scheduled Tasks

Cron Expression

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, 0 = Sunday)
│ │ │ │ │
* * * * *

Common Expressions

Expression Description
0 9 * * * Every day at 9:00
0 18 * * 1-5 Weekdays at 18:00
*/30 * * * * Every 30 minutes
0 0 1 * * 1st of each month at 0:00
0 9,18 * * * Every day at 9:00 and 18:00
0 9 * * 1 Every Monday at 9:00

Configuring Cron Tasks

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Please give me today's schedule and to-do items",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Generate this week's work summary",
      "enabled": true
    },
    {
      "id": "health-check",
      "schedule": "*/15 * * * *",
      "session": "main",
      "message": "Check system status and report any anomalies",
      "enabled": true
    }
  ]
}

Cron Configuration Fields

Field Type Description
id string Unique task identifier
schedule string Cron expression
session string Target session
message string Message to send
enabled boolean Whether enabled
timezone string Timezone (default: system timezone)

Managing Cron Tasks

# List all tasks
openclaw cron list

# Output example:
# ID               Schedule       Status    Last Run
# daily-briefing   0 9 * * *     enabled   2026-02-26 09:00
# weekly-summary   0 18 * * 5    enabled   2026-02-23 18:00
# health-check    */15 * * * *   enabled   2026-02-26 10:30

# Manually trigger a task
openclaw cron run daily-briefing

# Enable/disable task
openclaw cron enable daily-briefing
openclaw cron disable daily-briefing

# View task logs
openclaw cron logs daily-briefing

Webhook Triggers

Configuring Webhooks

{
  "webhooks": [
    {
      "id": "github-push",
      "path": "/webhook/github",
      "secret": "your-webhook-secret",
      "session": "main",
      "handler": "github-push"
    },
    {
      "id": "custom-alert",
      "path": "/webhook/alert",
      "secret": "your-webhook-secret",
      "session": "main",
      "message": "Alert received: {{data.message}}"
    }
  ]
}

Webhook Endpoints

POST http://your-gateway:18789/webhook/github-push
POST http://your-gateway:18789/webhook/alert

GitHub Webhook Example

{
  "webhooks": [
    {
      "id": "github-push",
      "path": "/webhook/github",
      "secret": "${GITHUB_WEBHOOK_SECRET}",
      "session": "work",
      "handler": "github-push"
    }
  ]
}

Handler script:

// ~/.openclaw/handlers/github-push.js
module.exports = async (payload, session) => {
  if (payload.ref === 'refs/heads/main') {
    const commits = payload.commits.map(c => c.message).join('\n- ');
    return `New push detected:\n\nBranch: main\nCommits:\n- ${commits}\n\nWhat would you like me to do?`;
  }
  return null;
};

Custom Webhook Handling

{
  "webhooks": [
    {
      "id": "monitoring-alert",
      "path": "/webhook/alert",
      "methods": ["POST"],
      "session": "main",
      "message": "🚨 Alert Notification\n\nLevel: {{data.level}}\nService: {{data.service}}\nMessage: {{data.message}}\nTime: {{data.timestamp}}"
    }
  ]
}

Sending a Webhook:

curl -X POST http://localhost:18789/webhook/alert \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret" \
  -d '{
    "level": "critical",
    "service": "api-server",
    "message": "CPU usage exceeds 90%",
    "timestamp": "2026-02-26T10:30:00Z"
  }'

Webhook Security

{
  "webhooks": [
    {
      "id": "secure-webhook",
      "path": "/webhook/secure",
      "secret": "your-secret-key",
      "signatureHeader": "X-Signature",
      "signatureAlgorithm": "sha256",
      "ipWhitelist": ["192.168.1.0/24"]
    }
  ]
}

Gmail Pub/Sub Integration

Configuring Gmail Pub/Sub

{
  "gmail": {
    "pubsub": {
      "enabled": true,
      "projectId": "your-project-id",
      "subscription": "gmail-subscription",
      "credentials": {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "...",
        "private_key": "...",
        "client_email": "..."
      },
      "filters": [
        {
          "from": "[email protected]",
          "session": "main",
          "message": "Important email received:\nFrom: {{sender}}\nSubject: {{subject}}"
        }
      ]
    }
  }
}

Setting Up Gmail Pub/Sub

  1. Create a Google Cloud project
  2. Enable Gmail API
  3. Create a Pub/Sub topic
  4. Create a service account
  5. Configure Gmail watch
# Configure Gmail watch
openclaw gmail watch --email [email protected]

Gmail Filters

Filter Condition Description
from Sender email address
to Recipient email address
subject Subject keywords
hasAttachment Whether has attachment
label Gmail label 
{
  "filters": [
    {
      "from": "[email protected]",
      "session": "work",
      "message": "GitHub notification received: {{subject}}"
    },
    {
      "from": "[email protected]",
      "hasAttachment": true,
      "session": "main",
      "message": "Stripe document received, please process"
    }
  ]
}

Heartbeat Proactive Check

Configuring Heartbeat

{
  "heartbeat": {
    "enabled": true,
    "interval": 3600000,
    "session": "main",
    "message": "Heartbeat: Please check if there's anything that needs my attention"
  }
}

Heartbeat Use Cases

Use Case Description
Proactive reminders Periodically remind users
Status check Check system or service status
Task suggestions Provide suggestions based on context
Context maintenance Keep sessions active

Heartbeat Example

{
  "heartbeat": {
    "enabled": true,
    "interval": 1800000,
    "conditions": [
      {
        "type": "time",
        "start": "09:00",
        "end": "18:00"
      },
      {
        "type": "active",
        "session": "main"
      }
    ],
    "message": "Based on current time, suggest checking:\n1. Today's to-dos\n2. Email reminders\n3. Schedule"
  }
}

Automation Examples

Example 1: Daily Morning Briefing

{
  "cron": [
    {
      "id": "morning-briefing",
      "schedule": "0 8 * * 1-5",
      "session": "main",
      "message": "Good morning! Please give me today's briefing:\n1. Weather forecast\n2. Today's schedule\n3. To-do items\n4. Important email summary"
    }
  ]
}

Example 2: CI/CD Notification

{
  "webhooks": [
    {
      "id": "ci-failure",
      "path": "/webhook/ci",
      "session": "dev",
      "message": "⚠️ CI Failure\n\nProject: {{data.repository}}\nBranch: {{data.branch}}\nCommit: {{data.commit}}\nError: {{data.error}}\n\nWould you like me to help analyze?"
    }
  ]
}

Example 3: Automatic Email Processing

{
  "gmail": {
    "pubsub": {
      "filters": [
        {
          "from": "[email protected]",
          "hasAttachment": true,
          "session": "main",
          "message": "Invoice email received, processing...\nPlease save attachment to finance folder"
        }
      ]
    }
  }
}

Example 4: System Monitoring

{
  "cron": [
    {
      "id": "system-monitor",
      "schedule": "*/5 * * * *",
      "session": "main",
      "message": "Check system status",
      "skills": ["system-monitor"]
    }
  ]
}

Troubleshooting

Cron Tasks Not Running

# Check task status
openclaw cron list

# Check logs
openclaw logs --filter cron

# Manually trigger for testing
openclaw cron run task-id

Webhook Not Responding

# Check webhook endpoint
curl -X POST http://localhost:18789/webhook/test \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# View logs
openclaw logs --filter webhook

Gmail Pub/Sub Not Working

# Check subscription status
openclaw gmail status

# Reconfigure
openclaw gmail setup

# Check permissions
openclaw gmail check-permissions

Summary

Automation enables OpenClaw to work proactively instead of responding passively:

  • Cron: Execute tasks on schedule
  • Webhook: Triggered by external events
  • Gmail Pub/Sub: Email automation
  • Heartbeat: Proactive reminders and suggestions

Changelog:

  • 2026-02-26: Initial release

Series Navigation: