---
name: cron-scheduling
description: Schedule automated tasks with cron expressions or intervals using OpenClaw's cron system
---

## When to use
Use when the user asks to:
- Run periodic checks (every hour, daily, weekly)
- Schedule one-time future tasks
- Automate recurring reports or backups
- Set up monitoring alerts
- Create time-based triggers

## Cron Basics

OpenClaw uses standard cron expressions:
```
* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week (0-7, 0= Sunday)
│ │ │ └──── Month (1-12)
│ │ └────── Day of month (1-31)
│ └──────── Hour (0-23)
└────────── Minute (0-59)
```

**Examples**:
- `0 * * * *` — every hour at minute 0
- `30 3 * * *` — daily at 3:30 AM
- `0 9 * * 1` — every Monday at 9:00 AM
- `*/15 * * * *` — every 15 minutes

## Workflow

### 1. Create a scheduled job
```bash
cron add \
  --name "daily-backup" \
  --schedule "0 2 * * *" \
  --task "clawteam task create backup 'Database backup' -o backup-agent"
```

### 2. List scheduled jobs
```bash
cron list
cron list --include-disabled true
```

### 3. Manage jobs
```bash
# Disable (keep config)
cron update --job-id <id> --enabled false

# Enable
cron update --job-id <id> --enabled true

# Remove
cron remove --job-id <id>
```

### 4. Run manually (for testing)
```bash
cron run --job-id <id>
```

### 5. View job history
```bash
cron runs --job-id <id> --limit 10
```

## Job Configuration Options

| Flag | Description | Example |
|------|-------------|---------|
| `--name` | Human-readable name | "Health check" |
| `--schedule` | Cron expression | "*/5 * * * *" |
| `--task` | Command to execute | "oh -p 'Check system'" |
| `--timezone` | IANA timezone | "Asia/Ho_Chi_Minh" |
| `--enabled` | Start enabled/disabled | true/false |

## Advanced Scheduling

### Interval-based (every N minutes/hours)
```bash
cron add \
  --name "ping-every-10m" \
  --schedule-kind every \
  --every-ms 600000 \
  --task "oh -p 'Ping service'"
```

### One-time future run
```bash
cron add \
  --name "deploy-at-noon" \
  --schedule-kind at \
  --at "2026-04-09T12:00:00Z" \
  --task "oh -p 'Deploy v2'"
```

### Random jitter (avoid thundering herd)
```bash
cron add \
  --schedule-kind cron \
  --expr "*/10 * * * *" \
  --stagger-ms 120000  # ±2 min random
```

## Task Payloads

### Simple command
```bash
--task "oh -p 'Check logs'"
```

### With context
```bash
--task "oh -p 'Check logs' --contextMessages 5"
```

### Agent turn (new conversation)
```bash
--task '{"kind":"agentTurn","message":"Check system health"}'
```

### System event (inject into main session)
```bash
--task '{"kind":"systemEvent","text":"/healthcheck"}'
```

## Best Practices

- **Descriptive names**: "daily-backup" not "job1"
- **Error alerts**: Configure cron failure alerts (`--failure-alert`)
- **Logging**: Ensure tasks have `--verbose` or logging enabled
- **Test manually**: `cron run` before relying on schedule
- **Avoid overlap**: Ensure tasks finish before next run (use `--timeout`)

## Examples

<Good>
Daily health check at 2 AM:
```bash
cron add \
  --name "nightly-health" \
  --schedule "0 2 * * *" \
  --timezone "Asia/Ho_Chi_Minh" \
  --task "oh -p 'Run full healthcheck' --output-format json" \
  --failure-alert '{"channel":"alerts","to":"#devops"}'
```
</Good>

<Bad>
Running backup every minute without timeout — can overlap and cause issues.
</Bad>

## Monitoring

Check cron status:
```bash
cron status
```

View recent runs:
```bash
cron runs --limit 20
```

Failed runs trigger alerts if configured.

## Verification Checklist
- [ ] Cron expression is correct (use crontab.guru to verify)
- [ ] Task command works manually (`cron run`)
- [ ] Timezone is set correctly
- [ ] Failure alerts configured for critical jobs
- [ ] Overlap is prevented (task duration < interval)
- [ ] Job history shows successful runs