178 lines
3.8 KiB
Markdown
178 lines
3.8 KiB
Markdown
---
|
|
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
|