Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

ПолеТиповоЕфект
enabledfalseГоловний перемикач для детекторів ковзної історії. Установлення false також вимикає захист після Compaction.
historySize30Кількість останніх викликів інструментів, що зберігаються для аналізу.
warningThreshold10Поріг, після якого шаблон класифікується лише як попередження.
criticalThreshold20Поріг для блокування повторюваних шаблонів циклів без прогресу.
unknownToolThreshold10Блокує повторні виклики того самого недоступного інструмента після такої кількості промахів.
globalCircuitBreakerThreshold30Глобальний поріг переривача без прогресу для всіх детекторів.
detectors.genericRepeattrueПопереджає про повторювані шаблони «той самий інструмент + ті самі параметри» і блокує, коли ті самі виклики також повертають ідентичні результати.
detectors.knownPollNoProgresstrueВиявляє відомі шаблони, схожі на опитування, без зміни стану.
detectors.pingPongtrueВиявляє черговані шаблони ping-pong.
postCompactionGuard.windowSize3Кількість викликів інструментів після Compaction, протягом яких захист лишається активним, а також кількість ідентичних трійок, що перериває виконання.
Для exec перевірки відсутності прогресу порівнюють стабільні результати команд і ігнорують мінливі метадані виконання, як-от тривалість, PID, ідентифікатор сесії та робочий каталог. Коли доступний ідентифікатор виконання, остання історія викликів інструментів оцінюється лише в межах цього виконання, тож заплановані цикли 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.
Захист після Compaction працює щоразу, коли головний прапорець явно не дорівнює false, навіть якщо ви ніколи не створювали блок tools.loopDetection. Щоб перевірити, шукайте post-compaction guard armed for N attempts у журналі Gateway відразу після події Compaction.

​
Журнали та очікувана поведінка

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

​
Пов’язане

Схвалення exec

Політика дозволу/заборони для виконання shell.

Рівні мислення

Рівні зусилля міркування та взаємодія з політикою провайдера.

Субагенти

Запуск ізольованих агентів для обмеження неконтрольованої поведінки.

Довідник конфігурації

Повна схема tools.loopDetection і семантика злиття.