cron-mgr

<Use_When>

• •User says "schedule", "every", "daily", "hourly", "cron", "recurring"
• •User describes a time: "at 8am", "every Monday", "twice a day", "every 5 minutes"
• •User wants to list, modify, or remove existing scheduled jobs
• •User asks "what is scheduled?" or "show my cron jobs"
• •Setting up recurring heartbeat, pipeline, or notification schedules
• •User says "stop scheduling" or "remove the daily job" </Use_When>

<Do_Not_Use_When>

• •One-time immediate execution (just run the command directly)
• •Complex multi-step pipeline scheduling (use automation-pipeline, which calls cron-mgr internally)
• •System-level crontab editing (use Bash with crontab directly if user specifically requests OS-level cron)
• •The user wants a delay/timer, not a recurring schedule ("wait 5 minutes" is not cron) </Do_Not_Use_When>

<Why_This_Exists> Scheduling is fundamental to automation but cron expressions are notoriously hard to write correctly. Users think in natural language ("every weekday at 8am") but cron requires cryptic syntax ("0 8 * * 1-5"). Cron Manager bridges this gap by parsing natural language into validated cron expressions, managing them through the OpenClaw gateway, and providing monitoring for failures. Without it, every scheduling task requires manual cron syntax lookup and gateway API calls. </Why_This_Exists>

<Execution_Policy>

• •Always parse natural language schedules into cron expressions before registering
• •Validate every cron expression before submitting to the gateway
• •Show the user the interpreted schedule in human-readable form for confirmation
• •List existing jobs before adding to avoid duplicates
• •Set up failure alerting for all production cron jobs
• •Use timezone-aware scheduling when the user specifies a timezone
• •Default timezone is the system local timezone unless specified otherwise </Execution_Policy>

1. •

   Generate cron expression: Build the 5-field cron expression:

   code

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

   Special characters:

   • •* -- any value
   • •, -- value list separator (1,3,5)
   • •- -- range (1-5)
   • •/ -- step values (*/5 = every 5th)
2. •

   Validate expression: Verify the expression is syntactically correct:

   • •All 5 fields present
   • •Values within valid ranges
   • •No contradictory fields (e.g., day 31 with month 2)
   • •Step values divide evenly into the range
3. •

   Check for duplicates: List existing cron jobs via sc_cron_list and check if a job with the same name or a very similar schedule already exists. Warn the user if so.

4. •

   Register via sc_cron_add: Submit the validated job to the OpenClaw cron system:

   code

   sc_cron_add({
     name: "job-name",
     expression: "0 8 * * 1-5",
     command: "the.command.to.run",
     description: "Human-readable description",
     timezone: "Asia/Seoul"
   })
   

5. •

   Verify registration: Call sc_cron_list after adding to confirm the job appears in the registered jobs list. If it does not appear, report the error.

6. •

   Set up failure alerting: For important jobs, configure an alert that fires if the job fails:

   code

   sc_gateway_request({
     method: "cron.alert",
     params: { job_name: "job-name", alert_channel: "telegram", on: "failure" }
   })
   

7. •

   Report to user: Show the user:

   • •Job name
   • •Cron expression
   • •Human-readable schedule interpretation
   • •Next 3 scheduled run times
   • •Alert configuration (if set) </Steps>

<Tool_Usage>

• •sc_cron_list -- List all registered cron jobs with their expressions, last run time, and status. Use before adding to check for duplicates.
• •sc_cron_add -- Register a new cron job with name, expression, command, and optional timezone. Returns the job ID on success.
• •sc_gateway_request -- Manage cron jobs via gateway API. Methods: cron.delete (remove job), cron.pause (pause job), cron.resume (resume job), cron.alert (configure alerts), cron.history (view run history).
• •Bash -- Calculate next run times, validate expressions with external tools if needed.
• •Read -- Read pipeline definitions that reference cron schedules.
• •Grep -- Search for cron references across configuration files. </Tool_Usage>

Why good: Clean natural language parsing, full validation cycle, clear confirmation. </Good>

Why good: Clear, tabular output with all relevant information. </Good>

Why bad: "at 8am" is ambiguous -- could mean once or daily. Should clarify with user before registering a recurring job. </Bad>

Why bad: Silent failure. The job might not have registered due to a gateway error. Always verify. </Bad> </Examples>

<Escalation_And_Stop_Conditions>

• •If the OpenClaw gateway is not connected, abort and suggest running setup
• •If a cron expression cannot be parsed from natural language, ask the user for clarification rather than guessing
• •If a duplicate job name exists, ask user whether to replace or rename
• •If sc_cron_add returns an error, report the specific error message to the user
• •If the user's schedule is ambiguous (e.g., "at 8" -- 8am or 8pm?), ask for clarification
• •After 3 failed registration attempts, check gateway connectivity and escalate if the gateway is down
• •Stop if the user cancels or decides not to schedule </Escalation_And_Stop_Conditions>

<Final_Checklist>

• • Schedule intent parsed correctly from natural language
• • Cron expression generated and validated
• • No duplicate jobs with the same name
• • Job registered via sc_cron_add
• • Registration verified via sc_cron_list
• • Failure alerting configured for important jobs
• • User shown human-readable schedule and next run times
• • Timezone handled correctly (default to local if unspecified) </Final_Checklist>

Field Ranges

Complex Expression Examples

OpenClaw Cron Integration

OpenClaw's cron system extends standard cron with:

• •Named jobs: Each job has a unique name for management
• •Run history: Last N executions tracked with status
• •Pause/resume: Jobs can be paused without deletion
• •Alert hooks: Configurable alerts on failure, success, or both
• •Timezone support: Per-job timezone configuration

Timezone Handling

When the user specifies a timezone:

1. •Validate it is a valid IANA timezone (e.g., "America/New_York", "Asia/Seoul", "Europe/London")
2. •Pass it as the timezone parameter to sc_cron_add
3. •Show scheduled times in both the specified timezone and UTC

Common timezone shortcuts:

Monitoring Cron Failures

Set up a meta-cron job that checks for failed jobs:

sc_cron_add({
  name: "cron-health-check",
  expression: "0 */6 * * *",
  command: "cron.health_check",
  description: "Check for failed cron jobs every 6 hours"
})

This monitors all other jobs and sends a Telegram alert if any have failed in the last 6 hours.

Modifying Existing Jobs

To modify a job, delete and re-create:

sc_gateway_request({ method: "cron.delete", params: { name: "old-job" } })
sc_cron_add({ name: "old-job", expression: "new-expression", command: "same-command" })

Troubleshooting