Time-Based And Event-Based Heartbeats: Choosing The Trigger

OpenClaw souls can wake on a clock, on a webhook, on a message, or on an internal signal. The trigger you pick shapes what kind of agent you actually have.

10 min · Reviewed 2026

The four trigger families

Every OpenClaw heartbeat reduces to a question: what makes the soul wake up? There are four answers worth knowing — interval, cron, event, and self-paced — and most production souls compose two or three of them.

Interval heartbeats

The simplest trigger: 'wake every N seconds.' Good for monitoring loops, ambient awareness, gentle background reflection. The runtime keeps a timer; when it fires, the soul runs one beat and the timer resets.

soul: name: inbox-watcher heartbeat: type: interval every: 5m max_iterations: 200An interval heartbeat. Every 5 minutes, the soul wakes up and checks its inbox. After 200 beats it stops on its own — a safety cap we cover in lesson three.

Cron heartbeats

When 'every 5 minutes' isn't precise enough, a cron expression nails the soul to a calendar. Useful for daily digests, weekly summaries, end-of-month reports — anything that should run at a specific time, not a relative one.

soul: name: morning-briefing heartbeat: type: cron schedule: "0 8 * * 1-5" # 8:00 AM, weekdays only timezone: America/New_YorkA cron heartbeat fires the soul at 8 AM Eastern, weekdays only. The runtime handles DST; you handle the timezone.

Event heartbeats

Sometimes the world should wake the soul, not the clock. Event heartbeats fire on incoming webhooks, queue messages, file changes, or other runtime signals. The soul reacts — but inside the agent loop, with full memory, not as a stateless handler.

soul: name: pr-reviewer heartbeat: type: event on: - webhook: github.pull_request.opened - webhook: github.pull_request.synchronize debounce: 30sWake on GitHub PR events. Debounce coalesces a flurry of pushes into a single beat — without it, a 10-commit push fires 10 reviews.

Self-paced heartbeats

The most agentic option: the soul itself sets the next beat. After running, it can return 'wake me in 90 seconds' or 'wake me when X arrives.' Useful when the rhythm depends on what the soul just learned — a slow heartbeat while idle, a fast one while a task is in flight.

Choosing the right trigger

You want	Use	Why
Background reflection on memory	Interval (slow, e.g. 1h)	Doesn't need to be precise
8 AM digest, weekdays only	Cron	Calendar-anchored, DST-safe
React to a webhook in seconds	Event	Latency matters; events carry context
A goal that needs faster polling while active	Self-paced + interval cap	Adaptive rhythm
Watch an inbox and write a daily summary	Event (on new mail) + Cron (8 AM digest)	Composed triggers
Free-running brainstorm with no real-time need	Cron once a day	Cheapest pattern that still feels alive

Composing triggers

Most useful souls have two triggers, not one — one for routine work, one for reactive work
Compose them in priority order: an event beat preempts a scheduled beat (the soul wakes immediately)
Add a debounce to event triggers to avoid thrashing on bursty signals
Add a floor to all triggers — no soul should beat more than once per second by default
Log every beat with its trigger source — 'why did the soul wake up?' is the first debugging question

The big idea: pick the trigger that matches the soul's job. Interval for ambient. Cron for calendar. Event for reactive. Self-paced for adaptive. Most production souls compose two.

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-openclaw-heartbeats-time-vs-event-creators

What is the main idea of "Time-Based And Event-Based Heartbeats: Choosing The Trigger"?
1. OpenClaw souls can wake on a clock, on a webhook, on a message, or on an internal signal.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Time-Based And Event-Based Heartbeats: Choosing The Trigger"?
1. cron schedule
2. interval trigger
3. event trigger
4. on-message
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. Most useful souls have two triggers, not one — one for routine work, one for reactive work
4. Treat the AI output as automatically correct
What should a careful learner remember about "Self-paced is powerful and dangerous"?
1. Use AI to draft or organize ideas about interval trigger, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about interval trigger be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about interval trigger.
Which action would help you apply "Time-Based And Event-Based Heartbeats: Choosing The Trigger" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Compose them in priority order: an event beat preempts a scheduled beat (the soul wakes immediately)

← Back to interactive lesson

Tendril · Creators · Tools Literacy