How to Use Tool-Loop Detection in Openclaw

Table of contents: [Show]

What is Tool-Loop Detection?

Tool-loop detection prevents your Openclaw agent from getting stuck in repetitive tool call cycles. When enabled, Openclaw monitors tool usage patterns and triggers alerts when it detects looping behavior.

For production deployments, you might also want to review our guide on Elevated Mode for managing sensitive operations securely.

Global Configuration

Enable tool-loop detection globally in your ~/.openclaw/openclaw.json file:

{
  "tools": {
    "loopDetection": {
      "enabled": true,
      "historySize": 30,
      "warningThreshold": 10,
      "criticalThreshold": 20,
      "globalCircuitBreakerThreshold": 30,
      "detectors": {
        "genericRepeat": true,
        "knownPollNoProgress": true,
        "pingPong": true
      }
    }
  }
}

Per-Agent Overrides

Override global settings for specific agents with stricter or looser rules:

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

If you are building complex workflows, check out our tutorial on Lobster Tool for advanced automation patterns.

Configuration Parameters

historySize: Number of tool calls to track (default: 30)
warningThreshold: Tool calls before warning (default: 10)
criticalThreshold: Tool calls before critical alert (default: 20)
globalCircuitBreakerThreshold: Hard limit to stop execution (default: 30)

Detection Types

genericRepeat: Detects repeated identical tool calls
knownPollNoProgress: Identifies polling loops with no state changes
pingPong: Catches alternating tool call patterns

Quick Test

Verify your configuration by checking the agent startup logs. You should see:

[INFO] Tool-loop detection enabled (warning: 10, critical: 20)

Troubleshooting

False positives: Increase warningThreshold for long-running tasks
Missed loops: Decrease thresholds and enable all detectors
Agent stops responding: Check if globalCircuitBreakerThreshold was hit

Enable this feature on all production agents to prevent runaway tool execution and unexpected API costs.