​

Heartbeat (Gateway)

Heartbeat ou Cron ? Voir Cron vs Heartbeat pour savoir quand utiliser chacun.

​

Démarrage rapide (débutant)

1. Laissez les heartbeats activés (la valeur par défaut est 30m, ou 1h pour Anthropic OAuth/setup-token) ou définissez votre propre cadence.
2. Créez une petite checklist HEARTBEAT.md dans l’espace de travail de l’agent (facultatif mais recommandé).
3. Décidez où doivent aller les messages de heartbeat (target: "last" est la valeur par défaut).
4. Facultatif : activez la livraison du raisonnement du heartbeat pour plus de transparence.
5. Facultatif : limitez les heartbeats aux heures actives (heure locale).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

Valeurs par défaut

• Intervalle : 30m (ou 1h lorsque le mode d’authentification détecté est Anthropic OAuth/setup-token). Définissez agents.defaults.heartbeat.every ou par agent agents.list[].heartbeat.every ; utilisez 0m pour désactiver.
• Corps du prompt (configurable via agents.defaults.heartbeat.prompt) : Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• Le prompt de heartbeat est envoyé verbatim en tant que message utilisateur. Le prompt système inclut une section « Heartbeat » et l’exécution est marquée en interne.
• Les heures actives (heartbeat.activeHours) sont vérifiées dans le fuseau horaire configuré. En dehors de la plage, les heartbeats sont ignorés jusqu’au prochain tick dans la fenêtre.

​

À quoi sert le prompt de heartbeat

• Tâches en arrière-plan : « Consider outstanding tasks » incite l’agent à revoir les suivis (boîte de réception, calendrier, rappels, travail en file d’attente) et à faire remonter l’urgent.
• Prise de contact humaine : « Checkup sometimes on your human during day time » incite à un message léger occasionnel du type « avez-vous besoin de quelque chose ? », tout en évitant le spam nocturne grâce au fuseau horaire local configuré (voir /concepts/timezone).

​

Contrat de réponse

• Si rien ne nécessite d’attention, répondez avec HEARTBEAT_OK.
• Pendant les exécutions de heartbeat, OpenClaw traite HEARTBEAT_OK comme un accusé de réception lorsqu’il apparaît au début ou à la fin de la réponse. Le jeton est supprimé et la réponse est ignorée si le contenu restant est ≤ ackMaxChars (par défaut : 300).
• Si HEARTBEAT_OK apparaît au milieu d’une réponse, il n’est pas traité de manière spéciale.
• Pour les alertes, n’incluez pas HEARTBEAT_OK ; renvoyez uniquement le texte d’alerte.

​

Configuration

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific override
        accountId: "ops-bot", // optional multi-account channel id
        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
      },
    },
  },
}

​

Portée et priorité

• agents.defaults.heartbeat définit le comportement global des heartbeats.
• agents.list[].heartbeat fusionne par-dessus ; si un agent possède un bloc heartbeat, seuls ces agents exécutent des heartbeats.
• channels.defaults.heartbeat définit les valeurs de visibilité par défaut pour tous les canaux.
• channels.<channel>.heartbeat remplace les valeurs par défaut des canaux.
• channels.<channel>.accounts.<id>.heartbeat (canaux multi-comptes) remplace les paramètres par canal.

​

Heartbeats par agent

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        },
      },
    ],
  },
}

​

Exemple d’heures actives

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

Exemple multi-compte

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Notes de champ

• every : intervalle de heartbeat (chaîne de durée ; unité par défaut = minutes).
• model : remplacement optionnel du modèle pour les exécutions de heartbeat (provider/model).
• includeReasoning : lorsqu’activé, livre aussi le message séparé Reasoning: lorsqu’il est disponible (même structure que /reasoning on).
• session : clé de session optionnelle pour les exécutions de heartbeat.
  • main (par défaut) : session principale de l’agent.
  • Clé de session explicite (copiez depuis openclaw sessions --json ou le CLI des sessions).
  • Formats de clé de session : voir Sessions et Groups.
• target :
  • last (par défaut) : livrer vers le dernier canal externe utilisé.
  • canal explicite : whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none : exécuter le heartbeat mais ne pas livrer en externe.
• to : remplacement optionnel du destinataire (id spécifique au canal, p. ex. E.164 pour WhatsApp ou un id de chat Telegram).
• accountId : id de compte optionnel pour les canaux multi-comptes. Lorsque target: "last", l’id de compte s’applique au dernier canal résolu s’il prend en charge les comptes ; sinon il est ignoré. Si l’id de compte ne correspond pas à un compte configuré pour le canal résolu, la livraison est ignorée.
• prompt : remplace le corps du prompt par défaut (non fusionné).
• ackMaxChars : nombre maximal de caractères autorisés après HEARTBEAT_OK avant livraison.
• activeHours : limite les exécutions de heartbeat à une plage horaire. Objet avec start (HH:MM, inclusif), end (HH:MM exclusif ; 24:00 autorisé pour fin de journée), et timezone optionnel.
  • Omission ou "user" : utilise votre agents.defaults.userTimezone s’il est défini, sinon revient au fuseau horaire du système hôte.
  • "local" : utilise toujours le fuseau horaire du système hôte.
  • Tout identifiant IANA (p. ex. America/New_York) : utilisé directement ; s’il est invalide, revient au comportement "user" ci-dessus.
  • En dehors de la fenêtre active, les heartbeats sont ignorés jusqu’au prochain tick dans la fenêtre.

​

Comportement de livraison

• Les heartbeats s’exécutent par défaut dans la session principale de l’agent (agent:<id>:<mainKey>), ou global lorsque session.scope = "global". Définissez session pour remplacer par une session de canal spécifique (Discord/WhatsApp/etc.).
• session n’affecte que le contexte d’exécution ; la livraison est contrôlée par target et to.
• Pour livrer vers un canal/destinataire spécifique, définissez target + to. Avec target: "last", la livraison utilise le dernier canal externe pour cette session.
• Si la file principale est occupée, le heartbeat est ignoré et réessayé plus tard.
• Si target ne se résout vers aucune destination externe, l’exécution a quand même lieu mais aucun message sortant n’est envoyé.
• Les réponses uniquement heartbeat ne maintiennent pas la session active ; le dernier updatedAt est restauré afin que l’expiration d’inactivité se comporte normalement.

​

Contrôles de visibilité

channels:
  defaults:
    heartbeat:
      showOk: false # Hide HEARTBEAT_OK (default)
      showAlerts: true # Show alert messages (default)
      useIndicator: true # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true # Show OK acknowledgments on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alert delivery for this account

​

Que fait chaque drapeau

• showOk : envoie un accusé de réception HEARTBEAT_OK lorsque le modèle renvoie une réponse OK uniquement.
• showAlerts : envoie le contenu d’alerte lorsque le modèle renvoie une réponse non-OK.
• useIndicator : émet des événements indicateurs pour les surfaces d’état de l’UI.

​

Exemples par canal vs par compte

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

​

Modèles communs

​

HEARTBEAT.md (facultatif)

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

​

L’agent peut-il mettre à jour HEARTBEAT.md ?

• « Met à jour HEARTBEAT.md pour ajouter une vérification quotidienne du calendrier.
• « Réécris HEARTBEAT.md pour qu’il soit plus court et axé sur les suivis de la boîte de réception. »

​

Réveil manuel (à la demande)

openclaw system event --text "Check for urgent follow-ups" --mode now

​

Livraison du raisonnement (facultatif)

• agents.defaults.heartbeat.includeReasoning: true

​

Sensibilisation aux coûts