Openclaw Cron

OpenClaw Cron Manager

Safe management of OpenClaw cron jobs without touching configuration files.

Quick Start

List all cron jobs

openclaw cron list

Add a new cron job

openclaw cron add \
  --name "任务名称" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "任务描述" \
  --announce \
  --channel telegram \
  --to "telegram:YOUR_CHAT_ID"

Test run immediately

openclaw cron run <job-id>

Disable/Enable a job

openclaw cron disable <job-id>
openclaw cron enable <job-id>

Common Patterns

Daily task (every day at 9 AM)

openclaw cron add \
  --name "每日检查" \
  --cron "0 9 * * *" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "执行每日检查任务" \
  --announce

Weekly task (every Monday at 9 AM)

openclaw cron add \
  --name "周报" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "生成周报" \
  --announce

Hourly task

openclaw cron add \
  --name "每小时检查" \
  --every "1h" \
  --agent main \
  --message "执行小时检查"

One-time task (run once after 20 minutes)

openclaw cron add \
  --name "提醒" \
  --at "+20m" \
  --agent main \
  --message "20分钟后的提醒" \
  --delete-after-run \
  --announce

Cron Expression Guide

Format: minute hour day month weekday

Examples:

• 0 9 * * * - Every day at 9:00 AM
• 0 9 * * 1 - Every Monday at 9:00 AM
• 0 */2 * * * - Every 2 hours
• 30 8 * * 1-5 - Weekdays at 8:30 AM
• 0 0 1 * * - First day of every month at midnight

Shortcuts:

• --every "10m" - Every 10 minutes
• --every "1h" - Every hour
• --every "1d" - Every day
• --at "+20m" - Once, 20 minutes from now
• --at "2026-03-02T09:00:00" - Once, at specific time

Key Options

Scheduling

• --cron <expr> - Cron expression (5-field)
• --every <duration> - Interval (e.g., 10m, 1h, 1d)
• --at <when> - One-time: ISO timestamp or +duration
• --tz <iana> - Timezone (default: system, e.g., Asia/Shanghai)

Agent & Session

• --agent <id> - Which agent runs the task (default: main)
• --session <target> - Session type: main or isolated (default: isolated)
• --model <model> - Model override for this job

Delivery

• --announce - Send result summary to chat
• --channel <channel> - Delivery channel (telegram, whatsapp, etc.)
• --to <dest> - Destination (e.g., telegram:123456)
• --no-deliver - Don't send any notifications

Task Content

• --message <text> - Message for agent to process
• --system-event <text> - System event payload

Behavior

• --disabled - Create job disabled (enable later)
• --delete-after-run - Auto-delete after one-time job succeeds
• --timeout-seconds <n> - Task timeout (default: 30)
• --thinking <level> - Thinking level: off/minimal/low/medium/high

Management Commands

List jobs

# List all jobs
openclaw cron list

# List with JSON output
openclaw cron list --json

View job details

openclaw cron status

Run job immediately (testing)

openclaw cron run <job-id>

View run history

openclaw cron runs <job-id>

Edit job

openclaw cron edit <job-id> --name "新名称"
openclaw cron edit <job-id> --cron "0 10 * * *"
openclaw cron edit <job-id> --disabled

Enable/Disable

openclaw cron disable <job-id>
openclaw cron enable <job-id>

Delete job

openclaw cron rm <job-id>

Real-World Examples

ClawHub Skills Discovery (Weekly)

openclaw cron add \
  --name "ClawHub Skills 周报" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "请检查 ClawHub 上的新 skills 并推荐给我。使用 clawhub search 命令搜索不同类别的 skills。" \
  --announce \
  --channel telegram \
  --to "telegram:5223431061"

Daily Backup

openclaw cron add \
  --name "每日备份" \
  --cron "0 2 * * *" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "创建 OpenClaw 配置备份并推送到 GitHub" \
  --announce

GitHub Activity Report (Daily)

openclaw cron add \
  --name "GitHub 日报" \
  --cron "0 17 * * *" \
  --tz "Asia/Shanghai" \
  --agent main \
  --message "总结今天的 GitHub 活动：commits, PRs, issues" \
  --announce \
  --channel telegram

Reminder (One-time)

openclaw cron add \
  --name "会议提醒" \
  --at "+30m" \
  --agent main \
  --message "30分钟后有会议" \
  --delete-after-run \
  --announce

Best Practices

✅ Do

1. Use --announce for tasks that should notify you
2. Set timezone with --tz for cron expressions
3. Test first with openclaw cron run <id> before enabling
4. Use isolated sessions (default) for independent task execution
5. Set reasonable timeouts with --timeout-seconds
6. Use descriptive names for easy identification

❌ Don't

1. Don't edit openclaw.json directly - Use CLI commands
2. Don't create too many frequent tasks - Combine related checks
3. Don't forget timezone - Default may not match your location
4. Don't use main session unless you need conversation context
5. Don't skip testing - Always test with cron run first

Troubleshooting

Job not running:

1. Check if enabled: openclaw cron list
2. Check next run time
3. Verify timezone setting
4. Test manually: openclaw cron run <id>

Job fails:

1. Check run history: openclaw cron runs <id>
2. Verify agent exists
3. Check timeout settings
4. Test message manually in chat

Wrong schedule:

1. Verify cron expression: https://crontab.guru
2. Check timezone setting
3. Edit schedule: openclaw cron edit <id> --cron "..."

Reference

Cron Expression Syntax

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

Common Timezones

• Asia/Shanghai - China (UTC+8)
• America/New_York - US Eastern
• Europe/London - UK
• UTC - Universal Time

Duration Format

• s - seconds (e.g., 30s)
• m - minutes (e.g., 10m)
• h - hours (e.g., 2h)
• d - days (e.g., 1d)

See Also

• Official docs: https://docs.openclaw.ai/cli/cron
• Cron expression tester: https://crontab.guru
• Timezone list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones