Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw dispose de deux garde-fous coopérants pour les motifs répétitifs d’appels d’outils :
  1. Détection de boucle (tools.loopDetection.enabled) — désactivée par défaut. Surveille l’historique glissant des appels d’outils pour repérer les motifs répétés et les nouvelles tentatives avec des outils inconnus.
  2. Garde post-Compaction (tools.loopDetection.postCompactionGuard) — activée par défaut sauf si tools.loopDetection.enabled vaut explicitement false. Elle s’arme après chaque nouvelle tentative de Compaction et abandonne l’exécution lorsque l’agent émet le même triplet (tool, args, result) dans la fenêtre.
Les deux sont configurés dans le même bloc tools.loopDetection, mais la garde post-Compaction s’exécute chaque fois que l’interrupteur principal n’est pas explicitement désactivé. Définissez tools.loopDetection.enabled: false pour désactiver les deux surfaces.

​
Pourquoi cela existe

  • Détecter les séquences répétitives qui ne progressent pas.
  • Détecter les boucles à haute fréquence sans résultat (même outil, mêmes entrées, erreurs répétées).
  • Détecter des motifs spécifiques d’appels répétés pour les outils d’interrogation connus.
  • Empêcher les cycles dépassement de contexte puis Compaction puis même boucle de s’exécuter indéfiniment.

​
Bloc de configuration

Valeurs globales par défaut, avec tous les champs documentés affichés : 
{
  tools: {
    loopDetection: {
      enabled: false, // master switch for the rolling-history detectors
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
      },
    },
  },
}
Remplacement par agent (facultatif) : 
{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            warningThreshold: 8,
            criticalThreshold: 16,
          },
        },
      },
    ],
  },
}

​
Comportement des champs

ChampPar défautEffet
enabledfalseInterrupteur principal des détecteurs d’historique glissant. Définir false désactive également la garde post-Compaction.
historySize30Nombre d’appels d’outils récents conservés pour l’analyse.
warningThreshold10Seuil avant qu’un motif soit classé comme avertissement uniquement.
criticalThreshold20Seuil de blocage des motifs de boucle répétitifs sans progression.
unknownToolThreshold10Bloque les appels répétés au même outil indisponible après ce nombre d’échecs.
globalCircuitBreakerThreshold30Seuil du disjoncteur global sans progression pour tous les détecteurs.
detectors.genericRepeattrueAvertit en cas de motifs répétés même outil + mêmes paramètres et bloque lorsque ces mêmes appels renvoient aussi des résultats identiques.
detectors.knownPollNoProgresstrueDétecte les motifs connus de type interrogation sans changement d’état.
detectors.pingPongtrueDétecte les motifs alternés de ping-pong.
postCompactionGuard.windowSize3Nombre d’appels d’outils post-Compaction pendant lesquels la garde reste armée et nombre de triplets identiques qui abandonne l’exécution.
Pour exec, les contrôles d’absence de progression comparent les résultats stables des commandes et ignorent les métadonnées d’exécution volatiles comme la durée, le PID, l’ID de session et le répertoire de travail. Lorsqu’un ID d’exécution est disponible, l’historique récent des appels d’outils est évalué uniquement dans cette exécution afin que les cycles Heartbeat planifiés et les nouvelles exécutions n’héritent pas de compteurs de boucle obsolètes provenant d’exécutions antérieures.

​
Configuration recommandée

  • Pour les modèles plus petits, définissez enabled: true et laissez les seuils à leurs valeurs par défaut. Les modèles phares ont rarement besoin de la détection par historique glissant et peuvent laisser l’interrupteur principal à false tout en bénéficiant de la garde post-Compaction.
  • Conservez les seuils dans l’ordre warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
  • Si des faux positifs se produisent :
    • Augmentez warningThreshold et/ou criticalThreshold.
    • Augmentez éventuellement globalCircuitBreakerThreshold.
    • Désactivez uniquement le détecteur spécifique qui pose problème (detectors.<name>: false).
    • Réduisez historySize pour un contexte historique moins strict.
  • Pour tout désactiver (y compris la garde post-Compaction), définissez explicitement tools.loopDetection.enabled: false.

​
Garde post-Compaction

Lorsque le moteur d’exécution termine une nouvelle tentative de Compaction après un dépassement de contexte, il arme une garde à fenêtre courte qui surveille les quelques appels d’outils suivants. Si l’agent émet plusieurs fois le même triplet (toolName, argsHash, resultHash) dans la fenêtre, la garde conclut que la Compaction n’a pas rompu la boucle et abandonne l’exécution avec une erreur compaction_loop_persisted. La garde est contrôlée par l’indicateur principal tools.loopDetection.enabled avec une nuance : elle reste activée lorsque l’indicateur n’est pas défini ou vaut true et se désactive uniquement lorsque l’indicateur vaut explicitement false. C’est intentionnel. La garde sert à sortir des boucles de Compaction qui consommeraient autrement des jetons sans limite ; un utilisateur sans configuration bénéficie donc quand même de la protection. 
{
  tools: {
    loopDetection: {
      // master switch; set false to disable the guard along with the rolling detectors
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // default
      },
    },
  },
}
  • Un windowSize plus bas est plus strict (moins de tentatives avant l’abandon).
  • Un windowSize plus élevé donne à l’agent davantage de tentatives de récupération.
  • La garde n’abandonne jamais lorsque les résultats changent, seulement lorsque les résultats sont identiques octet pour octet dans la fenêtre.
  • Elle est volontairement étroite : elle ne se déclenche que juste après une nouvelle tentative de Compaction.
La garde post-Compaction s’exécute chaque fois que l’indicateur principal n’est pas explicitement false, même si vous n’avez jamais écrit de bloc tools.loopDetection. Pour vérifier, recherchez post-compaction guard armed for N attempts dans le journal du Gateway immédiatement après un événement de Compaction.

​
Journaux et comportement attendu

Lorsqu’une boucle est détectée, OpenClaw signale un événement de boucle et atténue ou bloque le prochain cycle d’outil selon la gravité. Cela protège les utilisateurs contre une dépense excessive de jetons et les blocages tout en préservant l’accès normal aux outils.
  • Les avertissements apparaissent en premier.
  • La suppression suit lorsque les motifs persistent au-delà du seuil d’avertissement.
  • Les seuils critiques bloquent le prochain cycle d’outil et exposent une raison claire de détection de boucle dans l’enregistrement d’exécution.
  • La garde post-Compaction émet des erreurs compaction_loop_persisted avec le nom de l’outil incriminé et le nombre d’appels identiques.

​
Connexe

Approbations Exec

Politique d’autorisation/refus pour l’exécution shell.

Niveaux de réflexion

Niveaux d’effort de raisonnement et interaction avec la politique du fournisseur.

Sous-agents

Génération d’agents isolés pour borner les comportements incontrôlés.

Référence de configuration

Schéma complet de tools.loopDetection et sémantique de fusion.