Heartbeat

Heartbeat exécute des tours d’agent périodiques dans la session principale afin que le modèle puisse signaler tout ce qui nécessite une attention particulière sans vous inonder de messages.

Heartbeat est un tour planifié de la session principale : il ne crée pas d’enregistrements de tâche en arrière-plan. Les enregistrements de tâches servent aux travaux détachés (exécutions ACP, sous-agents, tâches Cron isolées).

Dépannage : Tâches planifiées

Démarrage rapide (débutant)

Exemple de configuration :

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files        isolatedSession: true, // optional: fresh session each run (no conversation history)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` message too      },    },  },}

Valeurs par défaut

• Intervalle : 30m. L’application des valeurs par défaut du fournisseur Anthropic le porte à 1h lorsque le mode d’authentification résolu est OAuth/jeton (y compris la réutilisation de la CLI Claude), mais uniquement tant que heartbeat.every n’est pas défini. Définissez agents.defaults.heartbeat.every ou agents.list[].heartbeat.every pour chaque agent ; utilisez 0m pour le 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.
• Délai d’expiration : les tours Heartbeat sans valeur définie utilisent agents.defaults.timeoutSeconds lorsque celui-ci est défini. Sinon, ils utilisent la fréquence de Heartbeat, plafonnée à 600 secondes. Définissez agents.defaults.heartbeat.timeoutSeconds ou agents.list[].heartbeat.timeoutSeconds pour chaque agent afin d’autoriser des travaux Heartbeat plus longs.
• Le prompt Heartbeat est envoyé tel quel comme message utilisateur. Le prompt système comprend une section « Heartbeats » uniquement lorsque les Heartbeats sont activés pour l’agent par défaut (et que includeSystemPromptSection n’est pas défini sur false), et l’exécution est marquée en interne.
• Lorsque les Heartbeats sont désactivés avec 0m, les exécutions normales omettent également HEARTBEAT.md du contexte d’amorçage afin que le modèle ne voie pas les instructions réservées à Heartbeat.
• Les heures d’activité (heartbeat.activeHours) sont vérifiées dans le fuseau horaire configuré. En dehors de cette plage, les Heartbeats sont ignorés jusqu’au prochain déclenchement situé dans la plage.
• Les Heartbeats sont automatiquement différés lorsqu’un travail Cron est actif ou en attente. Définissez heartbeat.skipWhenBusy: true pour également différer un agent lorsque son propre sous-agent associé à une clé de session ou ses files de commandes imbriquées sont occupés ; les agents frères ne sont plus suspendus simplement parce qu’un autre agent exécute un travail de sous-agent.

Rôle du prompt Heartbeat

Le prompt par défaut est volontairement général :

• Tâches en arrière-plan : « Prendre en compte les tâches en attente » incite l’agent à examiner les suivis (boîte de réception, calendrier, rappels, travaux en attente) et à signaler tout élément urgent.
• Prise de nouvelles de l’utilisateur : « Prendre parfois des nouvelles de votre utilisateur pendant la journée » incite à envoyer occasionnellement un bref message du type « avez-vous besoin de quelque chose ? », tout en évitant les messages nocturnes grâce au fuseau horaire local configuré (voir Fuseau horaire).

Heartbeat peut réagir aux tâches en arrière-plan terminées, mais une exécution Heartbeat ne crée pas elle-même d’enregistrement de tâche.

Si vous souhaitez qu’un Heartbeat effectue une action très précise (par exemple « vérifier les statistiques Gmail PubSub » ou « vérifier l’état du Gateway »), définissez agents.defaults.heartbeat.prompt (ou agents.list[].heartbeat.prompt) avec un corps personnalisé (envoyé tel quel).

Contrat de réponse

• Si rien ne nécessite d’attention, répondez avec HEARTBEAT_OK.
• Les exécutions Heartbeat peuvent à la place appeler heartbeat_respond avec notify: false pour ne produire aucune mise à jour visible, ou avec notify: true et notificationText pour générer une alerte. Lorsqu’elle est présente, la réponse structurée de l’outil prévaut sur le texte de repli.
• Pendant les exécutions Heartbeat, OpenClaw considère 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 abandonnée si le contenu restant comporte ≤ ackMaxChars caractères (valeur par défaut : 300).
• Si HEARTBEAT_OK apparaît au milieu d’une réponse, il ne fait l’objet d’aucun traitement particulier.
• Pour les alertes, n’incluez pas HEARTBEAT_OK ; renvoyez uniquement le texte de l’alerte.

En dehors des Heartbeats, tout HEARTBEAT_OK isolé au début ou à la fin d’un message est supprimé et journalisé ; un message contenant uniquement HEARTBEAT_OK est abandonné.

Configuration

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Thinking message when available)        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        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.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

Portée et priorité

