> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 工具迴圈偵測
OpenClaw 有兩道相互配合的防護機制，可避免重複的工具呼叫模式，
兩者皆設定於 `tools.loopDetection`：
1. **迴圈偵測**（`enabled`）— 預設停用。監控滾動式
工具呼叫歷程中的重複模式與未知工具重試。
2. **壓縮後防護** — 只要
`enabled` 未明確設為 `false`，即會啟用。每次壓縮重試後進入戒備狀態；若代理程式在時間窗內重複相同的 `(tool, args, result)` 三元組，
便會中止執行。
將 `tools.loopDetection.enabled: false` 設為靜默停用這兩道防護機制。
## 為何需要此機制
* 偵測毫無進展的重複序列。
* 偵測高頻率且無結果的迴圈（相同工具、相同輸入、重複
錯誤）。
* 偵測已知輪詢工具的特定重複呼叫模式。
* 中斷「內容超出上限 -> 壓縮 -> 相同迴圈」的循環，而非任其
無限執行。
## 設定區塊
全域設定：
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
tools: {
loopDetection: {
enabled: false, // 滾動歷程偵測器的主開關
},
},
}
```
個別代理程式覆寫（選用，位於 `agents.entries.*.tools.loopDetection`）：
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
list: [
{
id: "safe-runner",
tools: {
loopDetection: {
enabled: true,
},
},
},
],
},
}
```
個別代理程式設定會覆寫全域設定。
### 欄位行為
| 欄位 | 預設值 | 效果 |
| --------- | ------- | ------------------------------ |
| `enabled` | `false` | 滾動歷程偵測器的主開關。`false` 也會停用壓縮後防護。 |
對於 `exec`，無進展雜湊會比較穩定的命令結果（狀態、
結束代碼、逾時旗標、輸出），並忽略持續時間、PID、工作階段 ID 與工作目錄等
易變的執行階段中繼資料。外送訊息的傳送
結果在雜湊前會移除每次呼叫都會變動的 ID（訊息 ID、檔案 ID、時間戳記），
因此某次「已傳送」結果不會看起來與另一次不同的「已傳送」
結果完全相同。若有執行 ID，則只會在該次執行內評估歷程，
因此排程的心跳偵測週期與全新執行不會繼承
先前執行留下的過時迴圈計數。
## 建議設定
* 對於較小的模型，請設定 `enabled: true`。旗艦模型很少需要滾動歷程偵測，因此可
將主開關保持為 `false`，同時仍受益於
壓縮後防護。
* 若要停用所有機制（包括壓縮後防護），請明確設定
`tools.loopDetection.enabled: false`。
## 壓縮後防護
在內容超出上限後進行壓縮重試時，執行器會針對接下來幾次工具呼叫啟用
短時間窗防護。若代理程式在該時間窗內多次發出相同的
`(toolName, argsHash, resultHash)` 三元組，防護機制便會判定壓縮未能中斷
迴圈，並以 `compaction_loop_persisted` 錯誤中止執行。
此防護受主 `tools.loopDetection.enabled` 旗標控制，但有一項
特殊之處：旗標未設定或為 `true` 時，防護會保持**啟用**；只有
旗標明確設為 `false` 時才會關閉。這是刻意的設計 — 此防護
用於脫離原本會無上限消耗權杖的壓縮迴圈，
因此未進行任何設定的使用者仍可獲得保護。
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
tools: {
loopDetection: {
// 主開關；設為 false 可連同滾動偵測器一起停用此防護
enabled: true,
},
},
}
```
* 結果仍在變化時，防護絕不會中止執行；只有時間窗內
位元組完全相同的結果才會觸發。
* 此防護只會在壓縮重試後的緊接階段啟用，不會在一次執行的其他
時點啟用。
只要主旗標未明確設為 `false`，壓縮後防護就會執行，即使你從未編寫 `tools.loopDetection` 區塊也是如此。若要驗證，請在壓縮事件後立即查看閘道日誌中是否出現 `post-compaction guard armed for N attempts`。
## 日誌與預期行為
偵測到迴圈時，OpenClaw 會記錄迴圈事件，並依嚴重程度警告或封鎖
下一個工具週期，在保留正常工具存取能力的同時，防止權杖
失控消耗與系統卡死。
* 會先發出警告。
* 當模式持續超過警告門檻後，便會進行封鎖。
* 達到嚴重門檻時，會封鎖下一個工具週期，並在執行記錄中顯示明確的
迴圈偵測原因。
* 壓縮後防護會發出 `compaction_loop_persisted` 錯誤，其中會指出
涉事工具與相同呼叫次數。
## 相關內容
Shell 執行的允許／拒絕政策。
推理投入程度與供應商政策的互動。
產生隔離的代理程式，以限制失控行為。
完整的 `tools.loopDetection` 結構描述與合併語意。