Cron jobs for AI agents sound simple until the job has to talk to a model, use tools, remember what happened last time, and report back to the right chat. A normal script can fail quietly and wait for tomorrow. An agent job cannot always get away with that. If it is checking an inbox, drafting a report, watching a build, or waking a support agent at 7 AM, you need to know where the run went, whether it finished, and where the answer was delivered.
That is why OpenClaw treats scheduled work as a Gateway feature, not as a few lines hidden in a server crontab. The old cron mental model still helps. A schedule says “run this later” or “run this every day.” But the useful part for AI agents is what happens around that schedule: persisted job state, isolated sessions, background task records, channel delivery, timeouts, and run history.
My opinion is straightforward: OS cron is fine for starting a process from the outside. For recurring agent work, the scheduler should live next to the agent runtime. In OpenClaw, that means automations.
Why cron jobs for AI agents are different from cron jobs for scripts
A classic cron job usually runs a command and exits. Maybe it writes a log. Maybe it sends email if stderr is not empty. That model works for backup scripts, file cleanup, certificate renewals, and other jobs where the command is the whole story.
An AI agent run has more moving parts. It may need workspace instructions. It may need memory. It may call tools, browse a page, spawn subagents, generate media, update a document, or send a message to Slack, Telegram, WhatsApp, Discord, or iMessage. It may need to run in the main session because it depends on recent conversation context, or in an isolated session because you do not want yesterday’s chat history dragged into a scheduled report.
That is the first difference: the schedule is not the hard part. The hard part is ownership.
If system cron launches a command, cron owns the timer, the shell owns the process, and your agent platform has to infer what happened after the fact. If OpenClaw automations launch the work, the Gateway owns the schedule and the run. It can create a background task record, bind the run to a session, deliver the final output to a channel, keep run history, and handle scheduler-specific cleanup. That is a better shape for agent work.
It also makes failure less mysterious. A missed shell cron can become “I guess nothing happened.” An OpenClaw automation becomes a run with status, history, and a task ledger entry.
What OpenClaw automations actually do
OpenClaw automations are the built-in scheduler for the Gateway. The docs put the contract plainly: automations persist jobs, wake the agent at the right time, and can deliver output to a chat channel, a webhook, or nowhere. You manage them with openclaw automations. The older openclaw cron command still works as an alias, which is useful if your muscle memory is already there.
The important detail is where automations run. They run inside the Gateway process, not inside the model. The model does not sit there watching the clock. The Gateway does. That also means the Gateway must be running for schedules to fire.
OpenClaw stores job definitions, runtime state, and run history in its shared SQLite state database. That matters more than it sounds. If you restart the Gateway, schedules are not just loose shell lines that someone needs to remember. They are persisted jobs with runtime state.
Every automation run also creates a background task record. The task system is not the scheduler. It is the ledger. It records detached work such as automation runs, subagents, ACP runs, CLI operations, and media jobs. For scheduled agent work, that split is healthy: automations decide when the work starts, tasks show what happened after it started.
That gives you a real operational trail. A task can be queued, running, succeeded, failed, timed out, cancelled, or lost. Terminal records are kept for 7 days, while lost records are kept for 24 hours. That is enough time to debug the boring-but-real questions: Did the job fire? Did it start? Did the agent answer? Did delivery fail? Did the run time out?
The schedule types you can use
OpenClaw does more than plain five-field cron. The automations doc lists several schedule kinds, and each one fits a different kind of agent work.
One-shot jobs
Use --at for one-time work. This is the reminder shape: “at 4 PM, wake the agent and ask it to check the draft.” One-shot jobs auto-delete after success by default, unless you keep them with --keep-after-run.
openclaw automations create "2027-02-01T16:00:00Z" \
--name "Draft review reminder" \
--session main \
--system-event "Reminder: check the automations docs draft" \
--wake now \
--delete-after-runFor AI agents, one-shot jobs are underrated. They are a clean way to defer work without leaving a vague note in the current chat.
Fixed intervals
Use --every for simple intervals like 10m, 1h, or 1d. This fits repeated checks where exact wall-clock time is less important than cadence. For example, “look for stuck background tasks every hour” or “summarize a queue once a day.”
Be careful with interval jobs that take longer than their cadence. If a job can run for 20 minutes, scheduling it every 10 minutes is asking for overlap pain. OpenClaw has guards and run ownership rules, but a better first move is to pick a cadence that matches the work.
Cron expressions
Use --cron when you need a calendar schedule. This is the “every weekday at 9 AM” shape. OpenClaw supports 5-field and 6-field cron expressions, with optional --tz for IANA timezones.
The timezone bit is not decoration. Timestamps without a timezone are treated as UTC. Cron expressions without --tz use the Gateway host timezone. If your operator thinks in Asia/Kolkata and the VPS runs UTC, you should say the timezone out loud in the job definition.
openclaw automations add \
--name "Daily docs blog draft" \
--cron "0 7 * * *" \
--tz Asia/Kolkata \
--session isolated \
--message "Run the daily docs blog pipeline as a draft."There is one cron footgun worth repeating. OpenClaw uses Croner. Like standard Vixie cron behavior, when both day-of-month and day-of-week are non-wildcard, the expression matches when either field matches. So 0 9 15 * 1 means 9 AM on every 15th and 9 AM every Monday. It does not mean “the 15th, only if it is Monday.” Croner’s + modifier lets you require both fields, as in 0 9 15 * +1.
On-exit and stream schedules
OpenClaw also supports event-style schedules. --on-exit fires when a watched command exits. --stream-command supervises a long-lived command and fires from batched stdout or stderr lines. Those are not ordinary “wake up at 9” jobs. They are bridges from external process events into agent work.
That is useful when an agent should react to a build event, a monitoring stream, or a local script that already knows when something changed. The key is restraint. A stream can produce lots of lines. OpenClaw batches, caps, and coalesces, but you still want your trigger pattern to be narrow enough that the agent sees signal, not a log firehose.
Cron vs heartbeat: pick the right loop
OpenClaw has another recurring surface: heartbeat. It is easy to confuse heartbeat with cron because both wake the agent. They solve different problems.
Automations are for precise schedules and detached work. They can run isolated, create task records, and deliver to a channel or webhook. The OpenClaw automation overview says to use automations for exact timing, reports, reminders, and background jobs.
Heartbeat is a periodic main-session turn. It is for approximate monitoring that benefits from the agent’s main-session context. The default cadence is 30 minutes, and heartbeat turns do not create background task records. They are meant for lightweight awareness: inbox checks, calendar monitoring, notifications, and “is there anything I should surface?” work.
Here is the practical rule I use:
- Use automations when the job has its own schedule, should be auditable, or should run isolated from the main conversation.
- Use heartbeat when the agent should periodically look around with main-session context and stay quiet unless something matters.
- Use hooks when the trigger is an OpenClaw lifecycle event, such as
/reset, session compaction, gateway startup, or message flow. - Use Task Flow when the work is a durable multi-step flow, not one scheduled turn.
The queue item for this post is a good example. A daily 7 AM docs-blog run belongs in automations, not heartbeat. It has a precise time, a repeatable pipeline, a visible deliverable, and a result Boss needs to review. That is scheduled background work.
The production details that save you later
The difference between a neat demo and a job you trust is usually not the prompt. It is the dull operational detail around the prompt.
Timeouts need a real policy
OpenClaw automations support per-run wall-clock budgets with --timeout-seconds. If you do not set one, isolated and detached agent-turn jobs are bounded by the scheduler’s 60-minute watchdog before the underlying agent-turn timeout would matter. Command jobs default to 10 minutes, and script payloads default to 5 minutes.
That is sensible. A scheduled agent should not hold the lane forever because a browser hung, a model provider stalled, or a remote API never came back.
If you drive openclaw agent from system cron anyway, wrap it with a hard-kill backstop. The OpenClaw docs recommend GNU timeout -k 60 600 openclaw agent ... rather than a plain timeout 600 .... GNU’s manual explains why: -k sends a final KILL signal after the first timeout signal if the process does not exit in time. That extra grace window gives the process a chance to drain, then stops pretending patience is a strategy.
Staggering is not a bug
Recurring top-of-hour cron expressions are automatically staggered by up to 5 minutes to reduce load spikes. If you truly need exact timing, use --exact. Most agent jobs do not need to start at exactly 09:00:00. They need to run reliably, produce a result, and avoid piling onto every other job on the box.
Duplicate runs should be boring
Scheduled jobs can overlap with retries, operator commands, or a previous run that has not finished. OpenClaw tracks active Gateway runs, and reusing a --run-id while the original Gateway run is still active reports the duplicate as in-flight instead of starting a second run.
That is the behavior you want for side-effecting jobs. If an agent sends a customer update, posts a draft, or changes a task tracker, the second copy should not casually do it again.
Delivery is part of the job
A scheduled report that finishes but never reaches the operator is not done in any meaningful sense. OpenClaw automations can deliver output to a channel, a webhook, or nowhere. Background tasks also track delivery state for detached work. That means you can separate “the agent ran” from “the answer landed where it should.”
This matters for multi-channel agents. A job bound to a Slack channel, iMessage conversation, or Telegram DM has a different failure shape from a silent nightly cleanup task. Treat delivery as part of the design, not an afterthought.
A practical setup pattern
If you are new to cron jobs for AI agents, start with a low-risk job. Do not begin with “send public messages every morning” or “auto-approve production changes.” Start with a draft, report, or reminder that you can inspect.
A solid first pattern looks like this:
- Create an isolated automation with a clear name and timezone.
- Give it a narrow prompt with one deliverable.
- Set a timeout that matches the job’s real budget.
- Deliver the result to your own review channel.
- Check
openclaw automations runs --id <job-id>after the first few runs. - Use
openclaw tasks listoropenclaw tasks auditwhen something looks off.
For a content agent, that might mean: every day at 7 AM, read the first unchecked topic from a queue, research it, write a WordPress draft, attach the hero image, and send the edit link. The human still reviews before anything goes live. That is a healthy automation boundary: the agent does the repeatable work, but the irreversible step stays human-owned.
For an ops agent, it might mean: every weekday morning, inspect overnight failures and send a summary. For a founder’s assistant, it might mean: every Friday afternoon, review open invoices, unread high-priority email, and next week’s calendar, then send a private digest.
The common thread is that the scheduled run has a job to do, a place to report, and a way to be audited.
Frequently asked questions
Can I still use system cron with an AI agent?
Yes. System cron is still useful when you deliberately want an outside scheduler to launch openclaw agent or another CLI command. Just add a hard timeout, log the run, and be honest about what you lose: Gateway-native task records, automation run history, channel delivery semantics, and scheduler-managed cleanup.
What is the best schedule type for a daily AI report?
Use an OpenClaw automation with --cron and an explicit --tz. Run it isolated if the report does not need current chat history. Send the output to a review channel. After a few runs, check run history and task records so you know what normal looks like.
When should I use heartbeat instead of automations?
Use heartbeat when the work is approximate and context-aware: inbox awareness, calendar monitoring, and lightweight notifications. Use automations when the job has exact timing, needs isolation, should create task records, or has a standalone deliverable.
Do OpenClaw automations retry failed jobs?
The scheduler records failures and has error handling for its own runtime paths, but you should still design the job prompt and tools with idempotency in mind. A retried agent run can repeat side effects unless the target operation has a stable key, draft-first workflow, or duplicate guard.
What should I monitor after creating an automation?
Watch three things: run history, task status, and delivery. A green-looking model answer is not the whole story. You want to know whether the schedule fired, whether the run reached a terminal state, and whether the result landed in the expected channel.
The right cron job is the one you can inspect
Cron jobs for AI agents are not just timers. They are promises that an agent will wake up later, do useful work, and report back without confusing yesterday’s context, duplicating side effects, or disappearing into a log file nobody reads.
OpenClaw’s automations get the shape right because the Gateway already owns the pieces that matter: sessions, channels, background tasks, run history, and delivery. Use that. Keep OS cron for the cases where an external trigger is truly what you want.
Start with one boring scheduled draft or report. Make it run on time. Make it easy to inspect. Make failure obvious. Once that feels dull, you can move higher-impact work into the same pattern with far less anxiety.
