Lesson 870 of 2116
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.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1The four trigger families
- 2interval trigger
- 3cron schedule
- 4event trigger
Concept cluster
Terms to connect while reading
Section 1
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.
An 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.
soul:
name: inbox-watcher
heartbeat:
type: interval
every: 5m
max_iterations: 200Cron 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.
A cron heartbeat fires the soul at 8 AM Eastern, weekdays only. The runtime handles DST; you handle the timezone.
soul:
name: morning-briefing
heartbeat:
type: cron
schedule: "0 8 * * 1-5" # 8:00 AM, weekdays only
timezone: America/New_YorkEvent 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.
Wake on GitHub PR events. Debounce coalesces a flurry of pushes into a single beat — without it, a 10-commit push fires 10 reviews.
soul:
name: pr-reviewer
heartbeat:
type: event
on:
- webhook: github.pull_request.opened
- webhook: github.pull_request.synchronize
debounce: 30sSelf-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
Compare the options
| 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
Key terms in this lesson
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 quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Time-Based And Event-Based Heartbeats: Choosing The Trigger”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 45 min
Structured Outputs: Make the Model Return Data You Can Trust
For production apps, pretty prose is often the wrong output. Learn when to use structured outputs, function calling, and schema validation.
Creators · 9 min
Pro Search vs Default: When To Spend The Compute
Pro Search runs more queries, reads more pages, and routes to a stronger model. It is not always worth the wait — knowing when it is is the skill.
Creators · 10 min
Perplexity API: Building RAG Without Owning The Pipeline
The Perplexity API gives you cited search answers with one call. It is the cheapest way to add grounded retrieval to a product — and the limits are worth understanding.