.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw is fun when it replies in chat. It gets useful when it shows up by itself at the right time with the right message. That’s what the built-in cron scheduler is for. It runs inside the Gateway process so you don’t need a separate job runner and it can deliver results straight back to Telegram WhatsApp Slack Discord and more.
People hear “cron” and think “Linux crontab.” The idea is similar but the goal is different. This isn’t just “run a script at 7 AM.” It’s “wake the agent run a prompt or drop a system event into the main session then deliver output where I will actually see it.”
If you already use webhooks to trigger runs from GitHub Stripe or n8n you can think of cron as the other half of the same toolbox. Webhooks are event-driven and cron is time-driven. The mechanics of delivery look similar. If you want the webhook side explained properly see OpenClaw webhooks explained.
What the OpenClaw cron scheduler actually does
OpenClaw cron is a scheduler that lives inside the Gateway. You create jobs and the Gateway wakes them when they are due. Jobs are persisted to disk so a restart doesn’t wipe your schedule. Each run can also write a small run record so you can see what happened when something fails.
Once cron is enabled you can use it for things people normally glue together with random scripts:
- daily briefings that arrive on your phone at a fixed hour
- one-shot reminders that fire in 20 minutes
- weekly “deep review” prompts that use a stronger model without touching your main chat
- monitoring loops like “check prices every 6 hours and alert only on meaningful changes”
And yes it can deliver results to multiple channels. You can send the same job output to a private Telegram chat and also to a Slack channel if you want. Just don’t do that for noisy jobs unless you like being muted by your team.
Cron vs heartbeat
OpenClaw has another scheduling mechanism called heartbeat. People mix these up then wonder why token costs jump or why jobs feel “late.” The clean mental model is simple.
Heartbeat is a periodic sweep inside your main session
Heartbeat runs on an interval and it reads a checklist from a file (often named HEARTBEAT.md). It’s meant for routine awareness like “scan inbox for urgent messages” or “look at my calendar for the next two hours.” It batches multiple checks into one agent turn which keeps cost under control if you keep the checklist disciplined.
Heartbeat fits tasks that are fine being “roughly every 30 minutes” instead of “exactly at 09:00.” It also fits tasks that benefit from main-session context like ongoing projects and prior decisions.
Cron is for exact timing and isolated runs
Cron is for tasks that need a precise schedule or tasks you want to keep out of your main conversation history. A daily report at 9 AM is the obvious example. Another one is a weekly review that runs in a clean isolated session and only posts the final result back to you.
Most setups use both. Heartbeat handles the recurring background checks and cron handles “at a specific time” and “run this job in isolation.”
How cron jobs are stored and why that matters
OpenClaw keeps cron job definitions on disk and it keeps per-run history separately. That persistence is the reason cron works well on a VPS. If the box restarts your schedules are still there.
It also means two practical things:
- if the Gateway is not running then cron is not running because it lives inside the Gateway
- if you are testing jobs on a laptop that sleeps you will miss schedules
If you want cron to be reliable use an always-on host. That’s one reason a VPS deployment is popular. The guide OpenClaw VPS hosting now available explains the general idea without drowning you in setup trivia.
The three schedule types
OpenClaw cron supports three scheduling patterns and you pick based on the job you’re building. I’ll show CLI examples because they’re concrete. If you prefer chat-driven setup you can also just tell the agent what you want and it can create the job for you.
One-shot scheduling with at
Use this for “remind me in 20 minutes” or “run once at 16:00 UTC.” It executes once and then you usually delete it automatically after it runs.
openclaw cron add \
--name "Call back reminder" \
--at "20m" \
--session main \
--system-event "Reminder: call the client back." \
--wake now \
--delete-after-runOne-shot jobs are also great for personal reminders because they don’t clutter your permanent job list. You create them and forget about them.
Interval scheduling with every
Use this for “every 4 hours” or “every 30 minutes” jobs where exact clock alignment is not the point. It’s a steady interval.
openclaw cron add \
--name "Price check" \
--every "6h" \
--session isolated \
--message "Check monitored product prices. Alert me only on meaningful drops." \
--announce \
--channel telegram \
--to "123456789"If you are doing frequent checks like every 10 minutes you should pause and ask if heartbeat would batch it better. High frequency cron runs can get expensive fast if each run is a full agent turn.
Cron expressions with cron
Use this when you want “every weekday at 07:00” or “every Monday at 09:00.” You provide a cron expression and optionally a timezone.
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * 1-5" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Send my morning brief. Calendar first then inbox highlights then any blockers." \
--announce \
--channel whatsapp \
--to "+15551234567"If cron expressions feel rusty here are a few quick patterns that come up often:
0 7 * * *every day at 07:000 9 * * 1every Monday at 09:000 7 * * 1-5weekdays at 07:000 6 1 * *first day of the month at 06:000 * * * *every hour
If you need a reference for cron expression syntax the Wikipedia page is fine for a quick refresher. Cron expression overview
Main session jobs vs isolated jobs
This is the decision that changes how your system feels.
Main session mode
A main session cron job drops a system event into your main session then the agent processes it with full context. This is nice for tasks that depend on ongoing context like “continue that operations checklist we were doing” or “follow up on the vendor thread.”
Main session jobs are also cheaper when they are designed to be handled inside heartbeat. In that pattern cron is just placing a timed note and heartbeat is the runner that processes it.
Main session jobs are created with a system event payload:
openclaw cron add \
--name "Expense reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: submit the expense report." \
--wake now \
--delete-after-runOne downside is that main-session tasks can interrupt a busy conversation. If you schedule too many of them your main session starts feeling like a notification feed.
Isolated session mode
An isolated job runs a dedicated agent turn in its own session. It does not drag your main conversation into it. It’s clean and it’s safer for noisy tasks like monitoring and summaries because your main session stays readable.
Isolated jobs are created with a message payload:
openclaw cron add \
--name "Weekly review" \
--cron "0 9 * * 1" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Weekly review: open PRs, merged PRs, CI failures, open issues and blockers." \
--announce \
--channel slack \
--to "channel:C1234567890"Isolated runs also unlock a practical cost trick: you can use a cheaper model for routine summaries and reserve the expensive model for the once-a-week deep review. Model choice matters a lot and it’s covered in Claude vs OpenAI model choice in OpenClaw.
Delivery options and targeting
A cron job can run and do nothing visible or it can deliver output to a channel. The right default depends on the job. A job that always produces useful output should deliver. A job that only sometimes produces a signal should probably deliver only on signal.
Announce delivery to a messaging channel
Announce means “send me the result.” You pick the channel and the recipient. Targets differ by platform.
- Telegram often uses a numeric chat id
- WhatsApp and Signal use E.164 numbers like
+15551234567 - Slack and Discord use channel or user identifiers such as
channel:...oruser:...
If you run OpenClaw across multiple channels already and want to keep your setup tidy the multi-channel setup guide helps you avoid the usual “why did it reply in the wrong place” confusion.
Webhook delivery
Some people want cron output to go into another system instead of a chat. Example: a nightly export that posts into an internal API. In that case delivery by webhook is the cleaner route. Your job finishes and posts a JSON envelope to your endpoint.
If you use webhook delivery you should still treat that destination as a real integration with auth and retries. The general webhook hardening advice is the same as any other external trigger system.
No delivery
Sometimes you want cron to do work that is purely internal like refreshing a local cache or running a maintenance analysis that you only inspect when needed. In that mode you keep delivery off and you rely on run history when debugging.
Model and thinking overrides for scheduled jobs
Scheduled work has a weird failure mode: you forget it exists then you notice the bill. The easiest control knob is to set a cheaper model for routine jobs and keep “high effort” reasoning for less frequent runs.
Isolated jobs are the natural place to do this. Example:
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Weekly deep analysis of project progress and risks." \
--model "opus" \
--thinking high \
--announce \
--channel telegram \
--to "123456789"If you are also running a proxy for model routing and cost controls that’s another layer of savings but don’t overcomplicate it on day one. Get one job running cleanly first.
Creating cron jobs via chat
You don’t have to touch the CLI if you don’t want to. You can ask your agent something like:
"Create a daily cron job at 7 AM UTC. Summarize my calendar for today and highlight urgent emails. Send it to this Telegram chat."
The agent can convert that into a cron schedule plus an isolated message payload plus delivery targeting. When time or timezone is ambiguous it should ask instead of guessing. If it doesn’t ask you will eventually get a 7 AM surprise in the wrong timezone and you will hate cron for the wrong reason.
Real job patterns examples
Morning briefing (without spam)
A good morning briefing is short and biased toward action. It should not paste your whole calendar and it should not summarize every newsletter. A practical prompt asks for “what matters” and includes clear limits.
openclaw cron add \
--name "Morning briefing" \
--cron "0 7 * * *" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Morning briefing. List today’s calendar items with times. Then list urgent emails only. End with 2 or 4 suggested actions." \
--announce \
--channel telegram \
--to "123456789"If your briefing includes email and calendar data you will want those integrations set up properly first. The related guides are OpenClaw Gmail integration and email automation and OpenClaw Google Calendar integration.
Weekly review that uses a stronger model
This is where “scheduled AI” shines. It’s hard to sit down every Monday and do a calm review. Cron does not get tired.
openclaw cron add \
--name "Weekly review" \
--cron "0 9 * * 1" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Weekly review. Summarize progress. List blockers. Mention open PRs and failed CI runs. Suggest next steps." \
--model "opus" \
--thinking high \
--announce \
--channel slack \
--to "channel:C1234567890"If you want this review to include GitHub context you can integrate GitHub first. The guide OpenClaw GitHub automation for PR reviews and CI monitoring shows the usual setup patterns.
One-shot reminders that land in the main session
One-shot reminders are the safest thing to do in the main session because they behave like “a timed note.” They don’t need an isolated session and they don’t need a fancy prompt. Keep them boring.
openclaw cron add \
--name "Standup reminder" \
--at "20m" \
--session main \
--system-event "Reminder: standup starts in 10 minutes." \
--wake now \
--delete-after-runScraping and monitoring tasks
Cron is a natural fit for scraping and monitoring because you want repeated checks and alerts only when something changes. Most people do this as an isolated job that queries a store of previous values then decides if an alert is worth sending.
If you use OpenClaw for the scraping itself the dedicated scraping guide is web scraping with OpenClaw.
CLI management commands you will use a lot
Once you have more than a couple jobs you need basic hygiene. These are the commands people actually reach for:
openclaw cron listto see all jobsopenclaw cron run <jobId>to test a job immediatelyopenclaw cron edit <jobId>to change schedule prompt model or targetopenclaw cron pause <jobId>andopenclaw cron resume <jobId>when you need a breakopenclaw cron remove <jobId>when a job is no longer useful
And don’t skip “runs” or history. When a job fails it fails silently unless you look. Run history is how you answer “did it fire” without guessing.
Troubleshooting when jobs do not fire
The Gateway was not running
Cron runs inside the Gateway. If the process is down nothing runs. This is the most common reason a schedule “didn’t work.” On servers you want OpenClaw managed by systemd so it restarts and starts on boot. The guide how to host OpenClaw securely on a VPS also covers the ops pieces that usually cause downtime.
Timezone confusion
If your schedule uses a timezone argument confirm it matches your intent. If you do not specify one then the host timezone is used. That’s fine on a personal machine. It’s annoying on a VPS you deployed in a random region then forgot about.
The job ran but you never saw output
This is almost always delivery targeting. The job ran and wrote a run record but it did not announce to a channel or it announced to a target you no longer watch.
For chat delivery you need three things to be true:
- the channel integration is working
- the
totarget is correct - the job is set to announce or deliver results
For Telegram and Discord setup details the channel docs help a lot. Try connect OpenClaw to Telegram via BotFather and connect OpenClaw to Discord if those are your primary endpoints.
When cron is not enough and you need workflows
Cron is “start something at a time.” It is not a workflow engine. If your job needs multi-step tool calls plus approvals plus a pause-resume pattern you’ll want a workflow runtime. In the OpenClaw stack that role is often filled by Lobster where cron decides when the run happens then Lobster decides what steps happen and where approvals are required.
Most people only need that once they start doing real operational automations like “scrape prices then update a sheet then open a GitHub issue then wait for approval then send an email.” If you are still at “daily brief at 7” cron is enough.
