openclaw - 💡(How to fix) Fix Feature: Heartbeat auto-toggle when periodic tasks exist [1 comments, 2 participants]

Summary

Let heartbeat auto-enable when HEARTBEAT.md has active tasks, and auto-disable when it is empty.

Problem to solve

Currently agents.defaults.heartbeat.every is a static interval. If set to e.g. 30m, it runs every 30 minutes regardless of whether there are any periodic tasks to check. This wastes API calls (and therefore cost) when HEARTBEAT.md is empty or contains only comments.

The user has to manually change the config every time they want to add/remove periodic tasks, which defeats the purpose of a smart agent.

Proposed solution

Add a new heartbeat mode that checks whether HEARTBEAT.md (or the configured prompt file) contains actionable content before triggering a heartbeat turn.

Option A – auto mode for every:

agents:
  defaults:
    heartbeat:
      every: "auto"

When every: "auto":

• Before each scheduled heartbeat window, check if HEARTBEAT.md has any non-comment, non-whitespace content.
• If yes → run heartbeat as normal.
• If no (empty or only comments) → skip, no model invocation.
• A new config field like autoCheckInterval: "30m" controls how often to re-check the file.

Option B – Lighter-touch: Heartbeat always runs but returns HEARTBEAT_OK without model call when file is empty. This is simpler to implement but still incurs scheduling overhead.

Option C – Smart hook: Trigger heartbeat only when HEARTBEAT.md is modified. Use a file watcher on HEARTBEAT.md → when saved, schedule a one-shot heartbeat; when file is cleared, cancel pending heartbeat.

Alternatives considered

1. Status quo (static every): Simple but wasteful. User pays for empty turns.
2. Manual toggle: User sets every: "0" / every: "30m" via config. Works but friction, easily forgotten.
3. Only use cron instead of heartbeat: Cron already supports exact scheduling. But heartbeat has simpler HEARTBEAT.md workflow and is better for users who want the write-a-task-and-get-remembered pattern.

Impact

• Affected users: All OpenClaw users with heartbeat enabled, especially self-hosted users who pay per-token (DeepSeek, OpenAI, etc.).
• Severity: Moderate annoyance / cost leakage. One user reported ~48 model calls/day from empty heartbeats, each loading the full conversation context.
• Frequency: Always — every heartbeat cycle when HEARTBEAT.md is empty.
• Consequence: Unnecessary billing charges. For a user on paid API, this could add $5-30/month depending on context size and model pricing.

Evidence/examples

• User workflow: wants periodic weather reminders → sets up HEARTBEAT.md → turns on heartbeat → task done → clears HEARTBEAT.md → still pays for empty heartbeats until they remember to disable it.
• User asked: Does OpenClaw call the model even when I am not talking to it? — yes, heartbeat does.

Additional information

• Config schema already has agents.defaults.heartbeat.every (string type). An "auto" value would be backward-compatible.
• HEARTBEAT.md already exists as the canonical task file. Reusing it avoids adding another config surface.
• The file-watch approach (Option C) would need chokidar or similar, which is already a bundled dependency in OpenClaw plugin runtime.