mirror of
https://github.com/openclaw/openclaw.git
synced 2026-11-16 13:08:44 +00:00
## Problem
The tool-loop guard was 12 files and about 1,700 lines. It hashed tool outcomes, had name checks for single tools (exec, message, wait, memory_search, computer, progress_card, write, process), and had four separate detectors plus a post-compaction guard. Rolling detection was opt-in, so most installs did not use it.
One part was always on: after 3 identical failing calls, the next identical call ended the turn. The model got no chance to answer, and the user got a stop message in place of an answer.
## Fix
One guard in `packages/agent-core/src/tool-repeat-guard.ts` (105 lines), used by the agent loop:
- It compares each tool call with the call before it. It compares the tool name and the canonical arguments only. It never compares outcomes.
- 3rd identical call in a row: the call runs, and a redirect note is added to its result. The note names the tool and tells the model to change its approach.
- 20th identical call in a row: the call does not run. The turn ends with the typed reason `tool_repeat_limit` and 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.`
- Tools declare `repeatable` themselves and skip the check: Code Mode `wait`, `process` poll/log/list, `agents_wait`, `sessions_yield`, `subagents` list/wait, `computer` screenshot/wait. The declaration is plain data (`true` or `{ actions: [...] }`), so it crosses the worker wire.
- Worker turns (cloud and node workers) run the same guard over all their tools. The Gateway resolves `tools.loopDetection.enabled` (agent over global) into the worker tool-surface policy as `toolRepeatGuard`, and each tool definition carries its `repeatable` exemption. Two optional fields are added to the closed worker tool-surface schema (`definition.repeatable`, `policy.toolRepeatGuard`); worker bundles are build-bound to the Gateway.
- Calls to an unknown tool are keyed by name.
- New user input resets the streak.
Removed: outcome hashing, per-tool checks, argument churn, ping-pong, the rolling history, batch admission and recovery state, the post-compaction guard, the "3 identical failures" hard stop and its error code. Repeated identical failing calls now get the same note and cap as any other repeat.
Config:
- `tools.loopDetection.enabled` stays. `false` turns the guard off. Unset or `true` keeps it on. This also folds the rolling detection that was opt-in into the one default rule.
- The Codex `appServer.loopDetectionPreToolUseRelay` key is retired. `openclaw doctor --fix` removes it.
- The `tool.loop` diagnostic event stays, with `detector: "tool_repeat"`.
## User impact
- A model that repeats a failing call now gets a note and can still answer, instead of the turn ending after 3 failures.
- A model stuck on one call is stopped after 20 identical calls with a clear message, on local and worker turns alike.
- `tools.loopDetection.enabled: false` still turns the guard off. Existing configs keep loading; `openclaw doctor --fix` removes the retired keys.
## Proof
| Check | Tier | Base (`
|
||
|---|---|---|
| .. | ||
| app-server.md | ||
| commands.md | ||
| config-fields.md | ||
| configuration.md | ||
| native-features.md | ||
| placement.md | ||
| routing.md | ||
| runtime-behavior.md | ||
| troubleshooting.md | ||