openclaw - 💡(How to fix) Fix Feature Request: Agent Heartbeat Queue During Active Turn [1 comments, 2 participants]

Description

Feature Request: Add configuration option to queue heartbeat polls during an active agent turn instead of interrupting the turn.

Problem

Currently, when an agent is in the middle of a multi-step task (e.g., building a system), heartbeat polls from the gateway interrupt the agent's turn, ending it prematurely. This breaks the workflow for long-running tasks.

The current behavior is defined in HEARTBEAT.md:

• Active Hours: 08:00–23:00 ET
• If current time is outside active hours → reply HEARTBEAT_OK immediately, no checks

During active hours, heartbeat polls interrupt the agent mid-turn, which:

• Breaks context for multi-step tasks
• Makes it impossible to complete longer workflows
• Forces the agent to constantly restart from checkpoints

Proposed Solution

Add a config option in openclaw.json, for example:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "queueDuringActiveTurn": true
      }
    }
  }
}

When enabled, heartbeat events would be queued and delivered when the agent finishes its current turn rather than interrupting mid-turn.

Alternative Considered

• Lowering cron frequency (done as a workaround)
• Modifying gateway code (not recommended - would be overwritten on updates)

Priority

Medium - improves agent workflow for multi-step tasks

Additional Notes

• The schema already has agents.defaults.heartbeat and agents.list[].heartbeat defined as empty objects, suggesting this was a planned but not implemented feature
• The schema also has web.heartbeatSeconds which is also empty