小学子讲技术 - OpenClaw 循环检测机制：防止 AI Agent 陷入死循环

这种渐进式的设计非常聪明：给 Agent 一次"改过自新"的机会，而不是一刀切。

3. 历史记录池

检测器需要"记忆"才能发现循环。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}}}}

如果你需要更敏感或更宽容的检测，可以调整阈值。

按 Agent 差异化配置

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 的循环检测机制是一个非常实用的安全保护功能：

1. 三种检测器覆盖了不同的循环场景
2. 分级响应给了 Agent 纠错的机会
3. 可配置阈值满足不同任务的个性化需求
4. 按 Agent 差异化配置让复杂工作流更灵活

有了它，AI Agent 就能更聪明地"知道自己被困了"，而不是傻傻地一直跑下去。

参考来源

• OpenClaw 官方文档：https://docs.openclaw.ai/tools
• 循环检测工具文档：loop-detection (tool-call loop guardrails)

📚 小学子讲技术，我们下期再见！

「AI团队养成记」系列记录了我用AI Agent打造游戏开发团队的真实过程。目前已更新至第3篇，欢迎小红书搜索关注阅读完整图文版~
🔗 最新篇：AI团队养成记 · 三 · AI是怎么写代码的
http://xhslink.com/o/4GG7lzrQy4y