Compaction

Setiap model memiliki jendela konteks: jumlah token maksimum yang dapat diprosesnya. Saat percakapan mendekati batas tersebut, OpenClaw memadatkan pesan lama menjadi ringkasan agar obrolan dapat berlanjut.

# Cara kerjanya

1. Giliran percakapan yang lebih lama diringkas menjadi entri ringkas.
2. Ringkasan disimpan dalam transkrip sesi.
3. Pesan terbaru tetap dipertahankan utuh.

Saat OpenClaw membagi riwayat menjadi potongan pemadatan, OpenClaw menjaga panggilan alat asisten tetap berpasangan dengan entri toolResult yang sesuai. Jika titik pemisahan berada di dalam blok alat, OpenClaw memindahkan batasnya agar pasangan tetap bersama dan ekor saat ini yang belum diringkas tetap dipertahankan.

Riwayat percakapan lengkap tetap ada di disk. Pemadatan hanya mengubah apa yang dilihat model pada giliran berikutnya.

# Pemadatan otomatis

Pemadatan otomatis aktif secara default. Ini berjalan saat sesi mendekati batas konteks, atau saat model mengembalikan kesalahan luapan konteks (dalam hal ini OpenClaw memadatkan lalu mencoba ulang).

Anda akan melihat:

• 🧹 Auto-compaction complete dalam mode verbose.
• /status menampilkan 🧹 Compactions: <count>.

# Pemadatan manual

Ketik /compact di obrolan apa pun untuk memaksa pemadatan. Tambahkan instruksi untuk memandu ringkasan:

/compact Focus on the API design decisions

Saat agents.defaults.compaction.keepRecentTokens diatur, pemadatan manual menghormati titik potong Pi tersebut dan mempertahankan ekor terbaru dalam konteks yang dibangun ulang. Tanpa anggaran simpan eksplisit, pemadatan manual bertindak sebagai checkpoint tegas dan berlanjut hanya dari ringkasan baru.

# Konfigurasi

Konfigurasikan pemadatan di bawah agents.defaults.compaction dalam openclaw.json Anda. Opsi yang paling umum tercantum di bawah; untuk referensi lengkap, lihat Pendalaman manajemen sesi.

# Menggunakan model yang berbeda

Secara default, pemadatan menggunakan model utama agen. Atur agents.defaults.compaction.model untuk mendelegasikan peringkasan ke model yang lebih mampu atau terspesialisasi. Override menerima string provider/model-id apa pun:

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

Ini juga berfungsi dengan model lokal, misalnya model Ollama kedua yang didedikasikan untuk peringkasan:

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}

Jika tidak diatur, pemadatan dimulai dengan model sesi aktif. Jika peringkasan gagal dengan kesalahan penyedia yang memenuhi syarat fallback model, OpenClaw mencoba ulang upaya pemadatan tersebut melalui rantai fallback model sesi yang ada. Pilihan fallback bersifat sementara dan tidak ditulis kembali ke status sesi. Override eksplisit agents.defaults.compaction.model tetap persis dan tidak mewarisi rantai fallback sesi.

# Preservasi pengenal

Peringkasan pemadatan mempertahankan pengenal opak secara default (identifierPolicy: "strict"). Override dengan identifierPolicy: "off" untuk menonaktifkan, atau identifierPolicy: "custom" ditambah identifierInstructions untuk panduan khusus.

# Penjaga byte transkrip aktif

Saat agents.defaults.compaction.maxActiveTranscriptBytes diatur, OpenClaw memicu pemadatan lokal normal sebelum sebuah run jika JSONL aktif mencapai ukuran tersebut. Ini berguna untuk sesi berjalan lama ketika manajemen konteks sisi penyedia dapat menjaga konteks model tetap sehat sementara transkrip lokal terus bertambah. Ini tidak membagi byte JSONL mentah; ini meminta pipeline pemadatan normal membuat ringkasan semantik.

