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

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

---

什么是循环检测？

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

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

---

为什么需要循环检测？

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

1. 工具调用死循环：Agent 反复调用同一个工具，每次都得到相同的结果，却认为自己在进步
2. 决策振荡：在两个选项之间反复横跳，陷入"A-B-A-B"的无限循环
3. 轮询陷阱：不断检查某个状态是否变化，但状态永远不变

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

---

核心概念详解

1. 多维度检测器

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

检测器	作用	典型场景
genericRepeat	通用重复检测	同一个工具+相同参数被反复调用
knownPollNoProgress	轮询无进展检测	反复检查某个状态，但结果始终相同
pingPong	乒乓模式检测	两个操作交替执行，形成死循环

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

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

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

---

参考来源

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

---

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