Heartbeat

Heartbeat exécute des tours d’agent périodiques dans la session principale afin que le modèle puisse signaler ce qui nécessite votre attention sans vous spammer.

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âche sont destinés au travail détaché (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 (ou 1h lorsque l’authentification OAuth/jeton Anthropic est le mode d’authentification détecté, y compris la réutilisation de Claude CLI). Définissez agents.defaults.heartbeat.every ou agents.list[].heartbeat.every par agent ; 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.
• Délai d’expiration : les tours heartbeat non définis utilisent agents.defaults.timeoutSeconds lorsque cette valeur est définie. Sinon, ils utilisent la cadence heartbeat plafonnée à 600 secondes. Définissez agents.defaults.heartbeat.timeoutSeconds ou agents.list[].heartbeat.timeoutSeconds par agent pour un travail heartbeat plus long.
• Le prompt heartbeat est envoyé tel quel comme message utilisateur. Le prompt système inclut une section « Heartbeat » uniquement lorsque les heartbeats sont activés pour l’agent par défaut, et l’exécution est marquée en interne.
• Lorsque les heartbeats sont désactivés avec 0m, les exécutions normales omettent aussi HEARTBEAT.md du contexte d’amorçage afin que le modèle ne voie pas les instructions réservées aux heartbeats.
• Les heures actives (heartbeat.activeHours) sont vérifiées dans le fuseau horaire configuré. En dehors de la fenêtre, les heartbeats sont ignorés jusqu’au prochain tick à l’intérieur de la fenêtre.
• Les heartbeats sont automatiquement différés lorsque du travail cron est actif ou en file d’attente. Définissez heartbeat.skipWhenBusy: true pour différer aussi un agent sur son propre sous-agent indexé par clé de session ou ses voies de commande imbriquées ; les agents frères ne sont plus mis en pause simplement parce qu’un autre agent a du travail de sous-agent en cours.

À quoi sert le prompt heartbeat

Le prompt par défaut est volontairement large :

• Tâches en arrière-plan : « Consider outstanding tasks » incite l’agent à examiner les suivis (boîte de réception, calendrier, rappels, travail en file d’attente) et à signaler tout élément urgent.
• Point de contact humain : « Checkup sometimes on your human during day time » incite à envoyer occasionnellement un message léger du type « besoin de quelque chose ? », tout en évitant le spam nocturne grâce à votre 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 voulez qu’un heartbeat fasse quelque chose de très précis (par exemple « check Gmail PubSub stats » ou « verify gateway health »), 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 votre attention, répondez avec HEARTBEAT_OK.
• Les exécutions heartbeat capables d’utiliser des outils peuvent plutôt appeler heartbeat_respond avec notify: false pour aucune mise à jour visible, ou notify: true plus notificationText pour 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 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 abandonnée si le contenu restant est ≤ ackMaxChars (valeur par défaut : 300).
• Si HEARTBEAT_OK apparaît au milieu d’une réponse, il n’est pas traité de façon particulière.
• Pour les alertes, n’incluez pas HEARTBEAT_OK ; renvoyez uniquement le texte de l’alerte.

En dehors des heartbeats, un HEARTBEAT_OK parasite 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.",        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

Portée et priorité

• agents.defaults.heartbeat définit le comportement heartbeat global.
• 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 du canal.
• channels.<channel>.accounts.<id>.heartbeat (canaux multi-comptes) remplace les paramètres par canal.

Heartbeats par agent

Si une entrée agents.list[] inclut un bloc heartbeat, seuls ces agents exécutent des heartbeats. Le bloc par agent fusionne par-dessus agents.defaults.heartbeat (vous pouvez donc définir une fois les valeurs par défaut partagées et les remplacer par agent).

Exemple : deux agents, seul le second agent 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 actives

Limitez les heartbeats aux heures ouvrables dans un fuseau horaire spécifique :

{  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 fenêtre (avant 9 h ou après 22 h, heure de l’Est), les heartbeats sont ignorés. Le prochain tick planifié à l’intérieur de la fenêtre s’exécutera normalement.

Configuration 24 h/24, 7 j/7

Si vous voulez que les heartbeats s’exécutent toute la journée, utilisez l’un de ces modèles :

• Omettez entièrement activeHours (aucune restriction de fenêtre horaire ; c’est le comportement par défaut).
• Définissez une fenêtre d’une journée complète : activeHours: { start: "00:00", end: "24:00" }.

Exemple multi-comptes

Utilisez accountId pour cibler un compte spécifique sur des canaux multi-comptes comme 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" },      },    },  },}

Notes sur les champs

Comportement de livraison

Contrôles de visibilité

Par défaut, les accusés HEARTBEAT_OK sont supprimés tandis que le contenu d’alerte est livré. Vous pouvez ajuster cela par canal ou par compte :

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

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

Ce que fait chaque indicateur

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

Si les trois sont faux, OpenClaw ignore entièrement l’exécution 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 # all Slack accounts    accounts:      ops:        heartbeat:          showAlerts: false # suppress alerts for the ops account only  telegram:    heartbeat:      showOk: true

Modèles courants

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. Pensez-y comme à votre « liste de vérification Heartbeat » : petite, stable et sûre à prendre en compte toutes les 30 minutes.

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

Sur le harnais Codex natif, le contenu de HEARTBEAT.md n’est pas injecté dans le tour. Si le fichier existe et contient du contenu autre que des espaces, les instructions de mode collaboration Heartbeat indiquent le fichier à Codex et lui disent de le lire avant de poursuivre.

Si HEARTBEAT.md existe mais est effectivement vide (seulement des lignes vides, des commentaires Markdown/HTML, des titres Markdown comme # Heading, des marqueurs de clôture ou des ébauches de listes de vérification vides), OpenClaw ignore l’exécution Heartbeat pour économiser des appels API. Cette omission est signalée comme reason=empty-heartbeat-file. Si le fichier est absent, le Heartbeat s’exécute quand même et le modèle décide quoi faire.

Gardez-le minuscule (courte liste de vérification ou rappels) pour éviter de gonfler l’invite.

Exemple HEARTBEAT.md :

# 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.

Blocs tasks:

HEARTBEAT.md prend aussi en charge un petit bloc structuré tasks: pour des vérifications basées sur des intervalles dans Heartbeat lui-même.

Exemple :

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

Le mode tâche est utile lorsque vous voulez qu’un seul fichier Heartbeat contienne plusieurs vérifications périodiques sans payer pour chacune d’elles à chaque tick.

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

Oui — si vous le lui demandez.

HEARTBEAT.md est simplement un fichier normal dans l’espace de travail de l’agent, vous pouvez donc dire à l’agent (dans une discussion normale) quelque chose comme :

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

Si vous voulez que cela se produise de façon proactive, vous pouvez aussi inclure une ligne explicite dans votre invite Heartbeat, comme : « Si la liste de vérification devient obsolète, mettez à jour HEARTBEAT.md avec une meilleure version. »

Réveil manuel (à la demande)

Vous pouvez mettre en file d’attente un événement système et déclencher un Heartbeat immédiat avec :

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

Si plusieurs agents ont heartbeat configuré, un réveil manuel exécute immédiatement chacun de ces Heartbeat d’agent.

Utilisez --mode next-heartbeat pour attendre le prochain tick planifié.

Livraison du raisonnement (facultatif)

Par défaut, les Heartbeat ne livrent que la charge utile finale de « réponse ».

Si vous voulez de la transparence, activez :

• agents.defaults.heartbeat.includeReasoning: true

Lorsque c’est activé, les Heartbeat livrent aussi un message distinct préfixé Thinking (même forme que /reasoning on). Cela peut être utile lorsque l’agent gère plusieurs sessions/codex et que vous voulez voir pourquoi il a décidé de vous envoyer un ping — mais cela peut aussi révéler plus de détails internes que vous ne le souhaitez. Préférez le laisser désactivé dans les discussions de groupe.

Sensibilisation aux coûts

Les Heartbeat exécutent des tours d’agent complets. Des intervalles plus courts consomment davantage de jetons. Pour réduire le coût :

• Utilisez isolatedSession: true pour éviter d’envoyer tout l’historique de conversation (environ 100 000 jetons réduits à environ 2 à 5 000 par exécution).
• Utilisez lightContext: true pour limiter les fichiers d’amorçage au seul HEARTBEAT.md.
• Définissez un model moins coûteux (par exemple ollama/llama3.2:1b).
• Gardez HEARTBEAT.md petit.
• Utilisez target: "none" si vous voulez uniquement des mises à jour d’état internes.

Débordement de contexte après Heartbeat

Si un Heartbeat a précédemment laissé une session existante sur un modèle local plus petit, par exemple un modèle Ollama avec une fenêtre de 32k, et que le prochain tour de session principale signale un débordement de contexte, réinitialisez le modèle d’exécution de la session vers le modèle principal configuré. Le message de réinitialisation d’OpenClaw le signale lorsque le dernier modèle d’exécution correspond à heartbeat.model configuré.

Les Heartbeat actuels conservent le modèle d’exécution existant de la session partagée après la fin de l’exécution. Vous pouvez toujours utiliser isolatedSession: true pour exécuter les Heartbeat dans une session fraîche, le combiner avec lightContext: true pour l’invite la plus petite, ou choisir un modèle Heartbeat avec une fenêtre de contexte assez grande pour la session partagée.

Connexe

• Automatisation — aperçu de tous les mécanismes d’automatisation
• Tâches en arrière-plan — comment le travail détaché est suivi
• Fuseau horaire — comment le fuseau horaire affecte la planification des heartbeats
• Dépannage — débogage des problèmes d’automatisation