Виявлення зациклення інструментів

OpenClaw має два взаємодійні запобіжники для повторюваних шаблонів викликів інструментів:

1. Виявлення циклів (tools.loopDetection.enabled) — вимкнено за замовчуванням. Стежить за рухомою історією викликів інструментів, шукаючи повторювані шаблони та повторні спроби для невідомих інструментів.
2. Запобіжник після Compaction (tools.loopDetection.postCompactionGuard) — увімкнено за замовчуванням, якщо tools.loopDetection.enabled не задано явно як false. Активується після кожної повторної спроби після Compaction і перериває виконання, коли агент видає той самий трійковий набір (tool, args, result) у межах вікна.

Обидва налаштовуються в одному блоці tools.loopDetection, але запобіжник після Compaction працює щоразу, коли головний перемикач не вимкнено явно. Установіть tools.loopDetection.enabled: false, щоб вимкнути обидві поверхні.

# Навіщо це потрібно

• Виявляти повторювані послідовності, які не дають прогресу.
• Виявляти високочастотні цикли без результату (той самий інструмент, ті самі вхідні дані, повторювані помилки).
• Виявляти конкретні шаблони повторних викликів для відомих інструментів опитування.
• Запобігати нескінченному виконанню циклів «переповнення контексту, потім Compaction, потім той самий цикл».

# Блок конфігурації

Глобальні типові значення, з усіма задокументованими полями:

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

Перевизначення для окремого агента (необов’язково):

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

# Поведінка полів

Поле	Типове значення	Ефект
enabled	false	Головний перемикач для детекторів рухомої історії. Установлення false також вимикає запобіжник після Compaction.
historySize	30	Кількість останніх викликів інструментів, що зберігаються для аналізу.
warningThreshold	10	Поріг, після якого шаблон класифікується лише як попередження.
criticalThreshold	20	Поріг для блокування повторюваних циклічних шаблонів.
unknownToolThreshold	10	Блокує повторні виклики того самого недоступного інструмента після такої кількості промахів.
globalCircuitBreakerThreshold	30	Глобальний поріг аварійного переривання відсутності прогресу для всіх детекторів.
detectors.genericRepeat	true	Виявляє повторювані шаблони «той самий інструмент + ті самі параметри».
detectors.knownPollNoProgress	true	Виявляє відомі шаблони, подібні до опитування, без зміни стану.
detectors.pingPong	true	Виявляє почергові шаблони ping-pong.
postCompactionGuard.windowSize	3	Кількість викликів інструментів після Compaction, протягом яких запобіжник лишається активним, і кількість однакових трійок, що перериває виконання.

Для exec перевірки відсутності прогресу порівнюють стабільні результати команд і ігнорують мінливі метадані виконання, як-от тривалість, PID, ID сесії та робочий каталог. Коли доступний ID виконання, історія останніх викликів інструментів оцінюється лише в межах цього виконання, щоб заплановані цикли Heartbeat і нові виконання не успадковували застарілі лічильники циклів із попередніх виконань.

# Рекомендоване налаштування

• Для менших моделей установіть enabled: true і залиште пороги типовими. Флагманські моделі рідко потребують виявлення за рухомою історією та можуть залишити головний перемикач у стані false, водночас отримуючи користь від запобіжника після Compaction.
• Тримайте пороги впорядкованими як warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
• Якщо виникають хибнопозитивні спрацьовування:
  • Підвищте warningThreshold та/або criticalThreshold.
  • За потреби підвищте globalCircuitBreakerThreshold.
  • Вимкніть лише конкретний детектор, що спричиняє проблеми (detectors.<name>: false).
  • Зменште historySize для менш суворого історичного контексту.
• Щоб вимкнути все (включно із запобіжником після Compaction), явно встановіть tools.loopDetection.enabled: false.

# Запобіжник після Compaction

Коли runner завершує повторну спробу після Compaction унаслідок переповнення контексту, він активує коротковіконний запобіжник, який стежить за кількома наступними викликами інструментів. Якщо агент кілька разів у межах вікна видає той самий трійковий набір (toolName, argsHash, resultHash), запобіжник робить висновок, що Compaction не розірвало цикл, і перериває виконання з помилкою compaction_loop_persisted.

Запобіжник контролюється головним прапорцем tools.loopDetection.enabled з одним нюансом: він лишається увімкненим, коли прапорець не задано або встановлено в true, і деактивується лише тоді, коли прапорець явно дорівнює false. Це навмисно. Запобіжник існує, щоб виходити з циклів Compaction, які інакше спалювали б необмежену кількість токенів, тож користувач без конфігурації все одно отримує захист.

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

• Нижче windowSize є суворішим (менше спроб до переривання).
• Вище windowSize дає агенту більше спроб відновлення.
• Запобіжник ніколи не перериває виконання, коли результати змінюються, а лише коли результати побайтово ідентичні в межах вікна.
• Він навмисно вузький: спрацьовує лише безпосередньо після повторної спроби після Compaction.

# Журнали й очікувана поведінка

Коли виявлено цикл, OpenClaw повідомляє про подію циклу та або приглушує, або блокує наступний цикл інструментів залежно від серйозності. Це захищає користувачів від неконтрольованих витрат токенів і зависань, зберігаючи нормальний доступ до інструментів.

• Спочатку з’являються попередження.
• Якщо шаблони зберігаються після порога попередження, застосовується приглушення.
• Критичні пороги блокують наступний цикл інструментів і показують чітку причину виявлення циклу в записі виконання.
• Запобіжник після Compaction видає помилки compaction_loop_persisted з назвою проблемного інструмента та кількістю однакових викликів.

# Пов’язане