Qu'est-ce que la fonctionnalité heartbeat OpenClaw (Moltbot/Clawdbot) ?

OpenClaw (anciennement Moltbot/Clawdbot) est devenu rapidement populaire car il se concentre sur l'automatisation locale pratique : surveiller votre machine, détecter les dérives et agir avant que les problèmes ne s'accumulent. La fonction de battement de cœur est au centre de cette promesse.

Un battement de cœur est un signal périodique de santé et d'état. Dans OpenClaw, il fait plus que de simples pings de disponibilité. Il exécute un pipeline de décision en couches :

1. Vérifications déterministes économiques d'abord (processus, fichiers, profondeur de la file d'attente, statut de l'API)
2. Évaluation des règles par rapport aux seuils et aux politiques
3. Escalade de modèle optionnelle uniquement lorsque l'ambiguïté persiste

Ce modèle « vérifications économiques d'abord, modèles uniquement si nécessaire » est exactement ce que les développeurs ont demandé lors des récentes discussions communautaires : un meilleur contrôle des coûts, un comportement plus prévisible et moins d'appels LLM inutiles.

Si vous construisez une infrastructure d'agent, voici l'idée clé : les battements de cœur sont des primitives du plan de contrôle, pas seulement des événements de surveillance.

Architecture du battement de cœur OpenClaw en un coup d'œil

À l'exécution, les battements de cœur OpenClaw sont généralement implémentés comme une boucle en cinq étapes :

1. Le planificateur déclenche les impulsions du battement de cœur (par exemple toutes les 15s/30s/60s).
2. Le lanceur de sondes exécute des sondes déterministes.
3. Le moteur de politiques calcule les transitions d'état et la sévérité.
4. La porte d'escalade décide si un planificateur LLM/outil est nécessaire.
5. Le distributeur d'actions émet des alertes, des tâches de remédiation ou une opération nulle.

Une enveloppe d'événement pratique ressemble à ceci :

{
  "agent_id": "desktop-a17",
  "heartbeat_id": "hb_01JX...",
  "ts": "2026-02-11T10:18:05Z",
  "probes": {
    "cpu_load": 0.72,
    "disk_free_gb": 21.4,
    "mail_queue_depth": 0,
    "service_api": {
      "status": 200,
      "latency_ms": 83
    }
  },
  "policy": {
    "state": "degraded",
    "reasons": [
      "disk_free_below_warn"
    ]
  },
  "escalation": {
    "llm_required": false,
    "confidence": 0.93
  }
}

Le comportement clé du système :

• Les résultats des sondes déterministes sont la vérité primaire.
• Les sorties de la politique sont reproductibles et testables.
• L'utilisation du LLM est clairsemée, auditable et limitée par des portes strictes.

Ce que signifie « vérifications économiques d'abord » dans l'implémentation

Dans OpenClaw, les vérifications économiques devraient être :

• À faible latence (millisecondes à quelques centaines de ms)
• À faible coût (pas de dépense de jetons de modèle)
• Déterministes (même entrée => même sortie)
• Sans effets secondaires par défaut

Catégories de sondes typiques :

• Exécution locale : processus actif, pression mémoire, nombre de threads
• Santé I/O : espace disque libre, pression des inodes, modifications de permissions
• Santé de l'intégration : code de statut de l'API cible, délai d'attente, latence p95
• Santé des tâches : latence de la file d'attente, indicateurs de tempête de réessais
• Préconditions de politique : identifiants valides, fenêtres d'expiration des certificats

Contrat de sonde

Utilisez un schéma de sonde strict afin que la logique en aval soit stable :

yaml ProbeResult: name: string ok: boolean observed_at: datetime value: number|string|object|null severity_hint: info|warn|critical error: string|null ttl_ms: integer

Le ttl_ms est important. Si les données sont suffisamment récentes, ignorez les vérifications en double pendant les fenêtres de rafale.

Quand OpenClaw doit passer au raisonnement par modèle

L'escalade de modèle ne devrait se produire que lorsque la logique déterministe ne peut pas prendre de décision en toute sécurité.

