---
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:
   ```bash
   ./scripts/cron_health_check.sh
   ```
2. Create a job:
   ```bash
   ./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:
   ```bash
   ./scripts/cron_patch_job.sh --id <job-id> --cron "0 9 * * *" --tz "Asia/Ho_Chi_Minh"
   ```
4. Debug a run and inspect history:
   ```bash
   ./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.