​

Oturum Yönetimi ve Sıkıştırma (Derinlemesine İnceleme)

• Oturum yönlendirme (gelen mesajların bir sessionKey ile nasıl eşlendiği)
• Oturum deposu (sessions.json) ve neyi izlediği
• Transkript kalıcılığı (*.jsonl) ve yapısı
• Transkript hijyeni (çalıştırmalar öncesinde sağlayıcıya özgü düzeltmeler)
• Bağlam sınırları (bağlam penceresi ile izlenen token’lar)
• Sıkıştırma (manuel + otomatik sıkıştırma) ve ön sıkıştırma çalışmalarının nereye bağlanacağı
• Sessiz bakım işleri (örn. kullanıcıya görünür çıktı üretmemesi gereken bellek yazımları)

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

​

Tek doğruluk kaynağı: Gateway

• UI’ler (macOS uygulaması, web Control UI, TUI) oturum listeleri ve token sayıları için Gateway’i sorgulamalıdır.
• Uzak modda, oturum dosyaları uzak ana makinededir; “yerel Mac dosyalarınızı kontrol etmek” Gateway’in kullandıklarını yansıtmaz.

​

İki kalıcılık katmanı

1. Oturum deposu (sessions.json)
   • Anahtar/değer haritası: sessionKey -> SessionEntry
   • Küçük, değiştirilebilir, düzenlemesi (veya girdileri silmesi) güvenlidir
   • Oturum meta verilerini izler (geçerli oturum kimliği, son etkinlik, anahtarlar, token sayaçları vb.)
2. Transkript (<sessionId>.jsonl)
   • Ağaç yapılı, yalnızca eklemeli transkript (girdiler id + parentId içerir)
   • Gerçek konuşmayı + araç çağrılarını + sıkıştırma özetlerini depolar
   • Gelecek turlar için model bağlamını yeniden oluşturmakta kullanılır

​

Disk üzerindeki konumlar

• Depo: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transkriptler: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram konu oturumları: .../<sessionId>-topic-<threadId>.jsonl

​

Oturum anahtarları (sessionKey)

• Ana/doğrudan sohbet (ajan başına): agent:<agentId>:<mainKey> (varsayılan main)
• Grup: agent:<agentId>:<channel>:group:<id>
• Oda/kanal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> veya ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (aksi belirtilmedikçe)

​

Oturum kimlikleri (sessionId)

• Sıfırlama (/new, /reset), bu sessionKey için yeni bir sessionId oluşturur.
• Günlük sıfırlama (Gateway ana makinesinde varsayılan yerel saatle 04:00), sıfırlama sınırından sonraki ilk mesajda yeni bir sessionId oluşturur.
• Boşta kalma süresi dolumu (session.reset.idleMinutes veya eski session.idleMinutes), boşta penceresinden sonra bir mesaj geldiğinde yeni bir sessionId oluşturur. Günlük + boşta birlikte yapılandırıldığında, önce süresi dolan kazanır.

​

Oturum deposu şeması (sessions.json)

• sessionId: geçerli transkript kimliği (dosya adı, sessionFile ayarlanmadıkça buradan türetilir)
• updatedAt: son etkinlik zaman damgası
• sessionFile: isteğe bağlı açık transkript yol geçersiz kılma
• chatType: direct | group | room (UI’lere ve gönderim politikasına yardımcı olur)
• provider, subject, room, space, displayName: grup/kanal etiketleme için meta veriler
• Anahtarlar:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (oturum başına geçersiz kılma)
• Model seçimi:
  • providerOverride, modelOverride, authProfileOverride
• Token sayaçları (en iyi çaba / sağlayıcıya bağlı):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: bu oturum anahtarı için otomatik sıkıştırmanın kaç kez tamamlandığı
• memoryFlushAt: son ön sıkıştırma bellek boşaltmasının zaman damgası
• memoryFlushCompactionCount: son boşaltmanın çalıştığı sıradaki sıkıştırma sayısı

​

Transkript yapısı (*.jsonl)

• İlk satır: oturum başlığı (type: "session"; id, cwd, timestamp, isteğe bağlı parentSession içerir)
• Sonrasında: id + parentId (ağaç) ile oturum girdileri

