도구 루프 감지

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.

1. 루프 감지(tools.loopDetection.enabled) — 기본적으로 비활성화되어 있습니다. 반복 패턴과 알 수 없는 도구 재시도를 감지하기 위해 이동 도구 호출 기록을 감시합니다.
2. 사후 Compaction 가드(tools.loopDetection.postCompactionGuard) — tools.loopDetection.enabled가 명시적으로 false가 아닌 한 기본적으로 활성화됩니다. 모든 Compaction 재시도 후 작동 준비 상태가 되며, 에이전트가 창 내에서 동일한 (tool, args, result) 트리플을 내보내면 실행을 중단합니다.

​

존재 이유

• 진행되지 않는 반복 시퀀스를 감지합니다.
• 고빈도 무결과 루프를 감지합니다(동일한 도구, 동일한 입력, 반복되는 오류).
• 알려진 폴링 도구의 특정 반복 호출 패턴을 감지합니다.
• 컨텍스트 오버플로 후 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: true를 설정하고 임계값은 기본값으로 두세요. 플래그십 모델은 이동 기록 감지가 거의 필요하지 않으며, 사후 Compaction 가드의 이점을 계속 얻으면서도 마스터 스위치를 false로 둘 수 있습니다.
• 임계값 순서를 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold로 유지하세요.
• 거짓 양성이 발생하면:
  • warningThreshold 및/또는 criticalThreshold를 높입니다.
  • 선택적으로 globalCircuitBreakerThreshold를 높입니다.
  • 문제를 일으키는 특정 감지기만 비활성화합니다(detectors.<name>: false).
  • 덜 엄격한 기록 컨텍스트를 위해 historySize를 줄입니다.
• 사후 Compaction 가드를 포함해 모든 것을 비활성화하려면 tools.loopDetection.enabled: 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 가드는 문제가 되는 도구 이름과 동일 호출 횟수와 함께 compaction_loop_persisted 오류를 내보냅니다.

​

관련 항목