​

Manajemen Sesi & Pemadatan (Pendalaman)

• Perutean sesi (bagaimana pesan masuk dipetakan ke sessionKey)
• Penyimpanan sesi (sessions.json) dan apa yang dilacak
• Persistensi transkrip (*.jsonl) dan strukturnya
• Kebersihan transkrip (penyesuaian khusus penyedia sebelum dijalankan)
• Batas konteks (jendela konteks vs token yang dilacak)
• Pemadatan (pemadatan manual + otomatis) dan tempat mengaitkan pekerjaan pra-pemadatan
• Housekeeping senyap (misalnya, penulisan memori yang seharusnya tidak menghasilkan output yang terlihat oleh pengguna)

• /concepts/session
• /concepts/compaction
• /concepts/memory
• /concepts/memory-search
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Sumber kebenaran: Gateway

• UI (aplikasi macOS, UI Kontrol web, TUI) harus meminta daftar sesi dan jumlah token ke Gateway.
• Dalam mode jarak jauh, file sesi berada di host jarak jauh; “memeriksa file Mac lokal Anda” tidak akan mencerminkan apa yang digunakan oleh Gateway.

​

Dua lapisan persistensi

1. Penyimpanan sesi (sessions.json)
   • Peta key/value: sessionKey -> SessionEntry
   • Kecil, dapat diubah, aman untuk diedit (atau menghapus entri)
   • Melacak metadata sesi (ID sesi saat ini, aktivitas terakhir, toggle, penghitung token, dll.)
2. Transkrip (<sessionId>.jsonl)
   • Transkrip append-only dengan struktur pohon (entri memiliki id + parentId)
   • Menyimpan percakapan sebenarnya + panggilan alat + ringkasan pemadatan
   • Digunakan untuk membangun ulang konteks model untuk giliran mendatang

​

Lokasi di disk

• Penyimpanan: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transkrip: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Sesi topik Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Pemeliharaan penyimpanan dan kontrol disk

• mode: warn (default) atau enforce
• pruneAfter: batas usia entri usang (default 30d)
• maxEntries: batas entri di sessions.json (default 500)
• rotateBytes: rotasi sessions.json saat terlalu besar (default 10mb)
• resetArchiveRetention: retensi untuk arsip transkrip *.reset.<timestamp> (default: sama dengan pruneAfter; false menonaktifkan pembersihan)
• maxDiskBytes: anggaran opsional untuk direktori sesi
• highWaterBytes: target opsional setelah pembersihan (default 80% dari maxDiskBytes)

1. Hapus artefak transkrip arsip atau yatim tertua terlebih dahulu.
2. Jika masih di atas target, keluarkan entri sesi tertua beserta file transkripnya.
3. Lanjutkan sampai penggunaan berada pada atau di bawah highWaterBytes.

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Sesi cron dan log run

• cron.sessionRetention (default 24h) memangkas sesi run cron terisolasi lama dari penyimpanan sesi (false menonaktifkan).
• cron.runLog.maxBytes + cron.runLog.keepLines memangkas file ~/.openclaw/cron/runs/<jobId>.jsonl (default: 2_000_000 byte dan 2000 baris).

​

Kunci sesi (sessionKey)

• Obrolan utama/langsung (per agen): agent:<agentId>:<mainKey> (default main)
• Grup: agent:<agentId>:<channel>:group:<id>
• Ruangan/channel (Discord/Slack): agent:<agentId>:<channel>:channel:<id> atau ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (kecuali ditimpa)

​

ID sesi (sessionId)

• Reset (/new, /reset) membuat sessionId baru untuk sessionKey tersebut.
• Reset harian (default pukul 4:00 pagi waktu lokal di host gateway) membuat sessionId baru pada pesan berikutnya setelah batas reset.
• Kedaluwarsa idle (session.reset.idleMinutes atau session.idleMinutes lama) membuat sessionId baru ketika pesan tiba setelah jendela idle. Saat harian + idle sama-sama dikonfigurasi, yang kedaluwarsa lebih dulu yang berlaku.
• Pelindung fork induk thread (session.parentForkMaxTokens, default 100000) melewati forking transkrip induk ketika sesi induk sudah terlalu besar; thread baru dimulai dari awal. Tetapkan 0 untuk menonaktifkan.

​

Skema penyimpanan sesi (sessions.json)

• sessionId: ID transkrip saat ini (nama file diturunkan dari ini kecuali sessionFile ditetapkan)
• updatedAt: stempel waktu aktivitas terakhir
• sessionFile: penggantian jalur transkrip eksplisit opsional
• chatType: direct | group | room (membantu UI dan kebijakan pengiriman)
• provider, subject, room, space, displayName: metadata untuk pelabelan grup/channel
• Toggle:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (penggantian per sesi)
• Pemilihan model:
  • providerOverride, modelOverride, authProfileOverride
• Penghitung token (best-effort / bergantung pada penyedia):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: seberapa sering pemadatan otomatis selesai untuk kunci sesi ini
• memoryFlushAt: stempel waktu untuk flush memori pra-pemadatan terakhir
• memoryFlushCompactionCount: jumlah pemadatan saat flush terakhir dijalankan

​

Struktur transkrip (*.jsonl)

• Baris pertama: header sesi (type: "session", menyertakan id, cwd, timestamp, parentSession opsional)
• Lalu: entri sesi dengan id + parentId (pohon)

