OpenClaw mengelola sesi secara menyeluruh di area berikut:Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
- Perutean sesi (cara pesan masuk dipetakan ke
sessionKey) - Penyimpanan sesi (
sessions.json) dan apa yang dilacaknya - Persistensi transkrip (
*.jsonl) dan strukturnya - Kebersihan transkrip (perbaikan khusus penyedia sebelum run)
- Batas konteks (jendela konteks vs token yang dilacak)
- Compaction (manual dan auto-compaction) dan tempat mengaitkan pekerjaan pra-compaction
- Pemeliharaan senyap (penulisan memori yang tidak boleh menghasilkan keluaran yang terlihat pengguna)
Sumber kebenaran: Gateway
OpenClaw dirancang di sekitar satu proses Gateway yang memiliki status sesi.- UI (aplikasi macOS, UI Kontrol web, TUI) harus meminta daftar sesi dan jumlah token dari Gateway.
- Dalam mode jarak jauh, file sesi berada di host jarak jauh; “memeriksa file Mac lokal Anda” tidak akan mencerminkan apa yang digunakan Gateway.
Dua lapisan persistensi
OpenClaw mempertahankan sesi dalam dua lapisan:-
Penyimpanan sesi (
sessions.json)- Peta kunci/nilai:
sessionKey -> SessionEntry - Kecil, dapat diubah, aman untuk diedit (atau menghapus entri)
- Melacak metadata sesi (id sesi saat ini, aktivitas terakhir, toggle, penghitung token, dll.)
- Peta kunci/nilai:
-
Transkrip (
<sessionId>.jsonl)- Transkrip append-only dengan struktur pohon (entri memiliki
id+parentId) - Menyimpan percakapan aktual + panggilan alat + ringkasan compaction
- Digunakan untuk membangun ulang konteks model untuk giliran berikutnya
- Checkpoint debug pra-compaction besar dilewati setelah transkrip aktif
melampaui batas ukuran checkpoint, sehingga menghindari salinan
.checkpoint.*.jsonlraksasa kedua.
- Transkrip append-only dengan struktur pohon (entri memiliki
mtimeMs/size dan dibagikan di antara pembaca konkuren.
Lokasi di disk
Per agen, pada host Gateway:- Penyimpanan:
~/.openclaw/agents/<agentId>/sessions/sessions.json - Transkrip:
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl- Sesi topik Telegram:
.../<sessionId>-topic-<threadId>.jsonl
- Sesi topik Telegram:
src/config/sessions.ts.
Pemeliharaan penyimpanan dan kontrol disk
Persistensi sesi memiliki kontrol pemeliharaan otomatis (session.maintenance) untuk sessions.json, artefak transkrip, dan sidecar trajectory:
mode:warn(default) atauenforcepruneAfter: batas usia entri usang (default30d)maxEntries: batas entri dalamsessions.json(default500)resetArchiveRetention: retensi untuk arsip transkrip*.reset.<timestamp>(default: sama sepertipruneAfter;falsemenonaktifkan pembersihan)maxDiskBytes: anggaran direktori sesi opsionalhighWaterBytes: target opsional setelah pembersihan (default80%darimaxDiskBytes)
sessions.json besar tidak dikloning atau dibaca ulang untuk setiap pembaruan metadata. Kode runtime sebaiknya memilih updateSessionStore(...) atau updateSessionStoreEntry(...); penyimpanan seluruh store langsung adalah alat kompatibilitas dan pemeliharaan offline. Saat Gateway dapat dijangkau, openclaw sessions cleanup dan openclaw agents delete non-dry-run mendelegasikan mutasi store ke Gateway sehingga pembersihan bergabung dengan antrean penulis yang sama; --store <path> adalah jalur perbaikan offline eksplisit untuk pemeliharaan file langsung. Pembersihan maxEntries tetap dibatch untuk batas berukuran produksi, sehingga store dapat sebentar melampaui batas terkonfigurasi sebelum pembersihan high-water berikutnya menulis ulangnya kembali ke bawah. Pembacaan store sesi tidak memangkas atau membatasi entri selama startup Gateway; gunakan penulisan atau openclaw sessions cleanup --enforce untuk pembersihan. openclaw sessions cleanup --enforce tetap menerapkan batas terkonfigurasi segera dan memangkas artefak transkrip, checkpoint, dan trajectory lama yang tidak direferensikan bahkan ketika tidak ada anggaran disk yang dikonfigurasi.
Pemeliharaan mempertahankan pointer percakapan eksternal yang tahan lama seperti sesi grup
dan sesi chat berlingkup thread, tetapi entri runtime sintetis untuk cron, hook,
heartbeat, ACP, dan sub-agen tetap dapat dihapus ketika melampaui
usia, jumlah, atau anggaran disk yang dikonfigurasi.
OpenClaw tidak lagi membuat cadangan rotasi sessions.json.bak.* otomatis selama penulisan Gateway. Kunci lama session.maintenance.rotateBytes diabaikan dan openclaw doctor --fix menghapusnya dari konfigurasi lama.
Mutasi transkrip memakai write lock sesi pada file transkrip. Akuisisi lock menunggu hingga
session.writeLock.acquireTimeoutMs sebelum memunculkan galat sesi sibuk; defaultnya adalah 60000
md. Naikkan ini hanya ketika pekerjaan prep, pembersihan, compaction, atau mirror transkrip yang sah bersaing
lebih lama pada mesin lambat. Deteksi lock usang dan peringatan maksimum penahanan tetap menjadi kebijakan terpisah.
Urutan penegakan untuk pembersihan anggaran disk (mode: "enforce"):
- Hapus artefak arsip, transkrip yatim, atau trajectory yatim tertua terlebih dahulu.
- Jika masih di atas target, keluarkan entri sesi tertua dan file transkrip/trajectory-nya.
- Teruskan hingga penggunaan berada pada atau di bawah
highWaterBytes.
mode: "warn", OpenClaw melaporkan potensi pengeluaran tetapi tidak memutasi store/file.
Jalankan pemeliharaan sesuai permintaan:
Sesi Cron dan log run
Run cron terisolasi juga membuat entri sesi/transkrip, dan memiliki kontrol retensi khusus:cron.sessionRetention(default24h) memangkas sesi run cron terisolasi lama dari store sesi (falsemenonaktifkan).cron.runLog.maxBytes+cron.runLog.keepLinesmemangkas file~/.openclaw/cron/runs/<jobId>.jsonl(default:2_000_000byte dan2000baris).
cron:<jobId> sebelumnya sebelum menulis baris baru. Ia membawa preferensi aman
seperti pengaturan thinking/fast/verbose, label, dan override model/auth yang
dipilih pengguna secara eksplisit. Ia membuang konteks percakapan sekitar seperti
perutean channel/grup, kebijakan kirim atau antre, elevasi, asal, dan pengikatan runtime
ACP sehingga run terisolasi baru tidak dapat mewarisi pengiriman usang atau
otoritas runtime dari run lama.
Kunci sesi (sessionKey)
sessionKey mengidentifikasi bucket percakapan mana yang Anda masuki (perutean + isolasi).
Pola umum:
- Chat utama/langsung (per agen):
agent:<agentId>:<mainKey>(defaultmain) - Grup:
agent:<agentId>:<channel>:group:<id> - Ruang/channel (Discord/Slack):
agent:<agentId>:<channel>:channel:<id>atau...:room:<id> - Cron:
cron:<job.id> - Webhook:
hook:<uuid>(kecuali dioverride)
ID sesi (sessionId)
Setiap sessionKey menunjuk ke sessionId saat ini (file transkrip yang melanjutkan percakapan).
Pedoman umum:
- Reset (
/new,/reset) membuatsessionIdbaru untuksessionKeytersebut. - Reset harian (default pukul 4:00 pagi waktu lokal pada host gateway) membuat
sessionIdbaru pada pesan berikutnya setelah batas reset. - Kedaluwarsa idle (
session.reset.idleMinutesatau legacysession.idleMinutes) membuatsessionIdbaru ketika pesan tiba setelah jendela idle. Ketika harian + idle sama-sama dikonfigurasi, yang kedaluwarsa lebih dulu menang. - Peristiwa sistem (heartbeat, wakeup cron, notifikasi exec, pembukuan gateway) dapat memutasi baris sesi tetapi tidak memperpanjang kesegaran reset harian/idle. Rollover reset membuang pemberitahuan peristiwa sistem yang diantrekan untuk sesi sebelumnya sebelum prompt segar dibangun.
- Kebijakan fork induk menggunakan cabang aktif PI saat membuat thread atau fork subagen. Jika cabang itu terlalu besar, OpenClaw memulai child dengan konteks terisolasi alih-alih gagal atau mewarisi riwayat yang tidak dapat digunakan. Kebijakan ukuran bersifat otomatis; konfigurasi legacy
session.parentForkMaxTokensdihapus olehopenclaw doctor --fix.
initSessionState() dalam src/auto-reply/reply/session.ts.
Skema store sesi (sessions.json)
Tipe nilai store adalah SessionEntry dalam src/config/sessions.ts.
Bidang kunci (tidak lengkap):
sessionId: id transkrip saat ini (nama file diturunkan dari ini kecualisessionFileditetapkan)sessionStartedAt: timestamp mulai untuksessionIdsaat ini; kesegaran reset harian menggunakan ini. Baris legacy dapat menurunkannya dari header sesi JSONL.lastInteractionAt: timestamp interaksi pengguna/channel nyata terakhir; kesegaran reset idle menggunakan ini sehingga peristiwa heartbeat, cron, dan exec tidak menjaga sesi tetap hidup. Baris legacy tanpa bidang ini fallback ke waktu mulai sesi yang dipulihkan untuk kesegaran idle.updatedAt: timestamp mutasi baris store terakhir, digunakan untuk listing, pemangkasan, dan pembukuan. Ini bukan otoritas untuk kesegaran reset harian/idle.sessionFile: override jalur transkrip eksplisit opsionalchatType:direct | group | room(membantu UI dan kebijakan kirim)provider,subject,room,space,displayName: metadata untuk pelabelan grup/channel- Toggle:
thinkingLevel,verboseLevel,reasoningLevel,elevatedLevelsendPolicy(override per sesi)
- Pemilihan model:
providerOverride,modelOverride,authProfileOverride
- Penghitung token (best-effort / bergantung penyedia):
inputTokens,outputTokens,totalTokens,contextTokens
compactionCount: seberapa sering auto-compaction selesai untuk kunci sesi inimemoryFlushAt: timestamp untuk flush memori pra-compaction terakhirmemoryFlushCompactionCount: jumlah compaction ketika flush terakhir berjalan
Struktur transkrip (*.jsonl)
Transkrip dikelola oleh SessionManager dari @earendil-works/pi-coding-agent.
File tersebut adalah JSONL:
- Baris pertama: header sesi (
type: "session", menyertakanid,cwd,timestamp, opsionalparentSession) - Lalu: entri sesi dengan
id+parentId(pohon)
message: pesan pengguna/asisten/toolResultcustom_message: pesan yang diinjeksi ekstensi yang memang masuk ke konteks model (dapat disembunyikan dari UI)custom: status ekstensi yang tidak masuk ke konteks modelcompaction: ringkasan compaction yang dipertahankan denganfirstKeptEntryIddantokensBeforebranch_summary: ringkasan yang dipertahankan saat menavigasi cabang pohon
SessionManager untuk membaca/menulisnya.
Jendela konteks vs token yang dilacak
Dua konsep berbeda penting:- Jendela konteks model: batas keras per model (token yang terlihat oleh model)
- Penghitung store sesi: statistik bergulir yang ditulis ke
sessions.json(digunakan untuk /status dan dasbor)
- Jendela konteks berasal dari katalog model (dan dapat dioverride melalui konfigurasi).
contextTokensdalam store adalah nilai estimasi/pelaporan runtime; jangan perlakukan sebagai jaminan ketat.
Compaction: apa itu
Compaction meringkas percakapan lama ke dalam entricompaction yang dipertahankan dalam transkrip dan menjaga pesan terbaru tetap utuh.
Setelah compaction, giliran mendatang melihat:
- Ringkasan compaction
- Pesan setelah
firstKeptEntryId
Batas chunk Compaction dan pemasangan alat
Saat OpenClaw membagi transkrip panjang menjadi chunk compaction, OpenClaw menjaga panggilan alat asisten tetap dipasangkan dengan entritoolResult yang sesuai.
- Jika pembagian berbasis porsi token jatuh di antara panggilan alat dan hasilnya, OpenClaw menggeser batas ke pesan panggilan alat asisten alih-alih memisahkan pasangan tersebut.
- Jika blok hasil alat di akhir seharusnya mendorong chunk melewati target, OpenClaw mempertahankan blok alat yang tertunda itu dan menjaga ekor yang belum diringkas tetap utuh.
- Blok panggilan alat yang dibatalkan/galat tidak membuat pembagian tertunda tetap terbuka.
Kapan auto-compaction terjadi (runtime Pi)
Di agen Pi tertanam, auto-compaction dipicu dalam dua kasus:- Pemulihan overflow: model mengembalikan galat 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 berbentuk penyedia) → compact → coba lagi. - Pemeliharaan ambang batas: setelah giliran berhasil, ketika:
contextTokens > contextWindow - reserveTokens
Di mana:
contextWindowadalah jendela konteks modelreserveTokensadalah ruang cadangan yang disisihkan untuk prompt + keluaran model berikutnya
agents.defaults.compaction.maxActiveTranscriptBytes ditetapkan dan file
transkrip aktif mencapai ukuran tersebut. Ini adalah pengaman ukuran file untuk biaya
pembukaan ulang lokal, bukan pengarsipan mentah: OpenClaw tetap menjalankan compaction semantik normal,
dan memerlukan truncateAfterCompaction agar ringkasan yang sudah di-compact dapat menjadi
transkrip penerus baru.
Untuk run Pi tertanam, agents.defaults.compaction.midTurnPrecheck.enabled: true
menambahkan pengaman loop alat opsional. Setelah hasil alat ditambahkan dan sebelum
panggilan model berikutnya, OpenClaw memperkirakan tekanan prompt menggunakan logika anggaran
prapemeriksaan yang sama seperti saat awal giliran. Jika konteks tidak lagi muat, pengaman
tidak melakukan compact di dalam hook transformContext milik Pi. Pengaman menaikkan sinyal
prapemeriksaan tengah giliran terstruktur, menghentikan pengiriman prompt saat ini, dan membiarkan
loop run luar menggunakan jalur pemulihan yang ada: memotong hasil alat yang terlalu besar
jika itu cukup, atau memicu mode compaction yang dikonfigurasi dan mencoba lagi. Opsi ini
dinonaktifkan secara default dan bekerja dengan mode compaction default maupun safeguard,
termasuk compaction safeguard yang didukung penyedia.
Ini independen dari maxActiveTranscriptBytes: pengaman ukuran byte berjalan
sebelum giliran dibuka, sedangkan prapemeriksaan tengah giliran berjalan kemudian dalam loop alat Pi tertanam
setelah hasil alat baru ditambahkan.
Pengaturan Compaction (reserveTokens, keepRecentTokens)
Pengaturan compaction Pi berada di pengaturan Pi:
- Jika
compaction.reserveTokens < reserveTokensFloor, OpenClaw menaikkannya. - Batas bawah default adalah
20000token. - Tetapkan
agents.defaults.compaction.reserveTokensFloor: 0untuk menonaktifkan batas bawah. - Jika sudah lebih tinggi, OpenClaw membiarkannya.
/compactmanual menghormatiagents.defaults.compaction.keepRecentTokensyang eksplisit dan mempertahankan titik potong ekor terbaru Pi. Tanpa anggaran simpan eksplisit, compaction manual tetap menjadi checkpoint keras dan konteks yang dibangun ulang dimulai dari ringkasan baru.- Tetapkan
agents.defaults.compaction.midTurnPrecheck.enabled: trueuntuk menjalankan prapemeriksaan loop alat opsional setelah hasil alat baru dan sebelum panggilan model berikutnya. Ini hanya pemicu; pembuatan ringkasan tetap menggunakan jalur compaction yang dikonfigurasi. Ini independen darimaxActiveTranscriptBytes, yang merupakan pengaman ukuran byte transkrip aktif pada awal giliran. - Tetapkan
agents.defaults.compaction.maxActiveTranscriptByteske nilai byte atau string seperti"20mb"untuk menjalankan compaction lokal sebelum giliran saat transkrip aktif menjadi besar. Pengaman ini aktif hanya ketikatruncateAfterCompactionjuga diaktifkan. Biarkan tidak ditetapkan atau tetapkan0untuk menonaktifkan. - Ketika
agents.defaults.compaction.truncateAfterCompactiondiaktifkan, OpenClaw merotasi transkrip aktif ke JSONL penerus yang sudah di-compact setelah compaction. Transkrip penuh lama tetap diarsipkan dan ditautkan dari checkpoint compaction alih-alih ditulis ulang di tempat.
ensurePiCompactionReserveTokens() di src/agents/pi-settings.ts
(dipanggil dari src/agents/pi-embedded-runner.ts).
Penyedia compaction yang dapat dipasang
Plugin dapat mendaftarkan penyedia compaction melaluiregisterCompactionProvider() pada API plugin. Ketika agents.defaults.compaction.provider ditetapkan ke id penyedia yang terdaftar, ekstensi safeguard mendelegasikan peringkasan ke penyedia tersebut alih-alih pipeline summarizeInStages bawaan.
provider: id Plugin penyedia compaction terdaftar. Biarkan tidak ditetapkan untuk peringkasan LLM default.- Menetapkan
providermemaksamode: "safeguard". - Penyedia menerima instruksi compaction dan kebijakan pelestarian pengenal yang sama dengan jalur bawaan.
- Safeguard tetap mempertahankan konteks sufiks giliran terbaru dan giliran terbelah setelah keluaran penyedia.
- Peringkasan safeguard bawaan mendistilasi ulang ringkasan sebelumnya dengan pesan baru alih-alih mempertahankan seluruh ringkasan sebelumnya secara verbatim.
- Mode safeguard mengaktifkan audit kualitas ringkasan secara default; tetapkan
qualityGuard.enabled: falseuntuk melewati perilaku coba lagi saat keluaran cacat. - Jika penyedia gagal atau mengembalikan hasil kosong, OpenClaw otomatis kembali ke peringkasan LLM bawaan.
- Sinyal pembatalan/timeout dilempar ulang (tidak ditelan) untuk menghormati pembatalan pemanggil.
src/plugins/compaction-provider.ts, src/agents/pi-hooks/compaction-safeguard.ts.
Permukaan yang terlihat oleh pengguna
Anda dapat mengamati compaction dan status sesi melalui:/status(di sesi chat apa pun)openclaw status(CLI)openclaw sessions/sessions --json- Log Gateway (
pnpm gateway:watchatauopenclaw logs --follow):embedded run auto-compaction start+complete - Mode verbose:
🧹 Auto-compaction complete+ jumlah compaction
Housekeeping senyap (NO_REPLY)
OpenClaw mendukung giliran “senyap” untuk tugas latar belakang ketika pengguna tidak boleh melihat keluaran perantara.
Konvensi:
- Asisten memulai keluarannya dengan token senyap persis
NO_REPLY/no_replyuntuk menunjukkan “jangan kirim balasan kepada pengguna”. - OpenClaw menghapus/menekan ini di lapisan pengiriman.
- Penekanan token senyap persis tidak peka huruf besar-kecil, sehingga
NO_REPLYdanno_replykeduanya dihitung ketika seluruh payload hanyalah token senyap. - Ini hanya untuk giliran latar belakang/tanpa pengiriman yang sebenarnya; ini bukan pintasan untuk permintaan pengguna biasa yang dapat ditindaklanjuti.
2026.1.10, OpenClaw juga menekan streaming draf/mengetik ketika
chunk parsial dimulai dengan NO_REPLY, sehingga operasi senyap tidak membocorkan keluaran parsial
di tengah giliran.
”Memory flush” pra-compaction (diimplementasikan)
Tujuan: sebelum auto-compaction terjadi, jalankan giliran agentic senyap yang menulis state tahan lama ke disk (misalnyamemory/YYYY-MM-DD.md di workspace agen) agar compaction tidak dapat
menghapus konteks penting.
OpenClaw menggunakan pendekatan flush pra-ambang batas:
- Pantau penggunaan konteks sesi.
- Saat melewati “ambang batas lunak” (di bawah ambang compaction Pi), jalankan direktif senyap “tulis memori sekarang” ke agen.
- Gunakan token senyap persis
NO_REPLY/no_replysehingga pengguna tidak melihat apa pun.
agents.defaults.compaction.memoryFlush):
enabled(default:true)model(override penyedia/model persis opsional untuk giliran flush, misalnyaollama/qwen3:8b)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_REPLYuntuk menekan pengiriman. - Ketika
modelditetapkan, giliran flush menggunakan model tersebut tanpa mewarisi rantai fallback sesi aktif, sehingga housekeeping khusus lokal tidak diam-diam fallback ke model percakapan berbayar. - Flush berjalan sekali per siklus compaction (dilacak di
sessions.json). - Flush hanya berjalan untuk sesi Pi tertanam (backend CLI melewatinya).
- Flush dilewati ketika workspace sesi bersifat baca-saja (
workspaceAccess: "ro"atau"none"). - Lihat Memori untuk tata letak file workspace dan pola penulisan.
session_before_compact di API ekstensi, tetapi logika
flush OpenClaw saat ini berada di sisi Gateway.
Daftar periksa pemecahan masalah
- Kunci sesi salah? Mulai dengan /concepts/session dan konfirmasi
sessionKeydi/status. - Store vs transkrip tidak cocok? Konfirmasi host Gateway dan jalur store dari
openclaw status. - Spam compaction? Periksa:
- jendela konteks model (terlalu kecil)
- pengaturan compaction (
reserveTokensterlalu tinggi untuk jendela model dapat menyebabkan compaction lebih awal) - pembengkakan hasil alat: aktifkan/sesuaikan pemangkasan sesi
- Giliran senyap bocor? Konfirmasi balasan dimulai dengan
NO_REPLY(token persis tidak peka huruf besar-kecil) dan Anda berada pada build yang menyertakan perbaikan penekanan streaming.