OpenClaw 循环检测机制：防止 AI Agent 陷入死循环 > 📚 小学子讲技术，带你深入理解 OpenClaw 的核心安全机制 * * 什么是循环检测？ 想象一下：你让 AI 帮你完成一个任务，它却一直在同一个地方打转——要么重复执行同一个操作，要么在两个状态之间来回切换，却始终无法完成任务。这就是 AI Agent 的**死循环问题**。 OpenClaw 作为一款强大的 AI Ag…
📚 小学子讲技术，带你深入理解 OpenClaw 的核心安全机制
想象一下：你让 AI 帮你完成一个任务，它却一直在同一个地方打转——要么重复执行同一个操作，要么在两个状态之间来回切换，却始终无法完成任务。这就是 AI Agent 的死循环问题。
OpenClaw 作为一款强大的 AI Agent 框架，早就想到了这个问题。它内置了一套完整的循环检测机制（Loop Detection），就像给 AI Agent 装上了一双'火眼金睛'，能够及时发现并阻止这种无意义的重复行为。
在 AI Agent 的日常工作中，循环问题很常见：
这些问题不仅浪费计算资源，还可能导致任务超时甚至系统崩溃。OpenClaw 的循环检测机制就是为了解决这些烦恼！
OpenClaw 提供了三种不同的检测器，从不同角度捕捉循环行为：
| 检测器 | 作用 | 典型场景 |
|---|---|---|
genericRepeat | 通用重复检测 | 同一个工具+相同参数被反复调用 |
knownPollNoProgress | 轮询无进展检测 | 反复检查某个状态，但结果始终相同 |
pingPong | 乒乓模式检测 | 两个操作交替执行，形成死循环 |
这个检测器会记录所有工具调用的模式。当你让 Agent 读取同一个文件 10 次、或者连续 5 次执行 echo hello 时，它就会触发警告。
有些任务需要 Agent 不断检查状态变化（比如等待用户输入、等待文件上传完成）。但如果连续多次轮询返回的结果完全一样，说明状态根本没变化，Agent 却还在傻傻等待——这时 knownPollNoProgress 就会出手！
有时候循环不是简单的重复，而是"左脚-右脚-左脚-右脚"的交替模式。比如：
这就是典型的 ping-pong 行为，pingPong 检测器专门收拾它！
OpenClaw 不是简单地发现循环就立即停止，而是设计了三级响应：
🔵 正常状态 → 🟡 警告状态 → 🔴 严重状态 → ⚫ 全局熔断
这种渐进式的设计非常聪明：给 Agent 一次"改过自新"的机会，而不是一刀切。
检测器需要"记忆"才能发现循环。historySize 参数控制了这个记忆的大小：
"historySize":30// 记录最近 30 次工具调用
太小的记忆会导致误判（比如正常的重试被当作循环），太大的记忆又会让检测变得迟钝。30 次是一个经过实践验证的合理默认值。
{"tools":{"loopDetection":{"enabled":true}}}
只要打开 enabled 开关，循环检测就生效了！默认参数适合大多数场景。
{"tools":{"loopDetection":{"enabled":true,"warningThreshold":15,"criticalThreshold":25,"globalCircuitBreakerThreshold":40,"historySize":50,"detectors":{"genericRepeat":true,"knownPollNoProgress":true,"pingPong":true}}}}
如果你需要更敏感或更宽容的检测，可以调整阈值。
OpenClaw 支持为不同的 Agent 设置不同的循环检测策略：
{"tools":{"loopDetection":{"enabled":true,"warningThreshold":10,"criticalThreshold":20}},"agents":{"list":[{"id":"research-agent","tools":{"loopDetection":{"warningThreshold":20,"criticalThreshold":35}}},{"id":"quick-task-agent","tools":{"loopDetection":{"warningThreshold":5,"criticalThreshold":10}}}]}}
比如：
research-agent 可以更宽容（需要长时间探索）quick-task-agent 应该更严格（快速失败，快速重试）┌─────────────────────────────────────────────────────┐ │ 工具调用记录 │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ #1 │ │ #2 │ │ #3 │ │ #4 │ │ #5 │ ... │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 循环检测引擎 │ │ ┌──────────────────────────────────────────────┐ │ │ │ genericRepeat │ knownPollNoProgress │ pingPong│ │ │ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ <10次 │ │ 10-20次 │ │ >20次 │ │ 正常 │ │ 警告 │ │ 严重/熔断│ └─────────┘ └─────────┘ └─────────┘
{"action":"read","path":"config.json"}
Agent 连续读取同一个配置文件 15 次，每次都得到相同结果 → 触发警告 → 停止无意义读取
打开页面 → 内容为空 → 刷新 → 还是空 → 刷新 → ...
knownPollNoProgress 检测到连续 10 次刷新返回相同内容 → 发出警告
检查文件A权限 → 无权限 → 检查文件B权限 → 有权限 → 检查文件A权限 → 无权限 → 检查文件B权限 → 有权限 → ...
pingPong 检测到 A/B 交替模式 → 及时中断
OpenClaw 的循环检测机制是一个非常实用的安全保护功能：
有了它，AI Agent 就能更聪明地"知道自己被困了"，而不是傻傻地一直跑下去。
loop-detection (tool-call loop guardrails)📚 小学子讲技术，我们下期再见！
「AI团队养成记」系列记录了我用AI Agent打造游戏开发团队的真实过程。目前已更新至第3篇，欢迎小红书搜索关注阅读完整图文版~
🔗 最新篇：AI团队养成记 · 三 · AI是怎么写代码的
http://xhslink.com/o/4GG7lzrQy4y
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online