Tools
工具迴圈偵測
OpenClaw 有兩道相互配合的防護機制，可避免重複的工具呼叫模式，
兩者皆設定於 tools.loopDetection：
- 迴圈偵測（
enabled）— 預設停用。監控滾動式 工具呼叫歷程中的重複模式與未知工具重試。 - 壓縮後防護 — 只要
enabled未明確設為false，即會啟用。每次壓縮重試後進入戒備狀態；若代理程式在時間窗內重複相同的(tool, args, result)三元組， 便會中止執行。
將 tools.loopDetection.enabled: false 設為靜默停用這兩道防護機制。
為何需要此機制
- 偵測毫無進展的重複序列。
- 偵測高頻率且無結果的迴圈（相同工具、相同輸入、重複 錯誤）。
- 偵測已知輪詢工具的特定重複呼叫模式。
- 中斷「內容超出上限 -> 壓縮 -> 相同迴圈」的循環，而非任其 無限執行。
設定區塊
全域設定：
{ tools: { loopDetection: { enabled: false, // 滾動歷程偵測器的主開關 }, },}個別代理程式覆寫（選用，位於 agents.entries.*.tools.loopDetection）：
{ 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 時才會關閉。這是刻意的設計 — 此防護
用於脫離原本會無上限消耗權杖的壓縮迴圈，
因此未進行任何設定的使用者仍可獲得保護。
{ tools: { loopDetection: { // 主開關；設為 false 可連同滾動偵測器一起停用此防護 enabled: true, }, },}- 結果仍在變化時，防護絕不會中止執行；只有時間窗內 位元組完全相同的結果才會觸發。
- 此防護只會在壓縮重試後的緊接階段啟用，不會在一次執行的其他 時點啟用。
日誌與預期行為
偵測到迴圈時，OpenClaw 會記錄迴圈事件，並依嚴重程度警告或封鎖 下一個工具週期，在保留正常工具存取能力的同時，防止權杖 失控消耗與系統卡死。
- 會先發出警告。
- 當模式持續超過警告門檻後，便會進行封鎖。
- 達到嚴重門檻時，會封鎖下一個工具週期，並在執行記錄中顯示明確的 迴圈偵測原因。
- 壓縮後防護會發出
compaction_loop_persisted錯誤，其中會指出 涉事工具與相同呼叫次數。
