openclaw - 💡(How to fix) Fix Bug: hasExplicitHeartbeatAgents causes global heartbeat defaults to be ignored when any agent has explicit config [3 comments, 2 participants]

Bug Description

When any agent in agents.list has an explicit heartbeat config, the global agents.defaults.heartbeat setting is completely ignored for agents that don't have their own heartbeat config.

This means a single agent with heartbeat: { every: "0m" } can inadvertently disable heartbeat for ALL other agents that rely on the global default.

Root Cause

In heartbeat-summary.ts, the isHeartbeatEnabledForAgent function:

function isHeartbeatEnabledForAgent(cfg, agentId) {
  if (hasExplicitHeartbeatAgents(cfg)) {
    // Requires THIS agent to have explicit heartbeat config
    return list.some(entry => Boolean(entry?.heartbeat) && entry.id === agentId);
  }
  // Only reaches here if NO agent has heartbeat config
  if (cfg.agents?.defaults?.heartbeat) return true;
}

hasExplicitHeartbeatAgents checks if ANY agent in the list has a heartbeat config. If so, it enters a mode where ONLY agents with explicit heartbeat are considered enabled — the global default is never consulted.

Reproduction

{
  "agents": {
    "defaults": {
      "heartbeat": { "every": "600m" }
    },
    "list": [
      { "id": "main" },
      { "id": "sexmaid", "heartbeat": { "every": "0m" } }
    ]
  }
}

Expected: main uses global default 600m heartbeat. Actual: main heartbeat is disabled because hasExplicitHeartbeatAgents returns true (due to sexmaid), and main has no explicit heartbeat config.

Impact

• Cron jobs targeting session: main are silently skipped with "error": "disabled"
• The system event is enqueued but never processed because runHeartbeatOnce returns skipped
• Users have no visibility into why their main session cron jobs fail

Suggested Fix

The correct behavior should be agent-level config overriding global defaults, not an all-or-nothing mode:

function isHeartbeatEnabledForAgent(cfg, agentId) {
  const agentEntry = list.find(e => normalizeAgentId(e?.id) === agentId);
  // If this agent has explicit heartbeat, use it (even if every=0 means disabled)
  if (agentEntry?.heartbeat) {
    return Boolean(agentEntry.heartbeat.every);
  }
  // Otherwise fall back to global default
  if (cfg.agents?.defaults?.heartbeat) return true;
  return resolveAgentId === resolveDefaultAgentId(cfg);
}