Bons déclencheurs d'escalade :

• Signaux de sonde contradictoires (API 200 mais KPI métier en chute libre)
• Nouveaux clusters d'erreurs sans signature connue correspondante
• Planification de remédiation en plusieurs étapes sous contraintes
• Génération de résumés lisibles par l'homme pour les incidents

Mauvais déclencheurs d'escalade :

• Chaque événement d'avertissement
• Dépassements de seuils statiques avec des procédures connues
• Oscillation à haute fréquence où un débattement résoudrait le bruit

Conception de la machine à états : éviter le papillottement des alertes

La plupart des problèmes liés aux battements de cœur proviennent de transitions instables. Utilisez une machine à états avec hystérésis :

• sain
• dégradé
• critique
• en_récupération

Les règles de transition devraient inclure :

• Seuils d'entrée (par exemple, disque < 15% => dégradé)
• Seuils de sortie (par exemple, disque > 20% pendant 3 intervalles => sain)
• Fenêtres de débattement (N échantillons consécutifs)
• Refroidissement des actions (éviter la remédiation répétée)

Exemple :

yaml transitions: healthy->degraded: condition: disk_free_pct < 15 consecutive: 2 degraded->critical: condition: disk_free_pct < 8 consecutive: 1 degraded->healthy: condition: disk_free_pct > 20 consecutive: 3 critical->recovering: condition: remediation_applied == true recovering->healthy: condition: disk_free_pct > 20 consecutive: 2

Cela réduit drastiquement les oscillations bruyantes.

Conception d'API pour l'ingestion et le contrôle des battements de cœur

Si vous exposez des API de battement de cœur, gardez-les explicites et idempotentes lorsque cela est possible.

Points d'accès suggérés :

• POST /v1/heartbeats — ingérer l'événement de battement de cœur
• GET /v1/agents/{id}/status — dernier état calculé
• POST /v1/heartbeats/{id}/ack — accusé de réception de l'opérateur
• POST /v1/policies/simulate — simulation de politique avec un exemple de charge utile

Limites de sécurité pour les battements de cœur des agents

L'intérêt de la communauté pour le sandboxing et l'exécution sécurisée des agents croît pour de bonnes raisons. Les battements de cœur déclenchent souvent des actions, c'est pourquoi les limites de sécurité sont non négociables.

Contrôles minimums :

• Charges utiles de battement de cœur signées (HMAC ou identité mTLS)
• Jetons limités par agent (moindre privilège)
• Listes blanches de politiques/actions (pas d'invocation d'outil arbitraire)
• Exécution en sandbox pour les remédiations
• Piste d'audit pour chaque transition d'état et action

Si un modèle est impliqué :

• Traiter la sortie du LLM comme un texte de planification non fiable
• Valider les appels d'outils par rapport au schéma et à la politique
• Exiger des contrôles de garde déterministes avant l'exécution

En bref : la détection des battements de cœur peut être flexible ; les actions des battements de cœur doivent être contraintes.

Stratégie d'observabilité et de débogage

Pour déboguer les systèmes de battement de cœur, instrumentez d'abord ces métriques :

• taux d'ingestion des battements de cœur
• ratio de battements de cœur tardifs/manqués
• latence des sondes par type
• latence d'évaluation de la politique
• taux d'escalade (%)
• dépense de jetons de modèle par agent/jour
• étiquettes d'incidents faux positifs et faux négatifs

Tester les API de battement de cœur de style OpenClaw avec Apidog

Les systèmes de battement de cœur échouent aux limites : charges utiles malformées, événements rejoués et conditions de concurrence. Apidog vous aide à tester ces limites dans un seul espace de travail.

Un flux pratique :

1. Définir les points d'accès des battements de cœur en utilisant OpenAPI dans le concepteur visuel d'Apidog.
2. Construire des scénarios de test pour des événements de battement de cœur normaux, retardés, dupliqués et corrompus.
3. Ajouter des assertions visuelles sur les transitions d'état et les sorties d'action.
4. Simuler les canaux en aval (Slack/webhook/service de remédiation) avec des réponses dynamiques.
5. Exécuter les suites en CI/CD comme une porte de régression.

