---
read_when:
    - Користувач повідомляє, що агенти застрягають, повторюючи виклики tools
    - Вам потрібно налаштувати захист від повторюваних викликів
    - Ви редагуєте політики tools/runtime агента
summary: Як увімкнути та налаштувати guardrails, які виявляють повторювані цикли викликів tools
title: Виявлення циклів tools
x-i18n:
    generated_at: "2026-04-27T12:55:35Z"
    model: gpt-5.4
    provider: openai
    source_hash: ba601384e7d23ddfd316f9e5eef92b3daa4618d2287228a516c76fe141700a28
    source_path: tools/loop-detection.md
    workflow: 15
---

OpenClaw може не давати агентам застрягати в повторюваних шаблонах викликів tools.
Цей guard **за замовчуванням вимкнений**.

Увімкніть його лише там, де це потрібно, оскільки за суворих налаштувань він може блокувати легітимні повторні виклики.

## Навіщо це існує

- Виявляти повторювані послідовності, які не дають поступу.
- Виявляти високочастотні цикли без результату (той самий tool, ті самі вхідні дані, повторювані помилки).
- Виявляти конкретні шаблони повторних викликів для відомих polling tools.

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

Глобальні значення за замовчуванням:

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

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

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

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

- `enabled`: Головний перемикач. `false` означає, що виявлення циклів не виконується.
- `historySize`: кількість нещодавніх викликів tools, що зберігаються для аналізу.
- `warningThreshold`: поріг перед класифікацією шаблону лише як попередження.
- `criticalThreshold`: поріг для блокування повторюваних шаблонів циклів.
- `globalCircuitBreakerThreshold`: глобальний поріг аварійного вимикача для циклів без поступу.
- `detectors.genericRepeat`: виявляє повторювані шаблони той самий tool + ті самі params.
- `detectors.knownPollNoProgress`: виявляє відомі шаблони, схожі на polling, без зміни стану.
- `detectors.pingPong`: виявляє чергувальні шаблони ping-pong.

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

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

- Починайте з `enabled: true`, не змінюючи значення за замовчуванням.
- Зберігайте порядок порогів як `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Якщо виникають хибні спрацьовування:
  - підвищте `warningThreshold` і/або `criticalThreshold`
  - (необов’язково) підвищте `globalCircuitBreakerThreshold`
  - вимкніть лише той detector, який спричиняє проблеми
  - зменште `historySize`, щоб зробити історичний контекст менш суворим

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

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

- Надавайте перевагу попередженню та тимчасовому приглушенню.
- Підвищуйте рівень лише тоді, коли накопичуються повторні докази.

## Примітки

- `tools.loopDetection` об’єднується з перевизначеннями на рівні агента.
- Конфігурація для окремого агента повністю перевизначає або розширює глобальні значення.
- Якщо конфігурація відсутня, guardrails залишаються вимкненими.

## Пов’язані теми

- [Exec approvals](/uk/tools/exec-approvals)
- [Рівні thinking](/uk/tools/thinking)
- [Субагенти](/uk/tools/subagents)
