OpenClaw Quiet Hours: Restrict Proactive Notifications

Introduction

Without quiet hours, a Heartbeat-driven alert will wake you at 2 AM for a non-critical condition. Your server's disk hit 86%? You get a notification. A routine email digest? Notification. A price alert for a stock you're watching? Notification. The agent doesn't know you're asleep. It just knows something happened and it's configured to tell you.

OpenClaw's quiet hours feature restricts proactive notifications to user-defined time windows — typically daytime. The Heartbeat still runs (tasks execute), but notifications are suppressed during quiet hours unless marked urgent. You get the benefit of 24/7 monitoring without the cost of 3 AM wake-ups.

Configuration

heartbeat:
  quiet_hours:
    start: "22:00"
    end: "07:00"
    timezone: "America/New_York"
  urgent_override: true  # Critical alerts bypass quiet hours

start and end define the window when notifications are suppressed. Outside this window (7 AM–10 PM in the example), notifications flow normally. Inside (10 PM–7 AM), they're held unless urgent.

timezone ensures the window aligns with your local time. If you're in PST but the server runs in UTC, you need this. Otherwise, "22:00" might not match your 10 PM.

urgent_override: When true, tasks marked as "urgent" in HEARTBEAT.md will notify even during quiet hours. Use for genuine emergencies: server down, security alert, critical failure.

active_hours can also restrict when Heartbeat runs at all — useful for reducing API cost (no cycles at night if no night tasks). See below.

Behavior

During quiet hours: Heartbeat runs, tasks execute, but notify_channel receives nothing unless urgent_override and task marked urgent. Result: server monitoring still works (scripts run, conditions are checked), but you're not woken for "disk at 86%." Critical: "server down" still alerts.

What happens to suppressed notifications? They're dropped. The agent doesn't queue them for morning delivery. If you want a "digest of what happened overnight," you need a separate task that runs at 7 AM and summarizes the night's events. Most users don't need that — they're fine with "if it was critical, I got it; if not, I'll find out in the morning."

Interactive messages (user-initiated) are never suppressed. Quiet hours apply only to proactive Heartbeat notifications. If you message the agent at 2 AM, it responds. The restriction is one-way: proactive → user, not user → agent.

Urgent Override: When Alerts Still Get Through

Mark tasks as urgent in HEARTBEAT.md:

## Server Health
- Check HTTP status every 30 min
- urgent: true
- escalate_if: status != 200

When the server goes down, the agent escalates, marks the alert urgent, and sends the notification even at 3 AM. You need to know. Quiet hours don't block that.

Use urgent sparingly. If everything is urgent, quiet hours are meaningless. Reserve it for: server down, security breach, payment failure, or similar. "New email from VIP" might feel urgent to you, but it probably shouldn't bypass quiet hours — that's a morning digest item.

Active Hours vs. Quiet Hours

Quiet hours: Heartbeat runs; notifications suppressed. Tasks execute; you just don't get notified (unless urgent). Use when you want 24/7 monitoring but don't want night alerts.

Active hours: Heartbeat doesn't run at all outside the window. No task execution, no API calls, no notifications. Use when you have no night tasks and want to save cost. Example: active_hours 07:00–22:00 means 15 hours of Heartbeat per day instead of 24. Fewer cycles, lower API spend.

Most users want quiet hours (monitoring continues, notifications suppressed). Power users who have only daytime tasks (e.g., morning digest, calendar sync) may prefer active hours for cost savings.

Best Practices

• Set quiet hours to match your sleep schedule: If you're in bed 11 PM–7 AM, configure that. Err on the side of longer quiet hours — you can always check the agent in the morning.
• Use urgent_override for genuine emergencies: Server down, security alert, critical failure. Don't mark "daily digest" as urgent.
• Mark tasks with urgency level in HEARTBEAT.md: Most tasks: urgent: false. A few: urgent: true. Document why. Future you will thank present you.
• Consider timezone when traveling: If you're in a different timezone, update config or use UTC and mental math. Some users run a script that adjusts quiet hours based on calendar "out of office" — advanced but possible.

Troubleshooting

"I'm still getting notifications at night": Check that the task isn't marked urgent. Check timezone — maybe your "night" isn't the server's "night." Verify config is loaded (check logs for "quiet_hours active").

"I didn't get an alert I should have": Was it during quiet hours? If the task wasn't marked urgent, it was suppressed. Either mark it urgent or accept that non-critical alerts wait until morning.

"Heartbeat isn't running at all at night": You might have active_hours configured instead of (or in addition to) quiet_hours. Active hours stop execution entirely. Check your config.

Wrapping Up

Quiet hours are essential for sustainable proactive automation. Without them, the agent becomes a liability — useful by day, annoying by night. With them, you get 24/7 monitoring and 8 hours of peace. See Heartbeat Engine for full config and HEARTBEAT.md for task configuration.