• message: kullanıcı/asistan/toolResult mesajları
• custom_message: modele bağlama giren uzantı tarafından enjekte edilen mesajlar (UI’den gizlenebilir)
• custom: modele bağlama girmeyen uzantı durumu
• compaction: firstKeptEntryId ve tokensBefore içeren kalıcı sıkıştırma özeti
• branch_summary: ağaç dalında gezinirken kalıcı özet

​

Bağlam pencereleri ve izlenen token’lar

1. Model bağlam penceresi: model başına katı üst sınır (modelin görebildiği token’lar)
2. Oturum deposu sayaçları: sessions.json içine yazılan döngüsel istatistikler (/status ve panolar için kullanılır)

• Bağlam penceresi, model kataloğundan gelir (ve yapılandırma ile geçersiz kılınabilir).
• Depodaki contextTokens, çalışma zamanı tahmini/raporlama değeridir; katı bir garanti olarak ele almayın.

​

Compaction: what it is

• Sıkıştırma özeti
• firstKeptEntryId’ten sonraki mesajlar

​

Otomatik sıkıştırma ne zaman olur (Pi çalışma zamanı)

1. Taşma kurtarma: model bağlam taşması hatası döndürür → sıkıştır → yeniden dene.
2. Eşik bakımı: başarılı bir turdan sonra, şu koşulda:

• contextWindow, modelin bağlam penceresidir
• reserveTokens, istemler + bir sonraki model çıktısı için ayrılan baş boşluktur

​

Sıkıştırma ayarları (reserveTokens, keepRecentTokens)

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

• compaction.reserveTokens < reserveTokensFloor ise, OpenClaw yükseltir.
• Varsayılan taban 20000 token’dır.
• Tabanı devre dışı bırakmak için agents.defaults.compaction.reserveTokensFloor: 0 ayarlayın.
• Zaten daha yüksekse, OpenClaw dokunmaz.

​

Kullanıcıya görünen yüzeyler

• /status (herhangi bir sohbet oturumunda)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Ayrıntılı mod: 🧹 Auto-compaction complete + sıkıştırma sayısı

​

Sessiz bakım işleri (NO_REPLY)

• Asistan çıktısına “kullanıcıya yanıt teslim etme” anlamına gelen NO_REPLY ile başlar.
• OpenClaw, teslim katmanında bunu ayıklar/bastırır.

​

Ön sıkıştırma “bellek boşaltma” (uygulandı)

1. Monitor session context usage.
2. “Yumuşak eşik” (Pi’nin sıkıştırma eşiğinin altında) aşıldığında, ajana sessiz bir “şimdi belleği yaz” yönergesi çalıştırır.
3. Kullanıcının hiçbir şey görmemesi için NO_REPLY kullanılır.

• enabled (varsayılan: true)
• softThresholdTokens (varsayılan: 4000)
• prompt (boşaltma turu için kullanıcı mesajı)
• systemPrompt (boşaltma turu için eklenen ekstra sistem istemi)

• Varsayılan istem/sistem istemi, teslimi bastırmak için bir NO_REPLY ipucu içerir.
• Boşaltma, her sıkıştırma döngüsünde bir kez çalışır (sessions.json’da izlenir).
• Boşaltma yalnızca gömülü Pi oturumları için çalışır (CLI arka uçları atlar).
• Oturum çalışma alanı salt okunur olduğunda boşaltma atlanır (workspaceAccess: "ro" veya "none").
• Çalışma alanı dosya düzeni ve yazma kalıpları için bkz. Memory.

​

Sorun giderme kontrol listesi

• Oturum anahtarı yanlış mı? /concepts/session ile başlayın ve /status içindeki sessionKey’ı doğrulayın.
• Depo ile transkript uyuşmazlığı mı? Gateway ana makinesini ve openclaw status’den depo yolunu doğrulayın.
• Sıkıştırma spam’i mi? Şunları kontrol edin:
  • model bağlam penceresi (çok küçük)
  • sıkıştırma ayarları (model penceresi için reserveTokens çok yüksekse daha erken sıkıştırmaya neden olabilir)
  • tool-result şişmesi: oturum budamayı etkinleştirin/ayarlayın
• Sessiz turlar sızdırıyor mu? Yanıtın NO_REPLY (tam belirteç) ile başladığını ve akış bastırma düzeltmesini içeren bir derlemede olduğunuzu doğrulayın.