• agents.defaults.heartbeat définit le comportement global de Heartbeat.
• agents.list[].heartbeat est fusionné 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 du canal.
• channels.<channel>.accounts.<id>.heartbeat (canaux multicomptes) remplace les paramètres propres au canal.

Heartbeats par agent

Si une entrée agents.list[] contient un bloc heartbeat, seuls ces agents exécutent des Heartbeats. Le bloc propre à l’agent est fusionné par-dessus agents.defaults.heartbeat (vous pouvez ainsi définir une seule fois les valeurs par défaut communes et les remplacer pour chaque agent).

Exemple : deux agents, seul le second exécute des Heartbeats.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          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 d’activité

Limitez les Heartbeats aux heures de bureau dans un fuseau horaire précis :

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

En dehors de cette plage (avant 9 h ou après 22 h, heure de l’Est), les Heartbeats sont ignorés. Le prochain déclenchement planifié dans la plage s’exécutera normalement.

Configuration 24 h/24 et 7 j/7

Si vous souhaitez exécuter les Heartbeats toute la journée, utilisez l’un des modèles suivants :

• Omettez entièrement activeHours (aucune restriction de plage horaire ; il s’agit du comportement par défaut).
• Définissez une plage couvrant toute la journée : activeHours: { start: "00:00", end: "24:00" }.

Exemple multicomptes

Utilisez accountId pour cibler un compte précis sur les canaux multicomptes tels que Telegram :

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

Remarques sur les champs

Comportement de livraison

Contrôles de visibilité

Par défaut, les accusés de réception HEARTBEAT_OK sont supprimés tandis que le contenu des alertes est livré. Vous pouvez ajuster ce comportement par canal ou par compte :

channels:  defaults:    heartbeat:      showOk: false # Masquer HEARTBEAT_OK (par défaut)      showAlerts: true # Afficher les messages d'alerte (par défaut)      useIndicator: true # Émettre les événements d'indicateur (par défaut)  telegram:    heartbeat:      showOk: true # Afficher les accusés de réception OK sur Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Supprimer la livraison des alertes pour ce compte

Priorité : par compte → par canal → valeurs par défaut du canal → valeurs par défaut intégrées.

Rôle de chaque option

• showOk : envoie un accusé de réception HEARTBEAT_OK lorsque le modèle renvoie une réponse contenant uniquement OK.
• showAlerts : envoie le contenu de l'alerte lorsque le modèle renvoie une réponse autre que OK.
• useIndicator : émet des événements d'indicateur pour les surfaces d'état de l'interface utilisateur.

Si les trois valeurs sont fausses, OpenClaw ignore entièrement l'exécution du Heartbeat (aucun appel au modèle).

Exemples par canal et par compte

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # tous les comptes Slack    accounts:      ops:        heartbeat:          showAlerts: false # supprimer les alertes uniquement pour le compte ops  telegram:    heartbeat:      showOk: true

Configurations courantes

HEARTBEAT.md (facultatif)

Si un fichier HEARTBEAT.md existe dans l'espace de travail, l'invite par défaut demande à l'agent de le lire. Considérez-le comme votre « liste de contrôle du Heartbeat » : concise, stable et sûre à consulter toutes les 30 minutes.

Lors des exécutions normales, HEARTBEAT.md n'est injecté que lorsque les instructions de Heartbeat sont activées pour l'agent par défaut. Désactiver la cadence du Heartbeat avec 0m ou définir includeSystemPromptSection: false l'omet du contexte d'amorçage normal.

Dans le moteur Codex natif, le contenu de HEARTBEAT.md n'est pas injecté dans le tour comme les autres fichiers d'amorçage. Si le fichier existe et contient autre chose que des espaces, une note relative au mode de collaboration du Heartbeat indique le fichier à Codex et lui demande de le lire avant de continuer.

