Wykrywanie pętli narzędzi

OpenClaw ma dwa współpracujące mechanizmy zabezpieczające przed powtarzalnymi wzorcami wywołań narzędzi:

1. Wykrywanie pętli (tools.loopDetection.enabled) — domyślnie wyłączone. Obserwuje kroczącą historię wywołań narzędzi pod kątem powtarzających się wzorców i ponowień dla nieznanych narzędzi.
2. Strażnik po Compaction (tools.loopDetection.postCompactionGuard) — domyślnie włączony, chyba że tools.loopDetection.enabled jest jawnie ustawione na false. Uzbraja się po każdej próbie ponowienia po Compaction i przerywa uruchomienie, gdy agent wyemituje tę samą trójkę (tool, args, result) w ramach okna.

Oba są konfigurowane w tym samym bloku tools.loopDetection, ale strażnik po Compaction działa zawsze, gdy przełącznik główny nie jest jawnie wyłączony. Ustaw tools.loopDetection.enabled: false, aby wyciszyć oba mechanizmy.

Dlaczego to istnieje

• Wykrywanie powtarzalnych sekwencji, które nie robią postępu.
• Wykrywanie częstych pętli bez wyniku (to samo narzędzie, te same dane wejściowe, powtarzające się błędy).
• Wykrywanie konkretnych wzorców powtarzanych wywołań dla znanych narzędzi odpytujących.
• Zapobieganie cyklom przepełnienie kontekstu, następnie Compaction, następnie ta sama pętla, które działałyby bez końca.

Blok konfiguracji

Globalne wartości domyślne, z pokazanymi wszystkimi udokumentowanymi polami:

{  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      },    },  },}

Nadpisanie dla agenta (opcjonalne):

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

Zachowanie pól

Dla exec kontrole braku postępu porównują stabilne wyniki poleceń i ignorują zmienne metadane wykonania, takie jak czas trwania, PID, identyfikator sesji i katalog roboczy. Gdy dostępny jest identyfikator uruchomienia, historia ostatnich wywołań narzędzi jest oceniana tylko w ramach tego uruchomienia, więc zaplanowane cykle Heartbeat i świeże uruchomienia nie dziedziczą przestarzałych liczników pętli z wcześniejszych uruchomień.

Zalecana konfiguracja

• Dla mniejszych modeli ustaw enabled: true i pozostaw progi z wartościami domyślnymi. Modele flagowe rzadko potrzebują wykrywania na podstawie kroczącej historii i mogą pozostawić przełącznik główny na false, nadal korzystając ze strażnika po Compaction.
• Utrzymuj progi w kolejności warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
• Jeśli występują fałszywe alarmy:
  • Zwiększ warningThreshold i/lub criticalThreshold.
  • Opcjonalnie zwiększ globalCircuitBreakerThreshold.
  • Wyłącz tylko konkretny detektor powodujący problemy (detectors.<name>: false).
  • Zmniejsz historySize, aby kontekst historyczny był mniej rygorystyczny.
• Aby wyłączyć wszystko (w tym strażnika po Compaction), jawnie ustaw tools.loopDetection.enabled: false.

Strażnik po Compaction

Gdy runner zakończy próbę ponowienia po Compaction po przepełnieniu kontekstu, uzbraja strażnika z krótkim oknem, który obserwuje kilka kolejnych wywołań narzędzi. Jeśli agent wyemituje tę samą trójkę (toolName, argsHash, resultHash) wielokrotnie w ramach okna, strażnik uznaje, że Compaction nie przerwało pętli, i przerywa uruchomienie błędem compaction_loop_persisted.

Strażnik jest kontrolowany przez główną flagę tools.loopDetection.enabled z jednym szczegółem: pozostaje włączony, gdy flaga jest nieustawiona lub ma wartość true, i dezaktywuje się tylko wtedy, gdy flaga jest jawnie ustawiona na false. To zamierzone. Strażnik istnieje po to, aby wychodzić z pętli Compaction, które w przeciwnym razie zużywałyby nieograniczoną liczbę tokenów, więc użytkownik bez konfiguracji nadal otrzymuje ochronę.

{  tools: {    loopDetection: {      // master switch; set false to disable the guard along with the rolling detectors      enabled: true,      postCompactionGuard: {        windowSize: 3, // default      },    },  },}

• Niższe windowSize jest bardziej rygorystyczne (mniej prób przed przerwaniem).
• Wyższe windowSize daje agentowi więcej prób odzyskania działania.
• Strażnik nigdy nie przerywa, gdy wyniki się zmieniają, tylko gdy wyniki są bajtowo identyczne w całym oknie.
• Jest celowo wąski: uruchamia się tylko bezpośrednio po próbie ponowienia po Compaction.

Dzienniki i oczekiwane zachowanie

Gdy pętla zostanie wykryta, OpenClaw zgłasza zdarzenie pętli i albo tłumi, albo blokuje następny cykl narzędzi zależnie od wagi. Chroni to użytkowników przed niekontrolowanym zużyciem tokenów i blokadami, zachowując normalny dostęp do narzędzi.

• Ostrzeżenia pojawiają się najpierw.
• Tłumienie następuje, gdy wzorce utrzymują się po przekroczeniu progu ostrzeżeń.
• Progi krytyczne blokują następny cykl narzędzi i ujawniają jasny powód wykrycia pętli w rekordzie uruchomienia.
• Strażnik po Compaction emituje błędy compaction_loop_persisted z nazwą narzędzia powodującego problem i liczbą identycznych wywołań.

Powiązane