Tool-Schleifenerkennung

OpenClaw verfügt über zwei zusammenwirkende Schutzmechanismen gegen sich wiederholende Tool-Aufrufmuster, die beide unter tools.loopDetection konfiguriert werden:

1. Schleifenerkennung (enabled) – standardmäßig deaktiviert. Überwacht den gleitenden Verlauf der Tool-Aufrufe auf wiederholte Muster und Wiederholungsversuche mit unbekannten Tools.
2. Schutz nach Compaction (postCompactionGuard) – aktiviert, solange enabled nicht ausdrücklich auf false gesetzt ist. Wird nach jedem Wiederholungsversuch infolge einer Compaction aktiviert und bricht den Lauf ab, wenn der Agent innerhalb des Fensters dasselbe Tripel (tool, args, result) wiederholt.

Setzen Sie tools.loopDetection.enabled: false, um beide Schutzmechanismen zu deaktivieren.

Zweck

• Sich wiederholende Sequenzen erkennen, die keinen Fortschritt erzielen.
• Hochfrequente Schleifen ohne Ergebnis erkennen (gleiches Tool, gleiche Eingaben, wiederholte Fehler).
• Bestimmte wiederholte Aufrufmuster bekannter Polling-Tools erkennen.
• Zyklen aus Kontextüberlauf -> Compaction -> gleicher Schleife unterbrechen, statt sie unbegrenzt weiterlaufen zu lassen.

Konfigurationsblock

Globale Standardwerte mit allen dokumentierten Feldern:

{  tools: {    loopDetection: {      enabled: false, // Hauptschalter für die Detektoren des gleitenden Verlaufs      historySize: 30,      warningThreshold: 10,      criticalThreshold: 20,      unknownToolThreshold: 10,      globalCircuitBreakerThreshold: 30,      detectors: {        genericRepeat: true,        knownPollNoProgress: true,        pingPong: true,      },      postCompactionGuard: {        windowSize: 3, // nach einem Compaction-Wiederholungsversuch aktiviert; läuft, sofern enabled nicht ausdrücklich false ist      },    },  },}

Optionale Überschreibung pro Agent unter agents.list[].tools.loopDetection:

{  agents: {    list: [      {        id: "safe-runner",        tools: {          loopDetection: {            enabled: true,            warningThreshold: 8,            criticalThreshold: 16,          },        },      },    ],  },}

Die Einstellungen pro Agent überlagern den globalen Block Feld für Feld (einschließlich der verschachtelten Felder detectors und postCompactionGuard), sodass ein Agent nur die Felder festlegen muss, die er ändern soll.

Verhalten der Felder

Bei exec vergleicht der Hash für fehlenden Fortschritt stabile Befehlsergebnisse (Status, Exit-Code, Zeitüberschreitungskennzeichen, Ausgabe) und ignoriert veränderliche Laufzeitmetadaten wie Dauer, PID, Sitzungs-ID und Arbeitsverzeichnis. Ergebnisse ausgehender Nachrichtenversendungen werden ohne veränderliche aufrufspezifische IDs (Nachrichten-ID, Datei-ID, Zeitstempel) gehasht, sodass ein Ergebnis „gesendet“ nicht mit einem anderen Ergebnis „gesendet“ identisch erscheint. Wenn eine Lauf-ID verfügbar ist, wird der Verlauf ausschließlich innerhalb dieses Laufs ausgewertet, sodass geplante Heartbeat-Zyklen und neue Läufe keine veralteten Schleifenzähler aus früheren Läufen übernehmen.

Empfohlene Einrichtung

• Setzen Sie bei kleineren Modellen enabled: true und belassen Sie die Schwellenwerte auf ihren Standardwerten. Führende Modelle benötigen die Erkennung anhand des gleitenden Verlaufs nur selten und können den Hauptschalter auf false belassen, während sie weiterhin vom Schutz nach Compaction profitieren.
• Halten Sie die Schwellenwerte in der Reihenfolge warningThreshold < criticalThreshold < globalCircuitBreakerThreshold; die Laufzeit erhöht criticalThreshold und globalCircuitBreakerThreshold, wenn Sie sie auf oder unter den jeweils zu überschreitenden Schwellenwert setzen.
• Wenn Fehlalarme auftreten:
  • Erhöhen Sie warningThreshold und/oder criticalThreshold.
  • Erhöhen Sie optional globalCircuitBreakerThreshold.
  • Deaktivieren Sie nur den jeweiligen Detektor, der Probleme verursacht (detectors.<name>: false).
  • Verringern Sie historySize, um ein kürzeres Verlaufsfenster zu verwenden.
• Um alles einschließlich des Schutzes nach Compaction zu deaktivieren, setzen Sie tools.loopDetection.enabled: false ausdrücklich.

Schutz nach Compaction

Nach einem Compaction-Wiederholungsversuch infolge eines Kontextüberlaufs aktiviert der Runner für die nächsten Tool-Aufrufe einen Schutz mit kurzem Fenster. Wenn der Agent dasselbe Tripel (toolName, argsHash, resultHash) innerhalb dieses Fensters postCompactionGuard.windowSize-mal ausgibt, folgert der Schutz, dass die Compaction die Schleife nicht unterbrochen hat, und bricht den Lauf mit einem Fehler vom Typ compaction_loop_persisted ab.

Der Schutz wird durch den Hauptschalter tools.loopDetection.enabled gesteuert, jedoch mit einer Besonderheit: Er bleibt aktiviert, wenn der Schalter nicht gesetzt oder auf true gesetzt ist, und wird nur deaktiviert, wenn der Schalter ausdrücklich auf false gesetzt wird. Dies ist beabsichtigt – der Schutz dient dazu, Compaction-Schleifen zu verlassen, die andernfalls unbegrenzt Tokens verbrauchen würden, sodass auch Benutzer ohne Konfiguration geschützt sind.

{  tools: {    loopDetection: {      // Hauptschalter; auf false setzen, um den Schutz zusammen mit den Detektoren des gleitenden Verlaufs zu deaktivieren      enabled: true,      postCompactionGuard: {        windowSize: 3, // Standardwert      },    },  },}

• Ein niedrigerer Wert für windowSize ist strenger (weniger Versuche vor dem Abbruch).
• Ein höherer Wert für windowSize gewährt dem Agent mehr Wiederherstellungsversuche.
• Der Schutz bricht niemals ab, solange sich die Ergebnisse ändern; nur byteidentische Ergebnisse im gesamten Fenster lösen ihn aus.
• Er wird nur unmittelbar nach einem Compaction-Wiederholungsversuch aktiviert, nicht an anderen Stellen eines Laufs.

Protokolle und erwartetes Verhalten

Wenn eine Schleife erkannt wird, protokolliert OpenClaw ein Schleifenereignis und warnt entweder oder blockiert abhängig vom Schweregrad den nächsten Tool-Zyklus. Dadurch werden unkontrollierter Token-Verbrauch und Blockierungen verhindert, während der normale Tool-Zugriff erhalten bleibt.

• Zuerst werden Warnungen ausgegeben.
• Die Blockierung erfolgt, sobald ein Muster über den Warnschwellenwert hinaus fortbesteht.
• Kritische Schwellenwerte blockieren den nächsten Tool-Zyklus und geben im Datensatz des Laufs einen eindeutigen Grund für die Schleifenerkennung an.
• Der Schutz nach Compaction gibt Fehler vom Typ compaction_loop_persisted aus, die das verursachende Tool und die Anzahl identischer Aufrufe nennen.

Verwandte Themen