OpenClaw Tool-Loop-Erkennung: Endlosschleifen stoppen

Kennst du das? Dein Agent verfängt sich in einer Endlosschleife, ruft immer wieder dieselbe API auf und verbrennt in Sekunden dein Token-Budget. Das ist frustrierend und blockiert deinen gesamten Workflow.

Tool-Loop-Erkennung

OpenClaw verhindert, dass Agenten in wiederholten Tool-Call-Mustern stecken bleiben. Dieser Schutz ist standardmäßig deaktiviert.

Aktiviere ihn nur dort, wo er wirklich gebraucht wird, da er bei zu strengen Einstellungen auch legitime wiederholte Aufrufe blockieren kann.

Warum das existiert

• Erkennt repetitive Sequenzen, die keinen Fortschritt machen.
• Erkennt hochfrequente Loops ohne Ergebnis (gleiches Tool, gleiche Inputs, wiederholte Fehler).
• Erkennt spezifische Muster für bekanntes Polling.
• Schützt vor unkontrollierten Kosten durch redundante Tool-Aufrufe.

Konfigurationsblock

Global defaults:

{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 20,
      detectorCooldownMs: 12000,
      repeatThreshold: 3,
      criticalThreshold: 6,
      detectors: {
        repeatedFailure: true,
        knownPollLoop: true,
        repeatingNoProgress: true,
      },
    },
  },
}

Per-agent override (optional):

{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            repeatThreshold: 2,
            criticalThreshold: 5,
          },
        },
      },
    ],
  },
}

Field behavior

• enabled: Master switch. false bedeutet, dass keine Loop-Erkennung durchgeführt wird.
• historySize: Anzahl der letzten Tool-Calls, die für die Analyse gespeichert werden.
• detectorCooldownMs: Zeitfenster, das vom No-Progress-Detector verwendet wird.
• repeatThreshold: Mindestanzahl an Wiederholungen, bevor Warnungen oder Blockaden starten.
• criticalThreshold: Strengerer Schwellenwert, der eine härtere Behandlung auslösen kann.
• detectors.repeatedFailure: Erkennt wiederholte fehlgeschlagene Versuche auf demselben Call-Pfad.
• detectors.knownPollLoop: Erkennt bekannte Polling-ähnliche Schleifen.
• detectors.repeatingNoProgress: Erkennt hochfrequente wiederholte Aufrufe ohne Statusänderung.

Empfohlenes Setup

• Starte mit enabled: true und lass die Standardwerte unverändert.
• Wenn False Positives auftreten:
  • Erhöhe repeatThreshold und/oder criticalThreshold.
  • Deaktiviere gezielt den Detector, der Probleme verursacht.
  • Verringere historySize für weniger historischen Kontext.
  • Justiere die detectorCooldownMs für dein spezifisches Szenario.

Logs und erwartetes Verhalten

Wenn ein Loop erkannt wird, meldet OpenClaw ein Loop-Event und blockiert oder dämpft den nächsten Tool-Zyklus je nach Schweregrad. Das schützt dich vor explodierenden Token-Kosten und Systemabstürzen, während der normale Zugriff auf Tools erhalten bleibt.

• Bevorzuge zuerst Warnungen und temporäre Unterdrückung.
• Eskaliere erst, wenn sich die Hinweise häufen.

Hinweise

• tools.loopDetection wird mit den Overrides auf Agent-Ebene zusammengeführt.
• Die Konfiguration pro Agent überschreibt oder erweitert die globalen Werte vollständig.
• Wenn keine Konfiguration existiert, bleiben die Guardrails deaktiviert.
• Die Einstellungen lassen sich granular für jeden Use-Case anpassen.

Nächste Schritte

• Agent-Konfiguration
• Tool-Management

AI Setup Assistant