Wykrywanie pętli narzędziowej

OpenClaw ma dwa współpracujące zabezpieczenia dla powtarzalnych wzorców wywołań narzędzi:

1. Wykrywanie pętli (tools.loopDetection.enabled) — domyślnie wyłączone. Obserwuje przesuwaną historię wywołań narzędzi pod kątem powtarzających się wzorców i ponownych prób użycia nieznanych narzędzi.
2. Zabezpieczenie po Compaction (tools.loopDetection.postCompactionGuard) — domyślnie włączone, chyba że tools.loopDetection.enabled ma jawnie wartość false. Uzbraja się po każdej ponownej próbie po Compaction i przerywa przebieg, gdy agent wyemituje tę samą trójkę (tool, args, result) w oknie.

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

# Dlaczego to istnieje

• Wykrywa powtarzalne sekwencje, które nie robią postępu.
• Wykrywa pętle o wysokiej częstotliwości bez wyników (to samo narzędzie, te same dane wejściowe, powtarzające się błędy).
• Wykrywa konkretne wzorce powtarzanych wywołań dla znanych narzędzi odpytujących.
• Zapobiega nieograniczonemu działaniu cykli: przepełnienie kontekstu, potem Compaction, potem ta sama pętla.

# 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 pojedynczego agenta (opcjonalne):

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

# Zachowanie pól

Pole	Domyślnie	Efekt
enabled	false	Przełącznik główny dla detektorów przesuwanej historii. Ustawienie false wyłącza również zabezpieczenie po Compaction.
historySize	30	Liczba ostatnich wywołań narzędzi przechowywanych do analizy.
warningThreshold	10	Próg, po którym wzorzec jest klasyfikowany wyłącznie jako ostrzeżenie.
criticalThreshold	20	Próg blokowania powtarzalnych wzorców pętli.
unknownToolThreshold	10	Blokuje powtarzane wywołania tego samego niedostępnego narzędzia po tylu niepowodzeniach.
globalCircuitBreakerThreshold	30	Globalny próg wyłącznika dla braku postępu we wszystkich detektorach.
detectors.genericRepeat	true	Wykrywa powtarzające się wzorce: to samo narzędzie + te same parametry.
detectors.knownPollNoProgress	true	Wykrywa znane wzorce podobne do odpytywania bez zmiany stanu.
detectors.pingPong	true	Wykrywa naprzemienne wzorce ping-pong.
postCompactionGuard.windowSize	3	Liczba wywołań narzędzi po Compaction, podczas których zabezpieczenie pozostaje uzbrojone, oraz liczba identycznych trójek przerywająca przebieg.

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 przebiegu, ostatnia historia wywołań narzędzi jest oceniana tylko w obrębie tego przebiegu, więc zaplanowane cykle Heartbeat i świeże przebiegi nie dziedziczą nieaktualnych liczników pętli z wcześniejszych przebiegów.

# Zalecana konfiguracja

• Dla mniejszych modeli ustaw enabled: true i pozostaw progi z wartościami domyślnymi. Modele flagowe rzadko potrzebują wykrywania przesuwanej historii i mogą pozostawić przełącznik główny jako false, nadal korzystając z zabezpieczenia po Compaction.
• Zachowaj kolejność progów jako warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
• Jeśli pojawią się wyniki fałszywie dodatnie:
  • 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 zabezpieczenie po Compaction), ustaw jawnie tools.loopDetection.enabled: false.

# Zabezpieczenie po Compaction

Gdy runner ukończy ponowną próbę po Compaction po przepełnieniu kontekstu, uzbraja krótkookienne zabezpieczenie, które obserwuje kilka następnych wywołań narzędzi. Jeśli agent wyemituje tę samą trójkę (toolName, argsHash, resultHash) wielokrotnie w oknie, zabezpieczenie uznaje, że Compaction nie przerwało pętli, i przerywa przebieg z błędem compaction_loop_persisted.

Zabezpieczenie jest bramkowane przez główną flagę tools.loopDetection.enabled, z jednym niuansem: pozostaje włączone, gdy flaga nie jest ustawiona albo ma wartość true, i dezaktywuje się tylko wtedy, gdy flaga ma jawnie wartość false. To celowe. Zabezpieczenie istnieje po to, aby wydostać się 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.
• Zabezpieczenie nigdy nie przerywa, gdy wyniki się zmieniają; robi to tylko wtedy, gdy wyniki są identyczne bajt po bajcie w całym oknie.
• Jest celowo wąskie: uruchamia się tylko bezpośrednio po ponownej próbie po Compaction.

# Dzienniki i oczekiwane zachowanie

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

• Najpierw pojawiają się ostrzeżenia.
• Gdy wzorce utrzymują się po przekroczeniu progu ostrzeżenia, następuje tłumienie.
• Progi krytyczne blokują następny cykl narzędzia i pokazują jasną przyczynę wykrycia pętli w rekordzie przebiegu.
• Zabezpieczenie po Compaction emituje błędy compaction_loop_persisted z nazwą narzędzia powodującego problem i liczbą identycznych wywołań.

# Powiązane