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

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

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

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

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

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

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

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

```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`: кількість останніх викликів інструментів, що зберігаються для аналізу.
- `warningThreshold`: поріг, після якого шаблон класифікується лише як попередження.
- `criticalThreshold`: поріг для блокування повторюваних циклічних шаблонів.
- `globalCircuitBreakerThreshold`: глобальний поріг запобіжника для відсутності прогресу.
- `detectors.genericRepeat`: виявляє повторювані шаблони з тим самим інструментом + тими самими параметрами.
- `detectors.knownPollNoProgress`: виявляє відомі шаблони, схожі на polling, без зміни стану.
- `detectors.pingPong`: виявляє чергування за шаблоном ping-pong.

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

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

## Логи й очікувана поведінка

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

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

## Примітки

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