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

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

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:

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 -- full run history with stdout/stderr
• openclaw-scheduler jobs approve / reject -- for approval steps
• openclaw-scheduler jobs pause/unpause -- 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.