OpenClaw Scheduler#

A durable orchestration runtime for OpenClaw agents and shell workflows. SQLite-backed, runs as a separate launchd service ( ai.openclaw.scheduler), keeps full run history, and supports chains like shell check -> agent diagnosis -> human approval -> remediation.

Source: github.com/amittell/openclaw-scheduler -- MIT Service label: ai.openclaw.scheduler (LaunchAgent or LaunchDaemon) Default location: ~/.openclaw/scheduler/ Runtime: Node.js 22+ (ESM), SQLite via better-sqlite3, cron via croner

When to use#

Reach for openclaw-scheduler when one or more of these apply:

• Scheduled jobs need a real audit trail, not "it probably ran" buried in logs.
• Shell jobs must keep running when the gateway is unhealthy or restarting.
• Workflows have multiple steps that need retries, approvals, or escalation.
• Agent jobs need to stay isolated from the operator's personal chats.
• Built-in cron lacks the failure-handling or chaining you need.

If the user just wants one cron line that fires occasionally, built-in OpenClaw cron is enough. Don't suggest the scheduler.

Install#

bash

npm install -g openclaw-scheduler
openclaw-scheduler init
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.scheduler.plist
openclaw-scheduler jobs list

The init step creates ~/.openclaw/scheduler/scheduler.db and the launchd plist. jobs list confirms the service is talking to its DB.

Define a job#

bash

openclaw-scheduler jobs add \
  --name "weekly digest" \
  --cron "0 9 * * 1" \
  --kind agent \
  --to "@channel-id" \
  --prompt "Summarize last week's incidents and post to #digest"

For shell jobs, swap --kind agent --prompt ... with --kind shell --command ....

Multi-step workflows#

Workflows chain steps with explicit retries and approvals:

bash

openclaw-scheduler workflows add disk-watcher \
  --step shell:check --command 'df -h | awk "$5+0>85"' \
  --on-output --step agent:diagnose --to "@ops" \
    --prompt "Investigate the failing disk and propose a fix" \
  --then --step approval --approver "@alex" --timeout 30m \
  --on-approve --step shell:remediate --command 'sudo /opt/sbin/cleanup-tmp.sh'

Each step persists state, retries on failure, and surfaces the run in jobs runs.

Gateway interaction#

Agent jobs require the gateway to be reachable. The dispatcher calls waitForGateway(timeoutMs, intervalMs) before delivering; jobs queue up if the gateway is restarting and fire when it's ready again. Shell jobs run independently of gateway health.

Operator commands#

• openclaw-scheduler jobs list -- running, scheduled, paused
• openclaw-scheduler jobs runs <id> -- full run history with stdout/stderr
• openclaw-scheduler jobs approve <id> / reject <id> -- for approval steps
• openclaw-scheduler jobs pause/unpause <id> -- disable without deleting
• openclaw-scheduler workflows list -- multi-step workflow status

Boundary#

This tool replaces OpenClaw's built-in cron/heartbeat for hosts that need durability. It is not bundled with OpenClaw and not loaded as a plugin. The two can coexist (built-in cron handles agent heartbeats, openclaw-scheduler handles operator workflows), or operators can disable built-in cron and route everything through the scheduler.

Known gaps#

• macOS first-class; Linux works; Windows requires WSL2.
• No native gateway-side UI yet; runs are read via the CLI.
• See github.com/amittell/openclaw-scheduler/issues for open work.