Job Management

+15 Mana ✨
OpenClaw Cron Management(DOCUMENTATION)OpenClaw CLI Reference(DOCUMENTATION)

Introduction

Once you have created cron jobs, you need to manage them: list active jobs, edit schedules, enable or disable jobs temporarily, review execution history, and trigger immediate runs for testing. OpenClaw provides a complete set of CLI commands for every management operation.

Key Concepts

  • cron list: Shows all configured cron jobs and their current status
  • cron edit: Modifies an existing job's schedule, payload, or configuration
  • cron enable / cron disable: Toggles a job on or off without deleting it
  • cron runs: Displays the execution history of a specific job
  • cron run: Triggers an immediate execution of a job outside its schedule

Real World Context

During an incident, an on-call engineer needs to temporarily disable all non-critical cron jobs to reduce load on the AI provider's API. After the incident is resolved, they re-enable the jobs. The next morning, they review the execution history to confirm everything resumed correctly. This entire workflow is handled through CLI commands without touching configuration files.

Deep Dive

Listing Jobs

The cron list command shows all configured jobs:

bash
openclaw cron list

This outputs a table with each job's ID, schedule, status (enabled/disabled), last run time, and next scheduled execution. It gives you an at-a-glance view of all automation running in your Gateway.

Editing Jobs

The cron edit command modifies an existing job without recreating it:

bash
openclaw cron edit nightly-review \
  --schedule "0 3 * * *" \
  --model "anthropic:claude-sonnet-4-20250514"

This changes the nightly-review job to run at 3 AM instead of 2 AM and switches its model. The job retains its ID, execution history, and all settings that were not explicitly changed.

Enabling and Disabling

Temporarily pausing a job is cleaner than deleting and recreating it:

bash
# Disable a job (stops scheduling, keeps configuration)
openclaw cron disable nightly-review

# Re-enable it later
openclaw cron enable nightly-review

A disabled job remains in the configuration but is skipped by the scheduler. When re-enabled, it resumes from its next scheduled execution time.

Viewing Execution History

The cron runs command shows past executions for a specific job:

bash
openclaw cron runs nightly-review --limit 10

This shows the last 10 executions including start time, duration, status (success/failure), and a summary of the agent's response.

Immediate Execution

The cron run command triggers a job immediately:

bash
openclaw cron run nightly-review

This executes the job right now with all its configured settings. It is perfect for testing a new job before waiting for its scheduled time. The immediate run is recorded in the execution history alongside scheduled runs.

Combining Commands

Management commands compose naturally for common workflows:

bash
openclaw cron add --every "6h" --system-event "Sync customer data" \
  && openclaw cron run crm-sync \
  && openclaw cron runs crm-sync --limit 1

This chain creates a new job, runs it once to verify it works, and then shows the result.

Common Pitfalls

  • Deleting jobs instead of disabling them: Deleting a job loses its execution history. Disable jobs during maintenance windows and re-enable them when ready.
  • Forgetting to check execution history after changes: Always run cron runs after editing a job to verify the next execution uses the updated configuration.
  • Not testing with cron run before waiting for the schedule: A misconfigured job wastes hours if you wait for its scheduled time only to discover a problem.

Best Practices

  • Always test new jobs with cron run immediately after creation to catch configuration errors early.
  • Use cron disable during incidents rather than deleting jobs, preserving history and configuration.
  • Review cron runs regularly to catch silent failures where the job executes but produces incorrect results.

Summary

  • cron list provides an overview of all jobs with their status and schedules
  • cron edit modifies jobs in place, preserving their ID and history
  • cron enable/disable toggles jobs without deleting configuration or history
  • cron runs shows execution history for debugging and verification
  • cron run triggers immediate execution for testing outside the scheduled time
✓ Completed