Configure OpenClaw Tool-Loop Detection to Prevent Hangs

Ever had that sinking feeling when you check your logs and see an agent stuck in an infinite loop? It is a classic developer headache: a tool fails, the agent tries again with the exact same parameters, and your token usage spikes while nothing actually happens.

OpenClaw can keep agents from getting stuck in repeated tool-call patterns. The guard is disabled by default. You should enable it only where needed, because it can block legitimate repeated calls if your settings are too strict.

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:

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

Per-agent override (optional):

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

Field behavior

• enabled: Master switch. false means no loop detection is performed.
• historySize: number of recent tool calls kept for analysis.
• detectorCooldownMs: time window used by the no-progress detector.
• repeatThreshold: minimum repeats before warning/blocking starts.
• criticalThreshold: stronger threshold that can trigger stricter handling.
• detectors.repeatedFailure: detects repeated failed attempts on the same call path.
• detectors.knownPollLoop: detects known polling-like loops.
• detectors.repeatingNoProgress: detects high-frequency repeated calls without state change.

Recommended setup

• Start with enabled: true, defaults unchanged.
• If false positives occur:
  • raise repeatThreshold and/or criticalThreshold
  • disable only the detector causing issues
  • reduce 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 you from runaway token spend and lockups while preserving normal tool access.

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

Notes

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

Next steps

• Agent Configuration
• Tool Definitions

AI Setup Assistant