Skip to main content
OpenClaw 有两道相互配合的防护机制，用于防止重复的工具调用模式， 两者均在 tools.loopDetection 下配置：
  1. 循环检测（enabled）- 默认禁用。监视滚动的 工具调用历史记录，以发现重复模式和对未知工具的重试。
  2. 压缩后防护 - 只要 enabled 未被显式设置为 false，便会启用。每次压缩重试后进入防护状态；如果智能体在窗口内重复相同的 (tool, args, result) 三元组， 则中止运行。
将 tools.loopDetection.enabled: false 设置为静默禁用两道防护机制。

​
存在原因

  • 检测没有取得任何进展的重复序列。
  • 检测高频且无结果的循环（相同工具、相同输入、重复 错误）。
  • 检测已知轮询工具的特定重复调用模式。
  • 打破上下文溢出 -> 压缩 -> 相同循环的周期，而不是让它们 无限期运行。

​
配置块

全局设置：
按智能体覆盖（可选，位于 agents.entries.*.tools.loopDetection）：
按智能体设置会覆盖全局设置。

​
字段行为

对于 exec，无进展哈希会比较稳定的命令结果（状态、 退出代码、超时标志、输出），并忽略易变的运行时元数据，例如 持续时间、PID、会话 ID 和工作目录。出站消息发送 结果在哈希计算时会移除每次调用中易变的 ID（消息 ID、文件 ID、时间戳）， 因此一个“已发送”结果不会与另一个不同的“已发送” 结果看起来完全相同。当运行 ID 可用时，只会在该次运行内评估历史记录， 因此定时 Heartbeat 周期和新运行不会继承 先前运行中陈旧的循环计数。

​
推荐设置

  • 对于较小的模型，请设置 enabled: true。旗舰模型很少需要滚动历史记录检测，可以 将总开关保持为 false，同时仍受益于 压缩后防护。
  • 若要禁用包括压缩后防护在内的所有机制，请显式设置 tools.loopDetection.enabled: false。

​
压缩后防护

在上下文溢出后进行压缩重试之后，运行器会针对接下来的几次工具调用启用 短窗口防护。如果智能体在该窗口内足够多次地发出相同的 (toolName, argsHash, resultHash) 三元组，防护机制会判定压缩未能打破 循环，并以 compaction_loop_persisted 错误中止运行。 该防护机制受总开关 tools.loopDetection.enabled 标志控制，但有一个 特殊之处：当该标志未设置或为 true 时，它会保持启用，仅当该标志被显式设置为 false 时 才会关闭。这是有意为之——该防护机制用于摆脱原本会无限消耗 token 的压缩循环， 因此未进行配置的用户仍能获得保护。
  • 当结果仍在变化时，该防护机制绝不会中止运行；只有窗口内 字节完全相同的结果才会触发它。
  • 它仅在压缩重试后立即启用，而不会在运行中的其他 时刻启用。
只要总开关标志未被显式设置为 false，压缩后防护就会运行，即使你从未编写过 tools.loopDetection 块也是如此。若要验证，请在发生压缩事件后立即在 Gateway 网关日志中查找 post-compaction guard armed for N attempts。

​
日志和预期行为

检测到循环时，OpenClaw 会记录循环事件，并根据严重程度发出警告或阻止 下一个工具周期，从而防止 token 消耗失控和运行锁死，同时保留正常的工具访问能力。
  • 首先发出警告。
  • 当某种模式持续超过警告阈值后，便会进行阻止。
  • 达到严重阈值时，会阻止下一个工具周期，并在运行记录中显示明确的 循环检测原因。
  • 压缩后防护会发出 compaction_loop_persisted 错误，其中会指出 导致问题的工具和相同调用次数。

​
相关内容

Exec 审批

shell 执行的允许/拒绝策略。

思考级别

推理投入级别及其与提供商策略的交互。

子智能体

生成隔离的智能体，以限制失控行为。

配置参考

完整的 tools.loopDetection schema 和合并语义。