On this page
On this page
Tools
Tool-loop detection
The tool repeat guard stops a model that calls the same tool with the same arguments again and again. It is on by default.
How it works
The guard compares each tool call with the call before it. It compares only the tool name and the canonical arguments (key order does not matter). It never compares results, so a repeated failing call and a repeated successful call count the same way.
- 3rd identical call in a row: the call runs. OpenClaw adds a system note to its result that names the tool and tells the model to change its approach.
- 20th identical call in a row: the call does not run. OpenClaw ends the
turn with the typed reason
tool_repeat_limitand shows this message:OpenClaw stopped this turn: the model called <tool> with the same arguments 20 times in a row. Send a new message to continue.
A different call resets the count. New user input also resets it.
A call to an unavailable tool counts by name only, so a model that keeps trying a missing tool with changing arguments still reaches the note and the stop.
Tools that repeat by design
Some tools poll or wait, so identical calls are expected. These tools declare
repeatable and the guard skips them:
wait(Code Mode)processwithpoll,logorlistagents_wait,sessions_yield, andsubagentswithlistorwaitcomputerwithscreenshotorwait
A plugin tool can declare repeatable: true, or repeatable: { actions: [...] }
to skip only calls whose action argument is listed.
Worker turns (cloud and node workers) run the same guard over all their tools and
follow the same tools.loopDetection.enabled setting.
Configuration
Global setting:
Per-agent override (optional, at agents.entries.*.tools.loopDetection):
The per-agent setting overrides the global setting.
| Field | Default | Effect |
|---|---|---|
enabled |
true |
Set false to turn the tool repeat guard off. |
Older loop-detection keys (warningThreshold, criticalThreshold,
detectors, postCompactionGuard and similar) are retired; openclaw doctor --fix
removes them.
Logs
Each note and each stop writes a tool loop: diagnostic line and a tool.loop
diagnostic event with detector=tool_repeat. A note uses action=warn; a stop
uses action=block.