• message: pesan pengguna/asisten/toolResult
• custom_message: pesan yang disisipkan ekstensi yang memang masuk ke konteks model (dapat disembunyikan dari UI)
• custom: status ekstensi yang tidak masuk ke konteks model
• compaction: ringkasan pemadatan yang dipersistenkan dengan firstKeptEntryId dan tokensBefore
• branch_summary: ringkasan yang dipersistenkan saat menavigasi cabang pohon

​

Jendela konteks vs token yang dilacak

1. Jendela konteks model: batas keras per model (token yang terlihat oleh model)
2. Penghitung penyimpanan sesi: statistik bergulir yang ditulis ke sessions.json (digunakan untuk /status dan dasbor)

• Jendela konteks berasal dari katalog model (dan dapat ditimpa melalui konfigurasi).
• contextTokens dalam penyimpanan adalah nilai estimasi/pelaporan runtime; jangan anggap itu sebagai jaminan ketat.

​

Pemadatan: apa itu

• Ringkasan pemadatan
• Pesan setelah firstKeptEntryId

​

Batas potongan pemadatan dan pemasangan alat

• Jika pembagian berdasarkan porsi token jatuh di antara panggilan alat dan hasilnya, OpenClaw menggeser batas ke pesan panggilan alat asisten alih-alih memisahkan pasangan tersebut.
• Jika blok tool-result di akhir sebaliknya akan mendorong potongan melewati target, OpenClaw mempertahankan blok alat yang tertunda itu dan menjaga ekor yang belum diringkas tetap utuh.
• Blok panggilan alat yang dibatalkan/error tidak menahan pembagian tertunda tetap terbuka.

​

Kapan pemadatan otomatis terjadi (runtime Pi)

1. Pemulihan overflow: model mengembalikan kesalahan overflow konteks (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded, dan varian serupa yang dibentuk penyedia) → padatkan → coba lagi.
2. Pemeliharaan ambang batas: setelah giliran berhasil, ketika:

• contextWindow adalah jendela konteks model
• reserveTokens adalah ruang cadangan yang disisihkan untuk prompt + output model berikutnya

​

Pengaturan pemadatan (reserveTokens, keepRecentTokens)

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

• Jika compaction.reserveTokens < reserveTokensFloor, OpenClaw menaikkannya.
• Ambang bawah default adalah 20000 token.
• Tetapkan agents.defaults.compaction.reserveTokensFloor: 0 untuk menonaktifkan ambang bawah.
• Jika sudah lebih tinggi, OpenClaw membiarkannya.

​

Permukaan yang terlihat pengguna

• /status (dalam sesi obrolan apa pun)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Mode verbose: 🧹 Auto-compaction complete + jumlah pemadatan

​

Housekeeping senyap (NO_REPLY)

• Asisten memulai outputnya dengan token senyap yang persis NO_REPLY / no_reply untuk menunjukkan “jangan kirim balasan ke pengguna”.
• OpenClaw menghapus/menekan ini di lapisan pengiriman.
• Penekanan token senyap persis tidak peka huruf besar-kecil, jadi NO_REPLY dan no_reply sama-sama dihitung ketika seluruh payload hanyalah token senyap.
• Ini hanya untuk giliran latar belakang/tanpa pengiriman yang benar-benar demikian; ini bukan jalan pintas untuk permintaan pengguna biasa yang dapat ditindaklanjuti.

​

”Flush memori” pra-pemadatan (diimplementasikan)

1. Pantau penggunaan konteks sesi.
2. Saat melampaui “ambang lunak” (di bawah ambang pemadatan Pi), jalankan arahan senyap “tulis memori sekarang” ke agen.
3. Gunakan token senyap persis NO_REPLY / no_reply agar pengguna tidak melihat apa pun.

• enabled (default: true)
• softThresholdTokens (default: 4000)
• prompt (pesan pengguna untuk giliran flush)
• systemPrompt (prompt sistem tambahan yang ditambahkan untuk giliran flush)

• Prompt/prompt sistem default menyertakan petunjuk NO_REPLY untuk menekan pengiriman.
• Flush dijalankan sekali per siklus pemadatan (dilacak di sessions.json).
• Flush hanya dijalankan untuk sesi Pi tersemat (backend CLI melewatkannya).
• Flush dilewati ketika workspace sesi bersifat hanya-baca (workspaceAccess: "ro" atau "none").
• Lihat Memory untuk tata letak file workspace dan pola penulisan.

​

Daftar periksa pemecahan masalah

• Kunci sesi salah? Mulai dari /concepts/session dan konfirmasikan sessionKey di /status.
• Ketidakcocokan penyimpanan vs transkrip? Konfirmasikan host Gateway dan jalur penyimpanan dari openclaw status.
• Spam pemadatan? Periksa:
  • jendela konteks model (terlalu kecil)
  • pengaturan pemadatan (reserveTokens yang terlalu tinggi untuk jendela model dapat menyebabkan pemadatan lebih awal)
  • pembengkakan tool-result: aktifkan/setel pemangkasan sesi
• Giliran senyap bocor? Pastikan balasan dimulai dengan NO_REPLY (token persis yang tidak peka huruf besar-kecil) dan Anda menggunakan build yang menyertakan perbaikan penekanan streaming.