도구 루프 감지

OpenClaw는 에이전트가 반복적인 도구 호출 패턴에 빠지는 것을 방지할 수 있습니다. 이 가드레일은 기본적으로 비활성화되어 있습니다.

엄격한 설정에서는 정당한 반복 호출도 차단할 수 있으므로, 필요한 경우에만 활성화하세요.

존재 이유

진행 없이 반복되는 시퀀스를 감지합니다.
동일한 도구, 동일한 입력, 반복 오류가 있는 고빈도 무결과 루프를 감지합니다.
알려진 폴링 도구의 특정 반복 호출 패턴을 감지합니다.

설정 블록

전역 기본값:

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

에이전트별 재정의 (선택 사항):

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

필드 동작

enabled: 마스터 스위치. false이면 루프 감지가 수행되지 않습니다.
historySize: 분석을 위해 보관할 최근 도구 호출 수.
warningThreshold: 패턴을 경고 수준으로 분류하기 전 임계값.
criticalThreshold: 반복 루프 패턴을 차단하는 임계값.
globalCircuitBreakerThreshold: 전역 무진행 회로 차단기 임계값.
detectors.genericRepeat: 동일한 도구 + 동일한 매개변수의 반복 패턴을 감지합니다.
detectors.knownPollNoProgress: 상태 변화 없이 반복되는 폴링 패턴을 감지합니다.
detectors.pingPong: 교대 반복되는 핑퐁 패턴을 감지합니다.

권장 설정

enabled: true로 시작하고 기본값을 유지하세요.
임계값을 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold 순서로 유지하세요.
오탐이 발생하면:
- warningThreshold 및/또는 criticalThreshold를 높이세요
- (선택적으로) globalCircuitBreakerThreshold를 높이세요
- 문제를 일으키는 감지기만 비활성화하세요
- 이력 컨텍스트를 줄이려면 historySize를 줄이세요

로그 및 예상 동작

루프가 감지되면 OpenClaw는 루프 이벤트를 보고하고 심각도에 따라 다음 도구 사이클을 차단하거나 약화시킵니다. 이를 통해 정상적인 도구 접근을 유지하면서 과도한 토큰 소비와 잠금을 방지합니다.

경고와 일시적 억제를 먼저 적용합니다.
반복적인 증거가 누적될 때만 에스컬레이션합니다.

참고

tools.loopDetection은 에이전트 수준 재정의와 병합됩니다.
에이전트별 설정이 전역 값을 완전히 재정의하거나 확장합니다.
설정이 없으면 가드레일은 비활성 상태로 유지됩니다.