OpenClaw Loop Detection Explained

Loop detection is OpenClaw’s guardrail for agents that keep calling tools without making progress. It is disabled by default because repeated calls are not always bad. A build log may need several checks, and a long task may need status inspection. The point is to catch no-progress patterns before they burn tokens, annoy users, or wedge a session. Use it where the failure mode is expensive enough to justify the guard.

30-second answer

Enable tools.loopDetection when you want repetitive tool-call protection. The config tracks recent history, warning and critical thresholds, a global circuit breaker, and detectors for generic repeats, known polling with no progress, and ping-pong patterns. When a loop is detected, OpenClaw reports a loop event and blocks or dampens the next tool cycle depending on severity.

Where it fits

This is most useful for agents that supervise long-running tools, crons, browser flows, or external APIs. It is less useful for tightly scripted one-shot sessions where the workflow is already bounded. Start with default thresholds, then tune only if you see false positives. The docs explicitly warn that strict settings can block legitimate repeated calls.

Docs-grounded facts

• Loop detection is disabled by default.
• The config includes historySize, warningThreshold, criticalThreshold, and globalCircuitBreakerThreshold.
• Detectors include genericRepeat, knownPollNoProgress, and pingPong.
• Per-agent overrides are supported.
• Exec no-progress checks ignore volatile runtime metadata.
• Recent tool-call history is evaluated within a run when a run id is available.

Set it up deliberately

The global config lives under tools.loopDetection with enabled, historySize, warningThreshold, criticalThreshold, globalCircuitBreakerThreshold, and detector toggles. Per-agent overrides live under agents.list[].tools.loopDetection. That means you can enable it for a risky automation agent without changing every assistant on the gateway.

Use it safely

Keep thresholds ordered: warning below critical below global circuit breaker. If false positives occur, raise warning or critical thresholds, raise the global breaker, disable only the detector causing trouble, or reduce history size. Do not turn every knob at once. For exec, no-progress checks ignore volatile metadata such as duration, PID, session ID, and working directory, focusing on stable outcomes instead.

Common mistakes

The common mistake is treating loop detection as a substitute for good workflow design. It is a safety net, not a plan. Agents should still avoid tight poll loops, use completion events where available, and choose meaningful verification points. Another mistake is enabling aggressive thresholds globally after one bad incident, then blocking legitimate status checks elsewhere.

Verification checklist

Test with a harmless repeated-call scenario and confirm warnings appear before critical blocking. Then test a normal repeated workflow, such as a build status check, and make sure it is not blocked too early. Review logs for loop events and tune thresholds based on observed behavior rather than vibes.

Playbook angle

The OpenClaw Playbook’s stance is simple: prevent runaway loops, but do not punish useful persistence. Loop detection works best when paired with good task design, background completion wakes, and concise human updates for real blockers.

Operator note

OpenClaw Loop Detection Explained works best when it is written into a small runbook instead of left as tribal knowledge. Record the intended owner, the exact config surface, the channel where results should appear, the allowed inputs, the expected output, and the rollback step. OpenClaw gives agents broad tools, but the durable value comes from making each tool boring, repeatable, and auditable. I would rather have one well-scoped loop detection workflow that survives a restart than five clever demos nobody can safely run next week. If the runbook cannot explain when not to use it, keep refining before automation becomes default.

Keep the final proof simple: name the source doc, run the smallest check that proves the path works, and save the result where the next operator will look first.