Tool-Loop Detection Guide

OpenClaw relies on two complementary safeguards to prevent repetitive tool-call behavior, and both are controlled through tools.loopDetection:

Loop detection (enabled) - off by default. It monitors the rolling history of tool calls for recurring patterns and retries of unknown tools.
Post-compaction guard - active whenever enabled is not explicitly set to false. It activates after each compaction-retry and terminates the run if the agent repeats the same (tool, args, result) triple within the defined window.

To disable both safeguards, set tools.loopDetection.enabled: false.

Why this exists

Identify repeated sequences that fail to produce any progress.
Catch high-frequency loops with no output, where the same tool and inputs repeatedly trigger errors.
Spot specific repeated-call patterns for known polling tools.
Stop the context-overflow, compaction, same-loop cycle from running indefinitely.

Configuration block

Global setting:

{
  tools: {
    loopDetection: {
      enabled: false, // master switch for the rolling-history detectors
    },
  },
}

Per-agent override (optional, at agents.entries.*.tools.loopDetection):

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

When both are present, the per-agent value takes precedence over the global one.

The global rolling-history detectors can also be turned on via Settings -> Labs in the Control UI.

Field behavior

Field	Default	Effect
`enabled`	`false`	Primary toggle for the rolling-history detectors. Setting `false` also switches off the post-compaction guard.

For exec, no-progress hashing compares stable command outcomes, including status, exit code, timed-out flag, and output, while discarding volatile runtime details like duration, PID, session ID, and working directory. Outbound message-send results are hashed after stripping per-call identifiers such as message id, file id, and timestamp, so two different "sent" results do not appear identical. When a run id exists, history is evaluated only within that run, meaning scheduled heartbeat cycles and new runs do not carry over stale loop counts from previous runs.

Recommended setup

For smaller models, configure enabled: true. Flagship models usually do not need rolling-history detection and can keep the master switch false while still getting the post-compaction guard.
To turn off everything, including the post-compaction guard, explicitly set tools.loopDetection.enabled: false.

Post-compaction guard

After a compaction-retry triggered by a context-overflow, the runner arms a short-window guard for the next few tool calls. If the agent repeats the same (toolName, argsHash, resultHash) triple enough times within that window, the guard determines that compaction did not break the loop and stops the run with a compaction_loop_persisted error.

The guard depends on the master tools.loopDetection.enabled flag, with one exception: it remains enabled when the flag is unset or true, and only disables when the flag is explicitly false. This is deliberate, since the guard exists to break compaction loops that would otherwise consume unlimited tokens, so even users with no configuration receive the protection.

{
  tools: {
    loopDetection: {
      // master switch; set false to disable the guard along with the rolling detectors
      enabled: true,
    },
  },
}

The guard never aborts while results are changing; only byte-identical results across the window trigger it.
It only arms in the immediate aftermath of a compaction-retry, not at other points in a run.

Note

The post-compaction guard activates whenever the master flag is not explicitly false, even if you never wrote a tools.loopDetection block. To verify, look for post-compaction guard armed for N attempts in the gateway log immediately after a compaction event.

Logs and expected behavior

When a loop is detected, OpenClaw logs a loop event and either warns or blocks the next tool-cycle depending on severity, protecting against runaway token spend and lockups while preserving normal tool access.

Warnings come first.
Blocking follows once a pattern persists past the warning threshold.
In the embedded agent loop, the first critical loop blocks the whole tool batch before any tool in that batch runs. The model then gets one more response with its normal tools.
During that response, the model can answer, ask a question, or continue with a different tool or different arguments.
Another critical loop in the same run blocks its whole batch and ends the run. A new user run starts with a fresh recovery allowance.
The post-compaction guard emits compaction_loop_persisted errors naming the offending tool and identical-call count.

Exec approvals, Allow/deny policy for shell execution.
Thinking levels, Reasoning effort levels and provider-policy interaction.
Sub-agents, Spawning isolated agents to bound runaway behavior.
Configuration reference, Full tools.loopDetection schema and merging semantics.