Exemples de cas de test

• ingest_valid_heartbeat_returns_200
• duplicate_idempotency_key_no_duplicate_action
• critical_state_triggers_single_alert_with_cooldown
• invalid_signature_returns_401
• novelty_trigger_causes_model_escalation_when_enabled

Parce qu'Apidog combine la conception, les tests, la simulation et la documentation, votre contrat d'API et son comportement restent alignés à mesure que la logique des battements de cœur évolue.

Si votre équipe répartit actuellement ces tâches entre plusieurs outils, la consolidation dans Apidog réduit la dérive et accélère le débogage.

Cas limites souvent manqués par les ingénieurs

• Décalage horaire
• Les horodatages des agents peuvent dériver.
• Accepter un décalage borné et stocker l'heure de réception du serveur séparément.

• Partitions réseau
• Les battements de cœur peuvent arriver par rafales après une reconnexion.
• Utilisez des numéros de séquence et des fenêtres de réordonnancement.

• Tempêtes de contre-pression
• Si le moteur de politiques ralentit, les files d'attente peuvent amplifier le décalage.
• Appliquez un contrôle d'admission et dégradez-vous gracieusement.

• Défaillance silencieuse de la sonde
• « Aucune donnée » ne signifie pas « sain ».
• Encodez explicitement l'état inconnu.

• Boucles de remédiation incontrôlées
• Une action déclenche une condition qui déclenche la même action à plusieurs reprises.
• Ajoutez un refroidissement par action et des budgets de réessai maximum.

• Dérive du modèle dans les résultats d'escalade
• Conservez les montages d'évaluation pour les décisions assistées par modèle.
• Re-valider lors des changements de modèle/version.

Note de migration : Moltbot/Clawdbot vers la dénomination OpenClaw

L'historique des renommages a causé de la confusion dans les noms de paquets, la documentation et les préfixes de points d'accès. Si vous maintenez des intégrations :

• Maintenez des alias rétrocompatibles pour une fenêtre de dépréciation.
• Versionnez explicitement les schémas d'événements (event_version).
• Publiez une carte de migration (anciens noms de sujets -> nouveaux noms de sujets).
• Ajoutez des tests de contrat pour les charges utiles héritées et actuelles.

Cela réduit la rupture de l'écosystème pendant que la communauté converge vers la dénomination OpenClaw.

Base de référence de production recommandée

Si vous souhaitez une valeur par défaut raisonnable pour le déploiement des battements de cœur :

• Intervalle : 30s
• Délai d'attente de la sonde : 500ms chacune, budget total de 2s
• Débattement : 2 échecs consécutifs pour un avertissement
• Refroidissement : 5 minutes par type d'action
• Plafond d'escalade : max 5% des battements de cœur invoquent le modèle
• Rétention : 30 jours à chaud, 180 jours à froid pour les audits

Ensuite, ajustez par charge de travail. Les agents de bureau des développeurs et les agents de serveur nécessitent généralement des politiques différentes.

Points clés à retenir

La fonction de battement de cœur d'OpenClaw est précieuse car elle traite la santé des agents comme une boucle de contrôle disciplinée, et non comme un flux de travail axé sur le chat. Le modèle gagnant est clair :

• sondes déterministes d'abord,
• machine à états de politique explicite ensuite,
• escalade de modèle uniquement pour l'incertitude.

Cette conception vous offre des coûts réduits, une prévisibilité accrue et une automatisation plus sûre.

Lorsque vous implémentez des API de battement de cœur, investissez massivement dans les contrats, l'idempotence, la simulation de politique et l'automatisation des tests. Apidog est parfaitement adapté ici car vous pouvez concevoir des spécifications OpenAPI, simuler des dépendances, exécuter des tests de régression et publier de la documentation en un seul endroit.

Si vous construisez ou intégrez des battements de cœur de style OpenClaw maintenant, commencez par des règles déterministes strictes et ajoutez l'intelligence du modèle progressivement. La fiabilité vient des contraintes d'abord, de l'intelligence ensuite.