Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 可以防止智能体陷入重复的工具调用模式。 该护栏默认禁用。 仅在需要时启用，因为在严格设置下它可能会阻止合法的重复调用。

​
这样设计的原因

  • 检测不会取得进展的重复序列。
  • 检测高频、无结果的循环（相同工具、相同输入、重复错误）。
  • 检测已知轮询工具的特定重复调用模式。

​
配置块

全局默认值： 
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
按智能体覆盖（可选）： 
{
  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：检测交替的乒乓模式。
对于 exec，无进展检查会比较稳定的命令结果，并忽略诸如持续时间、PID、会话 ID 和工作目录等易变的运行时元数据。 当有 run id 可用时，最近的工具调用历史只会在该 run 内进行评估，因此计划中的心跳周期和新的运行不会继承早期运行中的旧循环计数。

​
推荐设置

  • 对于较小的模型，建议从 enabled: true 开始，并保持默认值不变。旗舰模型通常很少需要循环检测，可以保持禁用。
  • 保持阈值顺序为 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold。
  • 如果出现误报：
    • 提高 warningThreshold 和/或 criticalThreshold
    • （可选）提高 globalCircuitBreakerThreshold
    • 仅禁用引起问题的检测器
    • 降低 historySize 以减少历史上下文的严格程度

​
日志和预期行为

检测到循环时，OpenClaw 会报告一个循环事件，并根据严重程度阻止或抑制下一次工具循环。 这可以保护用户免受失控的 token 消耗和卡死，同时保留正常的工具访问。
  • 优先使用警告和临时抑制。
  • 只有在重复证据不断累积时才升级处理。

​
注意事项

  • tools.loopDetection 会与智能体级别的覆盖配置合并。
  • 每个智能体的配置会完全覆盖或扩展全局值。
  • 如果不存在配置，护栏将保持关闭。

​
相关内容