Tool-loop detection

OpenClaw can keep agents from getting stuck in repeated tool-call patterns. The guard is disabled by default.

Enable it only where needed, because it can block legitimate repeated calls with strict settings.

Why this exists

• Detect repetitive sequences that do not make progress.
• Detect high-frequency no-result loops (same tool, same inputs, repeated errors).
• Detect specific repeated-call patterns for known polling tools.

Configuration block

Global defaults:

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

Per-agent override (optional):

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

Field behavior

• text

  Copy

  enabled
  : Master switch.
  text

  Copy

  false
  means no loop detection is performed.
• text

  Copy

  historySize
  : number of recent tool calls kept for analysis.
• text

  Copy

  warningThreshold
  : threshold before classifying a pattern as warning-only.
• text

  Copy

  criticalThreshold
  : threshold for blocking repetitive loop patterns.
• text

  Copy

  globalCircuitBreakerThreshold
  : global no-progress breaker threshold.
• text

  Copy

  detectors.genericRepeat
  : detects repeated same-tool + same-params patterns.
• text

  Copy

  detectors.knownPollNoProgress
  : detects known polling-like patterns with no state change.
• text

  Copy

  detectors.pingPong
  : detects alternating ping-pong patterns.

For

, no-progress checks compare stable command outcomes and ignore volatile runtime metadata such as duration, PID, session ID, and working directory. When a run id is available, recent tool-call history is evaluated only within that run so scheduled heartbeat cycles and fresh runs do not inherit stale loop counts from earlier runs.

Recommended setup

• Start with
  text

  Copy

  enabled: true
  , defaults unchanged.
• Keep thresholds ordered as
  text

  Copy

  warningThreshold < criticalThreshold < globalCircuitBreakerThreshold
  .
• If false positives occur:
  • raise
    text

    Copy

    warningThreshold
    and/or
    text

    Copy

    criticalThreshold
  • (optionally) raise
    text

    Copy

    globalCircuitBreakerThreshold
  • disable only the detector causing issues
  • reduce
    text

    Copy

    historySize
    for less strict historical context

Logs and expected behavior

When a loop is detected, OpenClaw reports a loop event and blocks or dampens the next tool-cycle depending on severity. This protects users from runaway token spend and lockups while preserving normal tool access.

• Prefer warning and temporary suppression first.
• Escalate only when repeated evidence accumulates.

Notes

• text

  Copy

  tools.loopDetection
  is merged with agent-level overrides.
• Per-agent config fully overrides or extends global values.
• If no config exists, guardrails stay off.

Related

• Exec approvals
• Thinking levels
• Sub-agents