OpenClaw uses a built-in Cron scheduler to give AI agents precise time-based triggers, session isolation, model overrides, and multi-channel delivery. It solves the limitations of traditional crontab, which cannot manage context, notification pipelines, or intelligent decision-making. Keywords: OpenClaw, Cron, automated operations.
Technical Specification Snapshot
| Parameter | Description |
|---|---|
| Languages | YAML, JSON, Bash |
| Scheduling Protocols | Cron expressions, fixed intervals, one-time timestamps |
| Repository Popularity | Star count not provided in the source |
| Core Dependencies | OpenClaw Gateway, CLI, IANA Time Zone |
| Persistence Location | ~/.openclaw/cron/jobs.json |
| Run History | `~/.openclaw/cron/runs/ |
| .jsonl` |
OpenClaw elevates AI agent cron jobs from system-level scheduling to workflow capabilities
Traditional cron works well for running scripts, but it does not understand conversational context, model capabilities, or message delivery. OpenClaw combines scheduling, inference, notifications, and session management into a single mechanism, which makes it better suited for proactive AI agent execution scenarios.
Its core value is not just “run on schedule.” It makes tasks orchestratable. Developers can define timing, execution mode, model tier, delivery channel, and whether a job should pollute the main session history.
OpenClaw’s Cron capabilities consist of three scheduling modes
OpenClaw supports at, every, and cron, which map to one-time reminders, fixed-interval polling, and precise time-based triggers. Together, they cover most automated operations and intelligent reminder scenarios.
cron:
enabled: true # Enable scheduled job capability
store: "~/.openclaw/cron/jobs.json" # Job persistence path
maxConcurrentRuns: 1 # Control the maximum number of concurrent runsThis configuration defines the global Cron switch, the job storage location, and the concurrency limit. It is the foundational entry point for the scheduling system.
Cron expressions remain the core language for precise scheduling
A standard Cron expression contains five fields: minute, hour, day of month, month, and day of week. OpenClaw adopts the same model, which lowers the learning curve and lets developers reuse existing crontab knowledge.
In AI automation scenarios, Cron determines when a task should trigger, not how it should execute. The actual intelligent behavior is defined by payload, sessionTarget, and delivery.
The five-field structure must be interpreted with time zones in mind
| Field | Range | Common Symbols |
|---|---|---|
| Minute | 0-59 | * , - / |
| Hour | 0-23 | * , - / |
| Day of Month | 1-31 | * , - / ? L W |
| Month | 1-12 or JAN-DEC | * , - / |
| Day of Week | 0-7 or SUN-SAT | * , - / ? L # |
Common expressions include */15 * * * * for every 15 minutes and 0 7 * * * for 7:00 every day. If you do not explicitly declare tz, the job inherits the Gateway host time zone, which can easily cause errors in cross-region deployments.
{
"schedule": {
"kind": "cron",
"expr": "0 7 * * *",
"tz": "Asia/Shanghai"
}
}This configuration defines a job that triggers every day at 7:00 AM Beijing time, avoiding drift caused by the host machine’s local time zone.
Session mode determines whether a job has contextual continuity
A key OpenClaw design choice is binding scheduled jobs to different session targets. Developers can trigger events in the main session or run independent work in isolated sessions.
The main mode works well for reminders, follow-up questions, and decisions that continue from previous conversations. The isolated mode works better for backups, health inspections, daily report generation, and other background tasks because it prevents context pollution in the primary session.
A complete job combines schedule, payload, and delivery
{
"name": "Morning briefing",
"schedule": {
"kind": "cron",
"expr": "0 7 * * *",
"tz": "Asia/Shanghai"
},
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "Generate today's briefing: weather, calendar, emails, news.",
"model": "opus",
"thinking": "high"
},
"delivery": {
"mode": "announce",
"channel": "telegram",
"to": "-1001234567890:topic:123",
"bestEffort": true
},
"enabled": true
}This job demonstrates the full OpenClaw scheduling chain: scheduled trigger, isolated execution, higher-tier model analysis, and Telegram delivery for the generated summary.
Real-world scenarios map directly to CLI commands
One-time reminders work well for meeting notifications or deadline alerts. Fixed-interval jobs fit service inspections. Weekly scheduled jobs are useful for retrospective analysis. The CLI makes these workflows easy to implement in engineering environments.
In production, reminder-style jobs should usually go into the main session, while analytical jobs should run in isolated sessions. This preserves interaction continuity while keeping background tasks independent and traceable.
Running a system health check every 15 minutes is a classic operations use case
openclaw cron add \
--name "System health check" \
--cron "*/15 * * * *" \
--session isolated \
--message "Check CPU, memory, disk, and service status. Alert if any metric exceeds the threshold." \
--model "sonnet" \
--announce \
--channel telegram \
--to "+15551234567"This command creates a high-frequency inspection job that uses a lightweight model to analyze system resource health and automatically push an alert summary.
Cron and Heartbeat are complementary, not interchangeable
Cron is strong at precise triggering. Heartbeat is strong at periodic awareness. The former fits tasks tied to exact times, while the latter fits recurring checks across multiple pending items.
If a job must run exactly at 7:00 AM every day, 9:00 AM every Monday, or 20 minutes from now, choose Cron first. If a job needs to periodically inspect the main session context and decide whether to remind, summarize, or follow up, Heartbeat is usually a better fit.
The selection rule between the two mechanisms can be summarized in one sentence
| Dimension | Cron | Heartbeat |
|---|---|---|
| Trigger Mode | Precise time | Fixed interval |
| Session Type | Main session or isolated session | Main session only |
| Model Override | Supported | Usually follows the main session |
| One-Time Jobs | Supported | Not supported |
| Use Cases | Briefings, backups, reminders, weekly reports | Inbox checks, calendar scans, lightweight keepalive |
The best practice is usually to combine them: use Heartbeat for lightweight inspections, and use Cron for hard time-based tasks and deeper analysis.
Production stability depends on observability and clear troubleshooting paths
When a job does not run, the root cause is often not the expression itself. Common issues include the Gateway not running, Cron being disabled, environment variables skipping scheduling, or an incorrect understanding of time zones. Delivery failures usually come from channel configuration errors or invalid destination IDs.
Start by checking the job list, then inspect run history, and finally force a manual run to reproduce the problem. This process helps you quickly determine whether the failure is in the scheduling layer, execution layer, or delivery layer.
Common troubleshooting commands cover most issues
openclaw cron list # View jobs and enabled status
openclaw gateway status # Check whether the Gateway is running
openclaw cron runs --id
<jobId> --limit 10 # View recent run history
openclaw cron run
<jobId> --force # Manually trigger a job for debugging
echo $OPENCLAW_SKIP_CRON # Check whether Cron is being skippedThese commands help locate job state, execution results, and environment variable issues. They are the most direct debugging entry points.
FAQ
FAQ 1: What is the fundamental difference between OpenClaw Cron and Linux crontab?
OpenClaw Cron does more than “run a command at a specific time.” It also manages session isolation, model selection, notification delivery, and job persistence, which makes it better suited for AI agent workflows rather than simple system script scheduling.
FAQ 2: When should you choose main, and when should you choose isolated?
Choose main when the task needs to inherit previous conversation history and continue context-aware reasoning. Choose isolated when the task should run independently in the background, avoid polluting the main chat history, or override model and thinking levels.
FAQ 3: Why does my job still run at the wrong time even though the Cron expression is correct?
The most common reason is that tz is not set, so the job defaults to the time zone of the host running the Gateway. In cross-cloud, containerized, or overseas deployments, you should always explicitly declare an IANA time zone such as Asia/Shanghai.
Core summary: This article systematically reconstructs OpenClaw’s Cron capabilities, covering expression syntax, configuration structure, session modes, delivery mechanisms, comparison with Heartbeat, and troubleshooting methods to help developers build a reliable AI agent automation and scheduling system.