# Transkrip penerus

Saat agents.defaults.compaction.truncateAfterCompaction diaktifkan, OpenClaw tidak menulis ulang transkrip yang ada di tempat. OpenClaw membuat transkrip penerus aktif baru dari ringkasan pemadatan, status yang dipertahankan, dan ekor yang belum diringkas, lalu menyimpan JSONL sebelumnya sebagai sumber checkpoint arsip. Transkrip penerus juga membuang giliran pengguna panjang yang merupakan duplikat persis dan tiba dalam jendela coba ulang yang singkat, sehingga badai coba ulang kanal tidak terbawa ke transkrip aktif berikutnya setelah pemadatan.

Checkpoint pra-pemadatan dipertahankan hanya selama tetap berada di bawah batas ukuran checkpoint OpenClaw; transkrip aktif yang terlalu besar tetap dipadatkan, tetapi OpenClaw melewati snapshot debug besar alih-alih menggandakan penggunaan disk.

# Pemberitahuan pemadatan

Secara default, pemadatan berjalan diam-diam. Atur notifyUser untuk menampilkan pesan status singkat saat pemadatan dimulai dan selesai:

{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

# Flush memori

Sebelum pemadatan, OpenClaw dapat menjalankan giliran flush memori diam-diam untuk menyimpan catatan tahan lama ke disk. Atur agents.defaults.compaction.memoryFlush.model saat giliran pemeliharaan ini harus menggunakan model lokal alih-alih model percakapan aktif:

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

Override model flush memori bersifat persis dan tidak mewarisi rantai fallback sesi aktif. Lihat Memori untuk detail dan konfigurasi.

# Penyedia pemadatan yang dapat dipasang

Plugin dapat mendaftarkan penyedia pemadatan khusus melalui registerCompactionProvider() pada API Plugin. Saat penyedia terdaftar dan dikonfigurasi, OpenClaw mendelegasikan peringkasan kepadanya alih-alih menggunakan pipeline LLM bawaan.

Untuk menggunakan penyedia terdaftar, atur id-nya dalam konfigurasi Anda:

{
  "agents": {
    "defaults": {
      "compaction": {
        "provider": "my-provider"
      }
    }
  }
}

Mengatur provider secara otomatis memaksa mode: "safeguard". Penyedia menerima instruksi pemadatan dan kebijakan preservasi pengenal yang sama seperti jalur bawaan, dan OpenClaw tetap mempertahankan konteks sufiks giliran terbaru dan giliran terpisah setelah keluaran penyedia.

# Pemadatan vs pemangkasan

	Pemadatan	Pemangkasan
Apa fungsinya	Meringkas percakapan lama	Memangkas hasil alat lama
Disimpan?	Ya (dalam transkrip sesi)	Tidak (hanya dalam memori, per permintaan)
Cakupan	Seluruh percakapan	Hanya hasil alat

Pemangkasan sesi adalah pelengkap yang lebih ringan yang memangkas keluaran alat tanpa meringkas.

# Pemecahan masalah

Terlalu sering memadatkan? Jendela konteks model mungkin kecil, atau keluaran alat mungkin besar. Coba aktifkan pemangkasan sesi.

Konteks terasa basi setelah pemadatan? Gunakan /compact Focus on <topic> untuk memandu ringkasan, atau aktifkan flush memori agar catatan tetap bertahan.

Perlu mulai dari awal? /new memulai sesi baru tanpa memadatkan.

Untuk konfigurasi lanjutan (token cadangan, preservasi pengenal, mesin konteks khusus, pemadatan sisi server OpenAI), lihat Pendalaman manajemen sesi.

# Terkait

• Sesi: manajemen sesi dan siklus hidup.
• Pemangkasan sesi: memangkas hasil alat.
• Konteks: cara konteks dibangun untuk giliran agen.
• Hooks: hook siklus hidup pemadatan (before_compaction, after_compaction).