Building an AI assistant that watches over your projects without flooding you with trivial updates is a subtle art. A well‑tuned heartbeat can keep you informed only when it truly matters.
HEARTBEAT_OK refers to a quiet, scheduled check‑in that runs in the background, remaining silent unless a condition requiring attention is detected.
Understanding HEARTBEAT_OK and Quiet Hours
OpenClaw’s heartbeat system is a system‑owned automation that executes periodic agent turns in the main session, allowing the model to surface anything that needs attention without spamming you (OpenClaw Heartbeat Guide).
The quiet hours feature lets you define time windows during which the assistant suppresses non‑critical notifications, ensuring you only receive alerts during work hours.
Configuring the HEARTBEAT.md File
The heartbeat behavior is driven by the HEARTBEAT.md configuration file. Follow these steps:
- Create a
HEARTBEAT.mdat the root of your OpenClaw project. - Define the cadence using a cron expression, e.g.,
0 */30 * * * *for a 30‑second interval. - Specify the
HEARTBEAT_OKflag to indicate a silent successful run. - Include a
quiet_hoursblock with start and end times in 24‑hour format.
Example snippet:
cron: "0 */30 * * * *"
HEARTBEAT_OK: true
quiet_hours:
start: "22:00"
end: "07:00"
Implementing Exact‑Match Silence
Exact‑match silence ensures the assistant remains mute when the output matches a predefined pattern. Add a silence_patterns array to HEARTBEAT.md:
- "No new tasks"
- "All systems nominal"
When the heartbeat result exactly matches any of these strings, the notification is suppressed.
Skipping Busy Rules for Proactive Alerts
A skipped‑busy rule tells the scheduler to ignore the heartbeat if the assistant is already handling a high‑priority task. This prevents redundant alerts during busy periods.
Configure it by adding a skip_if_busy flag:
skip_if_busy: true
When the assistant’s task queue exceeds a threshold, the heartbeat run is skipped, preserving system resources and reducing noise.
Best Practices and Monitoring
To keep your heartbeat reliable:
- Log each heartbeat execution with timestamps for audit trails.
- Use health‑check endpoints to verify the scheduler is alive (OpenClaw HEARTBEAT.md Guide).
- Periodically review silence patterns to avoid silencing genuine issues.
Frequently Asked Questions
What is the difference between HEARTBEAT_OK and a regular heartbeat?
HEARTBEAT_OK signals a successful, silent run, whereas a regular heartbeat may emit a notification regardless of result.
Can I have multiple quiet hour windows?
Yes, you can define an array of quiet_hours ranges to cover separate periods, such as evenings and weekends.
How does exact‑match silence handle variations in wording?
Exact‑match silence only suppresses notifications that match the pattern verbatim. For flexible matching, use regular expressions in the silence_patterns list.
Will skipping busy rules affect critical alerts?
No. Skipped‑busy only bypasses routine heartbeats; if a critical condition is detected, the assistant overrides the skip and sends an alert.
Do I need to restart the scheduler after editing HEARTBEAT.md?
Changes are picked up automatically on the next cron tick, but a manual reload ensures immediate application.
Neptune Infotech can help you integrate advanced AI automation like a quiet heartbeat into your enterprise solutions—reach out to explore a tailored implementation.
