Detección de bucles en herramientas

OpenClaw puede evitar que los agentes queden atrapados en patrones repetitivos de llamadas a herramientas. La protección está desactivada por defecto.

Actívala solo donde sea necesario, ya que con configuraciones estrictas puede bloquear llamadas repetidas legítimas.

Por qué existe

• Detectar secuencias repetitivas que no avanzan.
• Detectar bucles de alta frecuencia sin resultados (misma herramienta, mismas entradas, errores repetidos).
• Detectar patrones específicos de llamadas repetidas para herramientas de polling conocidas.

Bloque de configuración

Valores globales por defecto:

{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

Sobreescritura por agente (opcional):

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

Comportamiento de los campos

• enabled: Interruptor principal. false significa que no se realiza detección de bucles.
• historySize: número de llamadas a herramientas recientes que se conservan para el análisis.
• warningThreshold: umbral antes de clasificar un patrón como solo advertencia.
• criticalThreshold: umbral para bloquear patrones de bucles repetitivos.
• globalCircuitBreakerThreshold: umbral del interruptor global de falta de progreso.
• detectors.genericRepeat: detecta patrones repetidos de la misma herramienta + mismos parámetros.
• detectors.knownPollNoProgress: detecta patrones tipo polling conocidos sin cambio de estado.
• detectors.pingPong: detecta patrones alternantes de ping-pong.

Configuración recomendada

• Comienza con enabled: true y los valores por defecto sin cambios.
• Mantén los umbrales ordenados como warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
• Si ocurren falsos positivos:
  • sube warningThreshold y/o criticalThreshold
  • (opcionalmente) sube globalCircuitBreakerThreshold
  • desactiva solo el detector que causa problemas
  • reduce historySize para un contexto histórico menos estricto

Logs y comportamiento esperado

Cuando se detecta un bucle, OpenClaw reporta un evento de bucle y bloquea o amortigua el siguiente ciclo de herramientas según la gravedad. Esto protege a los usuarios del gasto descontrolado de tokens y bloqueos mientras preserva el acceso normal a herramientas.

• Prefiere advertencia y supresión temporal primero.
• Escala solo cuando la evidencia repetida se acumula.

Notas

• tools.loopDetection se fusiona con las sobreescrituras a nivel de agente.
• La configuración por agente sobreescribe o extiende completamente los valores globales.
• Si no existe configuración, las protecciones permanecen desactivadas.