Per-Agent & Multi-Account Heartbeats

+15 Mana ✨
OpenClaw Multi-Agent Configuration(DOCUMENTATION)OpenClaw Cost Optimization Guide(DOCUMENTATION)

Introduction

When running multiple agents or managing multiple cloud accounts, heartbeat configuration becomes more nuanced. Each agent can override global heartbeat settings, and you can target specific accounts to distribute cost. This lesson covers agent-level overrides, accountId targeting, and cost optimization strategies.

Key Concepts

  • Agent-Level Override: Heartbeat settings defined on a specific agent that take precedence over the global defaults
  • accountId Targeting: Directing heartbeat API calls to a specific cloud provider account for cost tracking and rate limit management
  • Model Override: Using a cheaper or faster model specifically for heartbeat turns to reduce cost
  • target: "none": Suppressing all output to run heartbeats purely for logging and metrics
  • Cost Optimization: Strategies for reducing the per-cycle cost of heartbeat operations

Real World Context

A consultancy manages OpenClaw agents for three different clients, each with their own AI provider account. Client A needs aggressive 10-minute monitoring on their production systems. Client B wants hourly checks on staging. Client C only needs daily health snapshots. By using per-agent heartbeat overrides and accountId targeting, the consultancy configures all three in one Gateway while billing each client's API usage to their own account.

Deep Dive

Agent-Level Heartbeat Overrides

Global heartbeat settings apply to all agents by default. Any agent can override these settings:

json
{
  "agents": {
    "defaults": {
      "heartbeat": {
        "interval": 30,
        "showOk": true,
        "showAlerts": true
      }
    },
    "list": [
      {
        "id": "prod-monitor",
        "heartbeat": {
          "interval": 10,
          "showOk": false
        }
      },
      {
        "id": "staging-watcher",
        "heartbeat": {
          "interval": 60
        }
      }
    ]
  }
}

In this configuration, the global defaults set a 30-minute interval with all visibility enabled. The prod-monitor agent overrides the interval to 10 minutes and suppresses OK messages. The staging-watcher extends the interval to 60 minutes but inherits all other defaults. Only the fields you specify in the override are changed; everything else falls through to the defaults.

accountId Targeting

When multiple AI provider accounts are configured, you can direct heartbeat API calls to a specific account:

json
{
  "agents": {
    "list": [
      {
        "id": "client-a-monitor",
        "heartbeat": {
          "interval": 10,
          "accountId": "acct_client_a_prod"
        }
      },
      {
        "id": "client-b-monitor",
        "heartbeat": {
          "interval": 60,
          "accountId": "acct_client_b_staging"
        }
      }
    ]
  }
}

Each agent's heartbeat calls are billed to the specified account. This enables precise cost allocation in multi-tenant environments.

Cost Optimization with Model Overrides

Heartbeat checks often do not require the full reasoning power of a frontier model. You can specify a lighter model for heartbeat turns:

json
{
  "agents": {
    "list": [
      {
        "id": "cost-efficient-monitor",
        "model": {
          "primary": "anthropic:claude-sonnet-4-20250514"
        },
        "heartbeat": {
          "interval": 30,
          "model": "anthropic:claude-haiku-3",
          "target": "none"
        }
      }
    ]
  }
}

This agent uses Claude Sonnet for interactive conversations but switches to Claude Haiku for heartbeat turns. Combined with target: "none", this creates a silent, cost-efficient monitoring loop. The cost savings can be substantial: Haiku is significantly cheaper per token than Sonnet.

Silent Monitoring Pattern

The combination of target: "none", showOk: false, and a cheap model creates a purely background monitoring pattern. The agent checks everything, logs results internally, but produces zero visible output unless you query the logs explicitly. This is ideal for compliance auditing where you need a record of checks but do not want to clutter any conversation channels.

Common Pitfalls

  • Overriding too many fields per agent: If every agent has completely different heartbeat config, consider whether they should share a Gateway at all.
  • Using expensive models for heartbeat without justification: Frontier models are overkill for simple health checks. Use lighter models for routine monitoring.
  • Forgetting that accountId affects rate limits: Targeting a specific account means heartbeat calls count against that account's rate limits.

Best Practices

  • Use model overrides for heartbeat turns to reduce cost by 5-10x compared to using the primary model.
  • Set target: "none" for background monitoring agents that should not produce user-facing output.
  • Track per-agent cost by assigning distinct accountIds, even if they share the same billing entity.

Summary

  • Agent-level overrides let each agent customize interval, visibility, and routing independently
  • accountId targeting directs heartbeat API costs to specific cloud provider accounts
  • Model overrides let you use a cheaper model for heartbeat turns while keeping the primary model for conversations
  • target: "none" combined with a light model creates a cost-efficient silent monitoring loop
  • Override only the fields that differ from global defaults to keep configuration maintainable
✓ Completed