Detectie van tool-lussen

OpenClaw heeft twee samenwerkende beveiligingen tegen herhalende patronen van toolaanroepen, beide geconfigureerd onder tools.loopDetection:

1. Lusdetectie (enabled) - standaard uitgeschakeld. Bewaakt de voortschrijdende geschiedenis van toolaanroepen op herhalende patronen en nieuwe pogingen met onbekende tools.
2. Beveiliging na Compaction (postCompactionGuard) - ingeschakeld zolang enabled niet expliciet false is. Wordt na elke nieuwe poging na Compaction geactiveerd en breekt de uitvoering af als de agent binnen het venster hetzelfde drietal (tool, args, result) herhaalt.

Stel tools.loopDetection.enabled: false in om beide beveiligingen uit te schakelen.

Waarom dit bestaat

• Herhalende reeksen detecteren die geen voortgang boeken.
• Hoogfrequente lussen zonder resultaat detecteren (dezelfde tool, dezelfde invoer, herhaalde fouten).
• Specifieke patronen van herhaalde aanroepen voor bekende pollingtools detecteren.
• Cycli van contextoverschrijding -> Compaction -> dezelfde lus doorbreken in plaats van ze onbeperkt te laten doorgaan.

Configuratieblok

Globale standaardwaarden, met elk gedocumenteerd veld weergegeven:

{  tools: {    loopDetection: {      enabled: false, // hoofdschakelaar voor de detectoren met voortschrijdende geschiedenis      historySize: 30,      warningThreshold: 10,      criticalThreshold: 20,      unknownToolThreshold: 10,      globalCircuitBreakerThreshold: 30,      detectors: {        genericRepeat: true,        knownPollNoProgress: true,        pingPong: true,      },      postCompactionGuard: {        windowSize: 3, // geactiveerd na een nieuwe poging na Compaction; actief tenzij enabled expliciet false is      },    },  },}

Overschrijving per agent (optioneel, bij agents.list[].tools.loopDetection):

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

Instellingen per agent worden veld voor veld over het globale blok heen gelegd (inclusief geneste detectors en postCompactionGuard), zodat een agent alleen de velden hoeft in te stellen die moeten worden gewijzigd.

Gedrag van velden

Voor exec vergelijkt de hashing voor ontbrekende voortgang stabiele opdrachtresultaten (status, afsluitcode, time-outvlag, uitvoer) en negeert deze vluchtige runtimemetadata zoals duur, PID, sessie-id en werkmap. Resultaten van uitgaande berichtverzendingen worden gehasht zonder vluchtige id's per aanroep (bericht-id, bestands-id, tijdstempel), zodat een resultaat "verzonden" niet identiek lijkt aan een ander resultaat "verzonden". Wanneer een uitvoerings-id beschikbaar is, wordt de geschiedenis alleen binnen die uitvoering geëvalueerd, zodat geplande Heartbeat-cycli en nieuwe uitvoeringen geen verouderde lustellingen van eerdere uitvoeringen overnemen.

Aanbevolen configuratie

• Stel voor kleinere modellen enabled: true in en laat de drempelwaarden op hun standaardwaarden staan. Toonaangevende modellen hebben detectie via voortschrijdende geschiedenis zelden nodig en kunnen de hoofdschakelaar op false laten staan, terwijl ze nog steeds profiteren van de beveiliging na Compaction.
• Houd de drempelwaarden in de volgorde warningThreshold < criticalThreshold < globalCircuitBreakerThreshold; de runtime verhoogt criticalThreshold en globalCircuitBreakerThreshold als u ze instelt op of onder de drempelwaarde die ze moeten overschrijden.
• Als er fout-positieven optreden:
  • Verhoog warningThreshold en/of criticalThreshold.
  • Verhoog eventueel globalCircuitBreakerThreshold.
  • Schakel alleen de specifieke detector uit die problemen veroorzaakt (detectors.<name>: false).
  • Verlaag historySize voor een korter historisch venster.
• Stel expliciet tools.loopDetection.enabled: false in om alles uit te schakelen, inclusief de beveiliging na Compaction.

Beveiliging na Compaction

Na een nieuwe poging met Compaction na een contextoverschrijding activeert de uitvoerder een beveiliging met een kort venster voor de eerstvolgende toolaanroepen. Als de agent hetzelfde drietal (toolName, argsHash, resultHash) binnen dat venster postCompactionGuard.windowSize keer uitvoert, concludeert de beveiliging dat Compaction de lus niet heeft doorbroken en breekt deze de uitvoering af met een fout compaction_loop_persisted.

De beveiliging wordt aangestuurd door de hoofdvlag tools.loopDetection.enabled, met één bijzonderheid: deze blijft ingeschakeld wanneer de vlag niet is ingesteld of true is, en wordt alleen uitgeschakeld wanneer de vlag expliciet false is. Dit is opzettelijk: de beveiliging bestaat om aan Compaction-lussen te ontsnappen die anders onbeperkt tokens zouden verbruiken, zodat een gebruiker zonder configuratie toch wordt beschermd.

{  tools: {    loopDetection: {      // hoofdschakelaar; stel in op false om de beveiliging samen met de voortschrijdende detectoren uit te schakelen      enabled: true,      postCompactionGuard: {        windowSize: 3, // standaard      },    },  },}

• Een lagere windowSize is strenger (minder pogingen vóór afbreken).
• Een hogere windowSize geeft de agent meer herstelpogingen.
• De beveiliging breekt nooit af zolang resultaten veranderen; alleen byte-identieke resultaten binnen het venster activeren deze.
• De beveiliging wordt alleen direct na een nieuwe poging met Compaction geactiveerd, niet op andere momenten tijdens een uitvoering.

Logboeken en verwacht gedrag

Wanneer een lus wordt gedetecteerd, registreert OpenClaw een lusgebeurtenis en waarschuwt of blokkeert het de volgende toolcyclus, afhankelijk van de ernst. Dit beschermt tegen ongecontroleerd tokenverbruik en vastlopers, terwijl normale toegang tot tools behouden blijft.

• Waarschuwingen komen eerst.
• Er wordt geblokkeerd zodra een patroon na de waarschuwingsdrempel blijft voortduren.
• Kritieke drempelwaarden blokkeren de volgende toolcyclus en tonen een duidelijke reden voor de lusdetectie in het uitvoeringsrecord.
• De beveiliging na Compaction genereert fouten compaction_loop_persisted die de betreffende tool en het aantal identieke aanroepen vermelden.

Gerelateerd