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

OpenClaw 循环检测机制：防止 AI Agent 陷入死循环

📚 小学子讲技术，带你深入理解 OpenClaw 的核心安全机制

什么是循环检测？

想象一下：你让 AI 帮你完成一个任务，它却一直在同一个地方打转——要么重复执行同一个操作，要么在两个状态之间来回切换，却始终无法完成任务。这就是 AI Agent 的死循环问题。

OpenClaw 作为一款强大的 AI Agent 框架，早就想到了这个问题。它内置了一套完整的循环检测机制（Loop Detection），就像给 AI Agent 装上了一双“火眼金睛”，能够及时发现并阻止这种无意义的重复行为。

为什么需要循环检测？

在 AI Agent 的日常工作中，循环问题很常见：

这些问题不仅浪费计算资源，还可能导致任务超时甚至系统崩溃。OpenClaw 的循环检测机制就是为了解决这些烦恼！

核心概念详解

1. 多维度检测器

OpenClaw 提供了三种不同的检测器，从不同角度捕捉循环行为：

genericRepeat：火眼金睛

这个检测器会记录所有工具调用的模式。当你让 Agent 读取同一个文件 10 次、或者连续 5 次执行 echo hello 时，它就会触发警告。

knownPollNoProgress：轮询克星

有些任务需要 Agent 不断检查状态变化（比如等待用户输入、等待文件上传完成）。但如果连续多次轮询返回的结果完全一样，说明状态根本没变化，Agent 却还在傻傻等待——这时 knownPollNoProgress 就会出手！

pingPong：交替终结者

有时候循环不是简单的重复，而是"左脚-右脚-左脚-右脚"的交替模式。比如：

• 打开某个页面 → 发现没权限 → 关闭 → 打开 → 没权限 → 关闭 → …

这就是典型的 ping-pong 行为，pingPong 检测器专门收拾它！

2. 分级响应机制

OpenClaw 不是简单地发现循环就立即停止，而是设计了三级响应：

🔵 正常状态 → 🟡 警告状态 → 🔴 严重状态 → ⚫ 全局熔断

• 警告阈值（warningThreshold）：默认 10 次触发 → 发送警告，但允许继续执行
• 严重阈值（criticalThreshold）：默认 20 次触发 → 强制停止当前操作
• 全局熔断阈值（globalCircuitBreakerThreshold）：默认 30 次 → 彻底中断任务，防止系统资源耗尽

这种渐进式的设计非常聪明：给 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 的循环检测机制是一个非常实用的安全保护功能：

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

参考来源

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

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