cron-job-operator

name	cron-job-operator
description	Create, edit, run, inspect, and troubleshoot OpenClaw cron jobs using the Gateway scheduler with safe operational checks. Use when adding recurring automation, debugging failed job runs, validating delivery targets, fixing timezone/schedule mistakes, or auditing cron health and run history.

Cron Job Operator

Overview

Operate OpenClaw cron jobs with a repeatable workflow. Prefer CLI-first operations and verify status/runs after each change.

Quick Start

1. Check scheduler and current jobs:

   ./scripts/cron_health_check.sh
   

2. Create a job:

   ./scripts/cron_create_job.sh --name "Daily task" --cron "0 10 * * *" --tz "Asia/Ho_Chi_Minh" --system-event "/home/node/.openclaw/scripts/task.sh"
   

3. Patch/edit a job:

   ./scripts/cron_patch_job.sh --id <job-id> --cron "0 9 * * *" --tz "Asia/Ho_Chi_Minh"
   

4. Debug a run and inspect history:

   ./scripts/cron_debug_run.sh --id <job-id>
   

Workflow

Step 1: Validate gateway and scheduler

• Run status first (cron status, cron list).
• If gateway is unreachable, stop and report connectivity issue before mutating jobs.

Step 2: Create jobs with explicit schedule semantics

• Always set timezone (--tz) for cron expressions.
• Use either:
  • --cron for fixed schedules
  • --every for interval jobs
  • --at for one-shot jobs
• Keep payload explicit (--system-event or --message).

Step 3: Edit incrementally and verify

• Patch one concern at a time (schedule, delivery target, model, wake mode).
• Re-check cron list + cron status after edit.
• Avoid wide edits without before/after snapshots.

Step 4: Debug failures with run history

• Use cron run --id for immediate test.
• Inspect cron runs --id <job-id>.
• Verify:
  • lastRunStatus
  • delivery mode and target
  • timeout and wake behavior

Guardrails

• Do not modify production jobs until cron status is healthy.
• Do not schedule high-frequency jobs without explicit reason.
• Keep timezone explicit to avoid drift.
• Prefer edit over remove/recreate for minor changes.

Resources

• scripts/cron_health_check.sh: Show cron scheduler + job list.
• scripts/cron_create_job.sh: Create cron/interval/one-shot jobs safely.
• scripts/cron_patch_job.sh: Patch existing jobs (cron edit).
• scripts/cron_debug_run.sh: Trigger debug run and inspect runs.
• references/cron-operator-playbook.md: Schedule patterns and remediation matrix.

Example Requests

1. "Dùng cron-job-operator tạo job báo cáo lúc 10:00 sáng mỗi ngày theo giờ VN."
2. "Dùng cron-job-operator debug vì sao job tech-news fail hôm nay."
3. "Dùng cron-job-operator đổi lịch job weather từ 8:00 sang 7:30."

Load references/cron-operator-playbook.md when deciding schedule semantics or failure triage.