OpenClaw 툴 루프 탐지 설정: 무한 반복 방지 가이드

AI 에이전트를 운영하다 보면 가끔 에이전트가 무한 루프에 빠져 API 토큰을 순식간에 소모해버리는 당황스러운 상황을 겪게 됩니다. 도구가 예상치 못한 응답을 주거나 에러가 반복될 때 에이전트가 갈 길을 잃고 헤매는 것인데요.

OpenClaw는 에이전트가 이러한 반복적인 Tool-call 패턴에 갇히지 않도록 도와주는 기능을 제공해요. 이 안전장치는 **기본적으로 비활성화(disabled)**되어 있습니다. 설정이 너무 엄격하면 정상적인 반복 호출까지 차단할 수 있으니, 꼭 필요한 곳에만 활성화해서 사용하는 것이 좋아요.

Tool-loop 탐지

이 기능이 필요한 이유

• 진전이 없는 반복적인 시퀀스를 탐지해요.
• 결과가 없는 고빈도 루프(동일한 Tool, 동일한 입력, 반복되는 에러)를 탐지해요.
• 알려진 polling 도구들의 특정 반복 호출 패턴을 탐지해요.

설정 블록

글로벌 기본 설정:

{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 20,
      detectorCooldownMs: 12000,
      repeatThreshold: 3,
      criticalThreshold: 6,
      detectors: {
        repeatedFailure: true,
        knownPollLoop: true,
        repeatingNoProgress: true,
      },
    },
  },
}

에이전트별 개별 설정 (선택 사항):

{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            repeatThreshold: 2,
            criticalThreshold: 5,
          },
        },
      },
    ],
  },
}

필드 동작 방식

• enabled: 메인 스위치예요. false로 설정하면 루프 탐지를 수행하지 않아요.
• historySize: 분석을 위해 유지하는 최근 Tool 호출 횟수예요.
• detectorCooldownMs: no-progress 탐지기가 사용하는 시간 범위예요.
• repeatThreshold: 경고나 차단이 시작되기 전의 최소 반복 횟수예요.
• criticalThreshold: 더 엄격한 처리를 트리거할 수 있는 강한 임계값이에요.
• detectors.repeatedFailure: 동일한 호출 경로에서 반복된 실패 시도를 탐지해요.
• detectors.knownPollLoop: 알려진 polling 형태의 루프를 탐지해요.
• detectors.repeatingNoProgress: 상태 변화 없이 고빈도로 반복되는 호출을 탐지해요.

권장 설정

• 우선 enabled: true로 설정하고 기본값은 그대로 둔 채 시작해 보세요.
• 만약 오탐이 발생한다면 다음과 같이 조치할 수 있어요:
  • repeatThreshold 또는 criticalThreshold 값을 높이세요.
  • 문제를 일으키는 특정 탐지기만 비활성화하세요.
  • 과거 컨텍스트를 덜 엄격하게 반영하려면 historySize를 줄이세요.

로그 및 예상 동작

루프가 탐지되면 OpenClaw는 루프 이벤트를 보고하고, 심각도에 따라 다음 Tool 사이클을 차단하거나 억제해요. 이 기능은 일반적인 Tool 접근 권한은 유지하면서도, 사용자가 의도치 않은 토큰 비용을 지불하거나 시스템이 멈추는 현상을 방지해 줍니다.

• 처음에는 경고와 일시적인 억제를 우선적으로 적용해요.
• 반복적인 증거가 계속 쌓일 때만 대응 수위를 높여요.

참고 사항

• tools.loopDetection 설정은 에이전트 레벨의 설정과 병합되어 적용돼요.
• 에이전트별 설정은 글로벌 값을 완전히 덮어쓰거나 확장할 수 있어요.
• 별도의 설정을 하지 않으면 루프 탐지 안전장치는 꺼진 상태로 유지돼요.

AI Setup Assistant