Si HEARTBEAT.md existe, mais est en pratique vide (uniquement des lignes vides, des commentaires Markdown/HTML, des titres Markdown comme # Heading, des délimiteurs de blocs ou des ébauches de listes de contrôle vides), OpenClaw ignore l'exécution du Heartbeat afin d'économiser des appels d'API. Cette omission est signalée par reason=empty-heartbeat-file. Si le fichier est absent, le Heartbeat s'exécute tout de même et le modèle décide de l'action à entreprendre.

Gardez-le très concis (courte liste de contrôle ou rappels) pour éviter de gonfler l'invite.

Exemple de HEARTBEAT.md :

# Liste de contrôle du Heartbeat - Vérification rapide : y a-t-il quelque chose d'urgent dans les boîtes de réception ?- S'il fait jour, effectuer une brève prise de contact si rien d'autre n'est en attente.- Si une tâche est bloquée, noter _ce qui manque_ et interroger Peter la prochaine fois.

Blocs tasks:

HEARTBEAT.md prend également en charge un petit bloc structuré tasks: pour les vérifications par intervalle au sein du Heartbeat lui-même.

Exemple :

tasks: - name: inbox-triage  interval: 30m  prompt: "Vérifier les e-mails urgents non lus et signaler tout élément sensible au temps."- name: calendar-scan  interval: 2h  prompt: "Vérifier les réunions à venir qui nécessitent une préparation ou un suivi." # Instructions supplémentaires - Garder les alertes concises.- Si rien ne nécessite d'attention après toutes les tâches arrivées à échéance, répondre HEARTBEAT_OK.

Le mode tâche est utile lorsque vous souhaitez qu'un seul fichier de Heartbeat contienne plusieurs vérifications périodiques sans payer pour toutes à chaque déclenchement.

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

Oui, si vous le lui demandez.

HEARTBEAT.md est simplement un fichier normal de l'espace de travail de l'agent. Vous pouvez donc dire à l'agent (dans une discussion normale), par exemple :

• « Mettre à jour HEARTBEAT.md pour ajouter une vérification quotidienne du calendrier. »
• « Réécrire HEARTBEAT.md pour le rendre plus concis et axé sur les suivis de la boîte de réception. »

Si vous souhaitez que cela se produise de manière proactive, vous pouvez également inclure une ligne explicite dans votre invite de Heartbeat, par exemple : « Si la liste de contrôle devient obsolète, mettre à jour HEARTBEAT.md avec une meilleure version. »

Réveil manuel (à la demande)

Utilisez openclaw system event pour mettre un événement système en file d'attente et, éventuellement, déclencher immédiatement un Heartbeat :

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

Si aucune valeur --session-key n'est fournie et que plusieurs agents ont configuré heartbeat, --mode now exécute immédiatement le Heartbeat de chacun de ces agents.

Commandes de Heartbeat associées dans le même groupe CLI :

openclaw system heartbeat last     # afficher le dernier événement de Heartbeatopenclaw system heartbeat enable   # activer les Heartbeatsopenclaw system heartbeat disable  # désactiver les Heartbeats

Livraison du raisonnement (facultatif)

Par défaut, les Heartbeats transmettent uniquement la charge utile finale « answer ».

Pour plus de transparence, activez :

• agents.defaults.heartbeat.includeReasoning: true

Lorsque cette option est activée, les Heartbeats transmettent également un message distinct préfixé par Thinking (au même format que /reasoning on). Cela peut être utile lorsque l’agent gère plusieurs sessions/codex et que vous souhaitez comprendre pourquoi il a décidé de vous solliciter, mais cela peut aussi révéler davantage de détails internes que vous ne le souhaitez. Il est préférable de laisser cette option désactivée dans les discussions de groupe.

Maîtrise des coûts

Les Heartbeats exécutent des tours complets de l’agent. Des intervalles plus courts consomment davantage de jetons. Pour réduire les coûts :

• Utilisez isolatedSession: true pour éviter d’envoyer l’historique complet de la conversation (d’environ 100 000 jetons à environ 2 000–5 000 par exécution).
• Utilisez lightContext: true pour limiter les fichiers d’amorçage au seul fichier HEARTBEAT.md.
• Définissez un model moins coûteux (par exemple ollama/llama3.2:1b).
• Veillez à ce que HEARTBEAT.md reste concis.
• Utilisez target: "none" si vous souhaitez uniquement des mises à jour de l’état interne.

Dépassement de la fenêtre de contexte après un Heartbeat

Une fois leur exécution terminée, les Heartbeats conservent le modèle d’exécution existant de la session partagée. Ainsi, un Heartbeat qui a fait passer une session à un modèle local plus petit (par exemple, un modèle Ollama doté d’une fenêtre de 32 000 jetons) peut laisser ce modèle actif pour le tour suivant de la session principale. Si ce tour signale ensuite un dépassement de la fenêtre de contexte et que le dernier modèle d’exécution de la session correspond au heartbeat.model configuré, le message de récupération d’OpenClaw indique qu’une persistance du modèle du Heartbeat est probablement à l’origine du problème et suggère une solution.

Pour éviter cela : utilisez isolatedSession: true afin d’exécuter les Heartbeats dans une nouvelle session (éventuellement avec lightContext: true pour réduire l’invite au minimum), ou choisissez un modèle de Heartbeat doté d’une fenêtre de contexte suffisamment grande pour la session partagée.

Voir aussi

• Automatisation - vue d’ensemble de tous les mécanismes d’automatisation
• Tâches en arrière-plan - fonctionnement du suivi des travaux détachés
• Fuseau horaire - influence du fuseau horaire sur la planification des Heartbeats
• Dépannage - diagnostic des problèmes d’automatisation