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

In your ~/.openclaw/openclaw.json, the heartbeat config lives at agents.defaults.heartbeat. The activeHours block controls when heartbeat runs:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "telegram",
        "activeHours": {
          "start": "07:00",
          "end": "22:00",
          "timezone": "America/New_York"
        }
      }
    }
  }
}

start (inclusive) and end (exclusive) define the window when heartbeat runs. Outside this window (10 PM–7 AM in the example), heartbeat is skipped entirely — no task execution, no API calls, no notifications.

timezone ensures the window aligns with your local time. Use an IANA identifier like "America/New_York". If you're in PST but the server runs in UTC, you need this. Otherwise, "07:00" might not match your 7 AM. You can also use "local" for the host timezone or omit it to fall back to agents.defaults.userTimezone.

For tasks that must bypass quiet hours (server down, security alerts), write urgency instructions directly in HEARTBEAT.md: "Alert at any hour if server returns non-200. Include in morning briefing only if informational."

Behavior

Outside active hours: Heartbeat doesn't run at all — no tasks execute, no API calls, no notifications. This is the simplest way to avoid 3 AM alerts and reduce API cost. For tasks that need 24/7 coverage (like server monitoring), write urgency-level instructions in HEARTBEAT.md so the agent handles critical vs. non-critical alerts at the task level during active hours.

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.

How Active Hours Work

OpenClaw uses activeHours in the heartbeat config to control when heartbeat runs. Outside the active window, heartbeat is skipped entirely — no task execution, no API calls, no notifications. This is the primary mechanism for restricting nighttime activity.

Example: activeHours set to 07:00–22:00 means 15 hours of heartbeat per day instead of 24. Fewer cycles, lower API spend, and no nighttime alerts.

For users who need 24/7 monitoring but want to suppress non-critical notifications at night, the approach is to keep activeHours running 24/7 (or omit the block entirely) and write urgency-level instructions in HEARTBEAT.md: "If server returns non-200, alert immediately regardless of time. If disk usage is above 85%, include in morning briefing only." The agent respects these instructions and makes the judgment call on whether to send the notification.

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 your activeHours config. Is the end time correct? Is timezone set to your local IANA timezone? If the server is in UTC and you're in EST, "22:00" without a timezone means 10 PM UTC (5 PM EST). Check the Dashboard Heartbeat tab to see if ticks are still firing outside your expected window.

"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": Check your activeHours config in agents.defaults.heartbeat. If activeHours.end is set to "22:00", heartbeat stops entirely after 10 PM. Either extend the window or remove activeHours to run 24/7.

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.