Loop Detection（工具循环检测）

概述

OpenClaw 提供两个协作的工具调用循环检测护栏：滚动历史循环检测（默认禁用）和压缩后守卫（默认启用）。防止 Agent 陷入重复工具调用循环，避免无限 token 消耗。

两个护栏

1. 循环检测（tools.loopDetection.enabled）：默认禁用。监控滚动工具调用历史中的重复模式和未知工具重试。
2. 压缩后守卫（tools.loopDetection.postCompactionGuard）：默认启用（除非 enabled 显式为 false）。压缩重试后激活，检测相同 (tool, args, result) 三元组。

检测器类型

• genericRepeat：相同工具+相同参数的重复模式，且结果相同时阻止
• knownPollNoProgress：已知轮询类模式无状态变化
• pingPong：交替 ping-pong 模式

配置/使用

{
  tools: {
    loopDetection: {
      enabled: false,           // 主开关（默认 false）
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3,          // 压缩后守卫窗口大小
      },
    },
  },
}

per-agent 覆盖：

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

推荐设置

• 小型模型：启用 enabled: true，使用默认阈值
• 旗舰模型：保持主开关 false，仍受益于压缩后守卫
• 阈值顺序：warningThreshold < criticalThreshold < globalCircuitBreakerThreshold
• 出现误报时：提高阈值或禁用特定检测器

相关页面

• concepts/tool-subagents — Sub-agents（通过隔离限制失控行为）
• concepts/tool-thinking — Thinking 级别与提供商策略交互
• compaction — 对话压缩（压缩后守卫的触发条件）