메인 콘텐츠로 건너뛰기

​
Tool-loop detection

OpenClaw는 agents가 반복적인 tool-call patterns에 갇히는 것을 막을 수 있습니다. 이 guard는 기본적으로 비활성화되어 있습니다. 엄격한 설정에서는 정당한 반복 호출도 막을 수 있으므로, 필요한 경우에만 활성화하세요.

​
왜 필요한가

  • 진전이 없는 반복 sequence 감지
  • 높은 빈도의 no-result loops (같은 tool, 같은 inputs, 반복 errors) 감지
  • 알려진 polling tools에 대한 특정 repeated-call patterns 감지

​
Configuration block

전역 기본값: 
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
per-agent override (선택 사항): 
{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            warningThreshold: 8,
            criticalThreshold: 16,
          },
        },
      },
    ],
  },
}

​
Field behavior

  • enabled: master switch. false이면 loop detection을 수행하지 않음
  • historySize: 분석을 위해 유지하는 최근 tool calls 수
  • warningThreshold: pattern을 warning-only로 분류하기 전 threshold
  • criticalThreshold: 반복 loop patterns를 차단하는 threshold
  • globalCircuitBreakerThreshold: 전역 no-progress breaker threshold
  • detectors.genericRepeat: 같은 tool + 같은 params 반복 패턴 감지
  • detectors.knownPollNoProgress: 상태 변화가 없는 known polling-like patterns 감지
  • detectors.pingPong: 번갈아 오가는 ping-pong patterns 감지

​
권장 설정

  • enabled: true로 시작하고 기본값은 그대로 두세요.
  • 임계치는 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold 순서를 유지하세요.
  • false positives가 발생하면:
    • warningThreshold와/또는 criticalThreshold를 높이세요
    • (선택적으로) globalCircuitBreakerThreshold도 높이세요
    • 문제를 일으키는 detector만 비활성화하세요
    • 더 느슨한 historical context를 위해 historySize를 줄이세요

​
로그와 예상 동작

loop가 감지되면, OpenClaw는 loop event를 보고하고 심각도에 따라 다음 tool-cycle을 차단하거나 완화합니다. 이렇게 하면 runaway token spend와 lockups로부터 사용자를 보호하면서 정상 tool access는 유지합니다.
  • 먼저 warnings와 temporary suppression을 우선하세요.
  • 반복된 evidence가 쌓일 때만 상위 단계로 escalate하세요.

​
메모

  • tools.loopDetection은 agent-level overrides와 병합됩니다.
  • per-agent config는 전역 값을 완전히 override하거나 확장할 수 있습니다.
  • 아무 config가 없으면 guardrails는 꺼진 상태로 유지됩니다.