工具循环检测

OpenClaw 可以阻止 Agent 陷入重复工具调用模式。 该守护功能默认关闭。

只在必要时启用，因为设置过严会误拦截合法的重复调用。

为什么需要这个功能

• 检测没有实质进展的重复调用序列。
• 检测高频无结果循环（相同工具、相同输入、反复报错）。
• 检测已知轮询工具的特定重复调用模式。

配置块

全局默认值：

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

单 Agent 覆盖（可选）：

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

字段说明

• enabled：总开关。false 表示不执行任何循环检测。
• historySize：保留用于分析的最近工具调用数量。
• warningThreshold：触发"仅警告"分类的阈值。
• criticalThreshold：阻断重复循环模式的阈值。
• globalCircuitBreakerThreshold：全局无进展熔断阈值。
• detectors.genericRepeat：检测相同工具 + 相同参数的重复调用模式。
• detectors.knownPollNoProgress：检测已知类轮询模式且无状态变化的情况。
• detectors.pingPong：检测交替乒乓模式。

推荐设置

• 从 enabled: true、保持默认值开始。
• 保持阈值顺序：warningThreshold < criticalThreshold < globalCircuitBreakerThreshold。
• 如果出现误报：
  • 提高 warningThreshold 和/或 criticalThreshold
  • （可选）提高 globalCircuitBreakerThreshold
  • 仅禁用导致问题的检测器
  • 降低 historySize 以减少历史上下文的严格程度

日志与预期行为

检测到循环时，OpenClaw 会上报循环事件，并根据严重程度阻断或抑制下一个工具周期。 这可以保护用户免受失控 token 消耗和卡死的影响，同时保留正常工具访问。

• 优先使用警告和临时抑制。
• 只有在反复积累证据后才升级处理。

注意事项

• tools.loopDetection 会与 Agent 级覆盖合并。
• 单 Agent 配置会完全覆盖或扩展全局值。
• 如果不存在配置，守护保持关闭。

养龙虾小贴士：如果你的龙虾在某个任务上来回打转，检查一下是不是工具返回结果格式不对，导致 LLM 一直重试。循环检测是最后一道防线，根本原因排查更重要。