本页内容
本页内容
工具
工具循环检测
OpenClaw 总是在连续三个相同的工具错误后停止转动:相同的工具、参数和错误结果。该窄保护独立于 tools.loopDetection,包括显式 enabled: false。该回合以记录的错误结束,解释如何恢复,例如检查参数或切换到使用本机工具调用的模型。更改的结果、更改的参数和成功的调用都会重置错误条纹,因此重试进度和正常轮询将继续。
tools.loopDetection下配置了两个额外的护栏:
- 循环检测(
enabled)- 默认禁用。监视滚动的工具调用历史,查找重复模式和未知工具重试。 - 压缩后保护 - 当
enabled不是明确的false时启用。每次压缩重试后进行准备,如果代理在窗口内重复相同的(tool, args, result)三元组,则中止运行。
设置 tools.loopDetection.enabled: false 以禁用这两个附加护栏。
为什么存在这个
- 检测没有进展的重复序列。
- 检测高频无结果循环(同一工具、相同输入、重复错误)。
- 检测已知轮询工具的特定重复调用模式。
- 打破上下文溢出 -> 压缩 -> 相同循环的循环,而不是让它们无限运行。
配置块
全局设置:
按代理覆盖(可选,位于 agents.entries.*.tools.loopDetection):
按代理设置会覆盖全局设置。
您还可以在 Control UI 中的 Settings → Agent Defaults → Tools 中启用全局滚动历史检测器。将设置重置为默认值以禁用滚动检测器,同时保留后压实防护;明确关闭它会禁用两者。
字段行为
| 字段 | 默认值 | 作用 |
|---|---|---|
enabled |
false |
rolling-history 检测器的总开关。false 还会禁用压缩后保护。 |
执行标题不区分其他相同的 exec 调用。代码模式还提供私有结果标识:簿记计数器和延续 ID 不计为进度。自动保留的值使用其原始值标识,而不是新的结果引用 ID。待处理的工作通过其操作和参数进行比较,而更改的输出、返回值和错误仍然有意义。显示的收据和访客数据未更改,包括名为遥测或pendingToolCalls 的访客字段。这不会检测任意语义等效的 JavaScript 重写或使后台进程在网关重新启动后继续存在。
对于 exec,无进度哈希比较稳定的命令结果(状态、退出代码、超时标志、输出)并忽略易失性运行时元数据,例如持续时间、PID、会话 ID 和工作目录。对于键入的终端故障,它还会忽略诊断时间戳、显式尝试或重试计数器、经过的持续时间和标记的进程 ID。其他文本和数字仍然很重要,因此新的故障原因会重置该条纹。
对于成功的 memory_search 结果,比较会保留有序命中及其内容,同时忽略每次调用调试计时和总命中分数(随着时间衰减而变化)。对命中顺序、路径、片段、行范围、警告或其他稳定结果元数据的更改仍然算作进度。分数和调试数据保留在交付的结果中;错误结果保持充分比较。
出站消息发送结果经过哈希处理,并剥离了易失性的每次调用 ID(消息 ID、文件 ID、时间戳),因此仅传递 ID 并不会使重复的等效发送看起来像进度。当运行 ID 可用时,仅在该运行中评估历史记录,因此计划的心跳周期和新运行不会继承早期运行的过时循环计数。
成功的 progress_card 调用将使用保存的 Markdown 和计划进行比较,而不是使用其写入修订或收据措辞。已保存的修订和已交付的收据未更改,因此即使卡内容未更改,请求的刷新仍会收到更新的已保存修订。没有工具私有语义结果的错误和结果保持完整的结果比较。
被参数验证拒绝的调用(例如没有 command 的 exec)永远不会运行,但它们会被记录为失败的调用,因此像任何其他循环一样检测到重复调用。它们不会延长或结束 exec 连续故障。
比较 computer get_window_state 的窗口观测结果,无需新的观测结果和元素参考。像素、元素标签、值、边界和其他观察数据仍然算作更改。面向模型的结果保留新的引用,而陈旧的引用对于后续输入仍然无效。
结果比较还忽略新的外部内容包装器随机数,包括包装的错误和 JSON 结果。交付的安全标记保持不变;有效负载文本、状态、时间戳和持续时间仍然区分网络结果。这是语法比较:与完整包装器格式匹配的文字或复制文本也会忽略仅随机数更改。它不会验证内容、更改授权或修改交付的工具结果。
推荐设置
- 对于较小的模型,设置
enabled: true。旗舰模型很少需要滚动历史检测,并且可以不设置主开关,同时仍然受益于压缩后保护。 - 要禁用滚动检测器和后压实防护,请显式设置
tools.loopDetection.enabled: false。相同错误防护保持活动状态。
重复刀具错误
三个相同的连续失败允许初始尝试和两次重试。第三次失败会结束回合,而不会要求模型提供其他响应。未知的工具 ID 会被视为请求名称的错误。循环策略否决保留之前的失败证据而不是重置连续记录。
在记录终端故障之前已经运行的并行调用已解决;批次中未启动的调用将被阻止。错误计数遵循模型的调用顺序,而不是完成时间。承诺的用户消息开始重新计数,包括跟进和指导。在没有新用户输入的情况下继续重试将保留当前计数。
压缩后护栏
在因上下文溢出而进行一次压缩重试之后,运行器会在接下来的几次工具调用上启用一个短窗口护栏。如果代理在该窗口内多次发出相同的 (toolName, argsHash, resultHash) 三元组,护栏就会判定压缩并未打破该循环,并以 compaction_loop_persisted 错误终止运行。
该护栏受主开关 tools.loopDetection.enabled 控制,但有一个例外:当该标志未设置或为 true 时,它仍然保持启用,只有在该标志被显式设为 false 时才会关闭。这样设计是有意为之——护栏的存在就是为了跳出压缩循环,否则这些循环会无上限地消耗 token,因此即使是不配置的用户也能获得保护。
- 防护程序比较标准化结果哈希值,而不是原始结果字节。有意义的改变可以防止它中止;单独的新鲜包装随机数并不能算作进度。
- 它只会在一次压缩重试后的紧接阶段启用,而不会在运行中的其他时刻启用。
日志和预期行为
始终开启的相同错误防护以可见错误结束回合。可选的滚动探测器使用以下警告和恢复顺序:
- 警告优先。在 OpenClaw- 执行的工具调用上,受影响的工具结果中会附加一个简短的系统注释,以便模型可以在关键块之前更改方法。警告共享诊断日志的速率限制,而不是出现在每次重复调用上。原始结果是在添加注释之前记录的,因此警告文本不算作进度。
- 当某种模式持续超过警告阈值后,系统会进行阻止。
- 使用相同的参数和结果重复
wait十次会阻塞下一次等待。改变的结果重置了连胜。这使用下面描述的相同的恢复响应和终端处理;它不会取消仍在执行的工具调用。 - 在嵌入式代理循环中,第一次严重循环会在该工具批次中的任何工具运行之前阻止整个工具批次。随后,模型还会使用其正常工具再获得一次响应机会。
- 在这次响应期间,模型可以直接回答、提出问题,或使用不同的工具或不同的参数继续操作。
- 同一运行中再次出现严重循环时,系统会阻止其整个工具批次并结束本次运行。新的用户运行会以全新的恢复额度开始。
- 压缩后的防护机制会发出
compaction_loop_persisted错误,其中会标明触发问题的工具和相同调用的次数。