Skip to main content
OpenClaw memiliki dua pagar pengaman yang bekerja sama untuk mencegah pola pemanggilan alat berulang, keduanya dikonfigurasi di bawah tools.loopDetection:
  1. Deteksi loop (enabled) - dinonaktifkan secara default. Memantau riwayat pemanggilan alat bergulir untuk mendeteksi pola berulang dan percobaan ulang alat yang tidak dikenal.
  2. Pengaman pasca-compaction - diaktifkan setiap kali enabled tidak ditetapkan secara eksplisit ke false. Diaktifkan setelah setiap percobaan ulang compaction dan membatalkan proses jika agen mengulangi tiga serangkai (tool, args, result) yang sama dalam jendela tersebut.
Tetapkan tools.loopDetection.enabled: false untuk menonaktifkan kedua pagar pengaman.

​
Alasan fitur ini tersedia

  • Mendeteksi urutan berulang yang tidak menghasilkan kemajuan.
  • Mendeteksi loop tanpa hasil berfrekuensi tinggi (alat yang sama, input yang sama, kesalahan berulang).
  • Mendeteksi pola pemanggilan berulang tertentu untuk alat polling yang dikenal.
  • Memutus siklus luapan konteks -> compaction -> loop yang sama, alih-alih membiarkannya berjalan tanpa batas.

​
Blok konfigurasi

Pengaturan global:
Penggantian per agen (opsional, di agents.list[].tools.loopDetection):
Pengaturan per agen menggantikan pengaturan global.

​
Perilaku bidang

Untuk exec, hashing tanpa kemajuan membandingkan hasil perintah yang stabil (status, kode keluar, tanda batas waktu terlampaui, output) dan mengabaikan metadata runtime yang berubah-ubah seperti durasi, PID, ID sesi, dan direktori kerja. Hasil pengiriman pesan keluar di-hash setelah ID per pemanggilan yang berubah-ubah (ID pesan, ID file, stempel waktu) dihapus, sehingga hasil “terkirim” tidak terlihat identik dengan hasil “terkirim” yang berbeda. Ketika ID proses tersedia, riwayat hanya dievaluasi dalam proses tersebut, sehingga siklus Heartbeat terjadwal dan proses baru tidak mewarisi jumlah loop usang dari proses sebelumnya.

​
Penyiapan yang disarankan

  • Untuk model yang lebih kecil, tetapkan enabled: true. Model unggulan jarang memerlukan deteksi riwayat bergulir dan dapat membiarkan sakelar utama false sambil tetap memperoleh manfaat dari pengaman pasca-compaction.
  • Untuk menonaktifkan semuanya, termasuk pengaman pasca-compaction, tetapkan tools.loopDetection.enabled: false secara eksplisit.

​
Pengaman pasca-compaction

Setelah percobaan ulang compaction yang mengikuti luapan konteks, runner mengaktifkan pengaman berjendela pendek pada beberapa pemanggilan alat berikutnya. Jika agen menghasilkan tiga serangkai (toolName, argsHash, resultHash) yang sama cukup banyak kali dalam jendela tersebut, pengaman menyimpulkan bahwa compaction tidak memutus loop dan membatalkan proses dengan kesalahan compaction_loop_persisted. Pengaman dikendalikan oleh tanda utama tools.loopDetection.enabled dengan satu pengecualian: pengaman tetap diaktifkan ketika tanda tidak ditetapkan atau true, dan hanya dinonaktifkan ketika tanda secara eksplisit bernilai false. Hal ini disengaja - pengaman tersedia untuk keluar dari loop compaction yang jika tidak ditangani akan menghabiskan token tanpa batas, sehingga pengguna tanpa konfigurasi tetap mendapatkan perlindungan.
  • Pengaman tidak pernah membatalkan proses selama hasil masih berubah; hanya hasil yang identik byte demi byte di seluruh jendela yang memicunya.
  • Pengaman hanya diaktifkan segera setelah percobaan ulang compaction, bukan pada titik lain dalam suatu proses.
Pengaman pasca-compaction berjalan setiap kali tanda utama tidak ditetapkan secara eksplisit ke false, meskipun Anda tidak pernah menulis blok tools.loopDetection. Untuk memverifikasinya, cari post-compaction guard armed for N attempts dalam log Gateway segera setelah peristiwa compaction.

​
Log dan perilaku yang diharapkan

Ketika loop terdeteksi, OpenClaw mencatat peristiwa loop dan memberikan peringatan atau memblokir siklus alat berikutnya bergantung pada tingkat keparahannya, sehingga melindungi dari penggunaan token tak terkendali dan kebuntuan sekaligus mempertahankan akses alat normal.
  • Peringatan diberikan terlebih dahulu.
  • Pemblokiran dilakukan setelah pola berlanjut melewati ambang peringatan.
  • Ambang kritis memblokir siklus alat berikutnya dan menampilkan alasan deteksi loop yang jelas dalam catatan proses.
  • Pengaman pasca-compaction menghasilkan kesalahan compaction_loop_persisted yang menyebutkan alat penyebab dan jumlah pemanggilan identik.

​
Terkait

Persetujuan eksekusi

Kebijakan izinkan/tolak untuk eksekusi shell.

Tingkat pemikiran

Tingkat upaya penalaran dan interaksi dengan kebijakan penyedia.

Subagen

Membuat agen terisolasi untuk membatasi perilaku tak terkendali.

Referensi konfigurasi

Skema lengkap tools.loopDetection dan semantik penggabungan.