​

Zarządzanie sesjami i kompaktowanie (szczegółowe omówienie)

• Routowanie sesji (jak wiadomości przychodzące mapują się na sessionKey)
• Store sesji (sessions.json) i co śledzi
• Trwałość transkryptu (*.jsonl) i jego struktura
• Higiena transkryptu (poprawki specyficzne dla dostawcy przed uruchomieniami)
• Limity kontekstu (okno kontekstu vs śledzone tokeny)
• Kompaktowanie (ręczne + automatyczne kompaktowanie) i gdzie podpiąć pracę wykonywaną przed kompaktowaniem
• Ciche porządki (np. zapisy do pamięci, które nie powinny generować widocznego dla użytkownika wyjścia)

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

​

Źródło prawdy: Gateway

• Interfejsy użytkownika (aplikacja macOS, webowy Control UI, TUI) powinny odpytywać Gateway o listy sesji i liczniki tokenów.
• W trybie zdalnym pliki sesji znajdują się na zdalnym hoście; „sprawdzanie lokalnych plików na Macu” nie odzwierciedli tego, czego używa Gateway.

​

Dwie warstwy trwałości

1. Store sesji (sessions.json)
   • Mapa klucz/wartość: sessionKey -> SessionEntry
   • Mały, mutowalny, bezpieczny do edycji (lub usuwania wpisów)
   • Śledzi metadane sesji (bieżący identyfikator sesji, ostatnią aktywność, przełączniki, liczniki tokenów itd.)
2. Transkrypt (<sessionId>.jsonl)
   • Transkrypt typu append-only o strukturze drzewa (wpisy mają id + parentId)
   • Przechowuje właściwą konwersację + wywołania narzędzi + podsumowania kompaktowania
   • Służy do odbudowy kontekstu modelu dla przyszłych tur

​

Lokalizacje na dysku

• Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transkrypty: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Sesje tematów Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Utrzymanie store i kontrola dysku

• mode: warn (domyślnie) lub enforce
• pruneAfter: próg wieku dla starych wpisów (domyślnie 30d)
• maxEntries: limit wpisów w sessions.json (domyślnie 500)
• rotateBytes: rotacja sessions.json, gdy plik jest zbyt duży (domyślnie 10mb)
• resetArchiveRetention: retencja dla archiwów transkryptów *.reset.<timestamp> (domyślnie: taka sama jak pruneAfter; false wyłącza czyszczenie)
• maxDiskBytes: opcjonalny limit budżetu katalogu sesji
• highWaterBytes: opcjonalny cel po czyszczeniu (domyślnie 80% z maxDiskBytes)

1. Najpierw usuń najstarsze zarchiwizowane lub osierocone artefakty transkryptów.
2. Jeśli nadal jest powyżej celu, usuń najstarsze wpisy sesji i ich pliki transkryptów.
3. Kontynuuj, aż użycie spadnie do highWaterBytes lub niżej.

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

​

Sesje cron i logi uruchomień

• cron.sessionRetention (domyślnie 24h) usuwa stare sesje izolowanych uruchomień cron ze store sesji (false wyłącza).
• cron.runLog.maxBytes + cron.runLog.keepLines przycinają pliki ~/.openclaw/cron/runs/<jobId>.jsonl (domyślnie: 2_000_000 bajtów i 2000 linii).

​

Klucze sesji (sessionKey)

• Główny/bezpośredni czat (per agent): agent:<agentId>:<mainKey> (domyślnie main)
• Grupa: agent:<agentId>:<channel>:group:<id>
• Pokój/kanał (Discord/Slack): agent:<agentId>:<channel>:channel:<id> lub ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (chyba że nadpisano)

​

Identyfikatory sesji (sessionId)

• Reset (/new, /reset) tworzy nowy sessionId dla tego sessionKey.
• Codzienny reset (domyślnie o 4:00 czasu lokalnego na hoście gatewaya) tworzy nowy sessionId przy następnej wiadomości po przekroczeniu granicy resetu.
• Wygaśnięcie bezczynności (session.reset.idleMinutes lub starsze session.idleMinutes) tworzy nowy sessionId, gdy wiadomość nadejdzie po oknie bezczynności. Gdy skonfigurowano jednocześnie reset dzienny i bezczynność, wygrywa ten, który wygaśnie wcześniej.
• Zabezpieczenie przed rozwidleniem z rodzica dla wątków (session.parentForkMaxTokens, domyślnie 100000) pomija forking transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna się od zera. Ustaw 0, aby wyłączyć.

​

Schemat store sesji (sessions.json)

• sessionId: bieżący identyfikator transkryptu (nazwa pliku jest z niego wyprowadzana, chyba że ustawiono sessionFile)
• updatedAt: znacznik czasu ostatniej aktywności
• sessionFile: opcjonalne jawne nadpisanie ścieżki transkryptu
• chatType: direct | group | room (pomaga interfejsom użytkownika i polityce wysyłania)
• provider, subject, room, space, displayName: metadane do etykietowania grup/kanałów
• Przełączniki:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (nadpisanie per sesja)
• Wybór modelu:
  • providerOverride, modelOverride, authProfileOverride
• Liczniki tokenów (best-effort / zależne od dostawcy):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: jak często auto-kompaktowanie zakończyło się dla tego klucza sesji
• memoryFlushAt: znacznik czasu ostatniego opróżnienia pamięci przed kompaktowaniem
• memoryFlushCompactionCount: licznik kompaktowań, przy którym uruchomiono ostatnie opróżnienie

​

Struktura transkryptu (*.jsonl)

• Pierwsza linia: nagłówek sesji (type: "session", zawiera id, cwd, timestamp, opcjonalnie parentSession)
• Następnie: wpisy sesji z id + parentId (drzewo)

• message: wiadomości użytkownika/asystenta/toolResult
• custom_message: wiadomości wstrzykiwane przez rozszerzenie, które wchodzą do kontekstu modelu (mogą być ukryte w UI)
• custom: stan rozszerzenia, który nie wchodzi do kontekstu modelu
• compaction: zapisane podsumowanie kompaktowania z firstKeptEntryId i tokensBefore
• branch_summary: zapisane podsumowanie przy nawigacji po gałęzi drzewa

​

Okna kontekstu vs śledzone tokeny

1. Okno kontekstu modelu: twardy limit per model (tokeny widoczne dla modelu)
2. Liczniki store sesji: statystyki kroczące zapisywane do sessions.json (używane przez /status i dashboardy)

• Okno kontekstu pochodzi z katalogu modeli (i może być nadpisane przez konfigurację).
• contextTokens w store to wartość szacunkowa/raportowana przez runtime; nie traktuj jej jako ścisłej gwarancji.

​

Kompaktowanie: czym jest

• Podsumowanie kompaktowania
• Wiadomości po firstKeptEntryId

​

Granice chunków kompaktowania i parowanie narzędzi

• Jeśli podział według udziału tokenów wypada między wywołaniem narzędzia a jego wynikiem, OpenClaw przesuwa granicę do wiadomości asystenta z wywołaniem narzędzia zamiast rozdzielać parę.
• Jeśli końcowy blok z wynikiem narzędzia w przeciwnym razie przekroczyłby docelowy rozmiar chunku, OpenClaw zachowuje ten oczekujący blok narzędzia i pozostawia niepodsumowany ogon bez zmian.
• Przerwane/błędne bloki wywołań narzędzi nie utrzymują oczekującego podziału otwartego.

​

Kiedy następuje auto-kompaktowanie (runtime Pi)

1. Odzyskiwanie po przepełnieniu: model zwraca błąd przepełnienia kontekstu (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 oraz podobne warianty zależne od dostawcy) → kompaktuj → ponów próbę.
2. Utrzymanie progu: po udanej turze, gdy:

• contextWindow to okno kontekstu modelu
• reserveTokens to zapas zarezerwowany na prompty + następne wyjście modelu

​

Ustawienia kompaktowania (reserveTokens, keepRecentTokens)

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

• Jeśli compaction.reserveTokens < reserveTokensFloor, OpenClaw go podnosi.
• Domyślny próg minimalny to 20000 tokenów.
• Ustaw agents.defaults.compaction.reserveTokensFloor: 0, aby wyłączyć ten próg.
• Jeśli wartość jest już wyższa, OpenClaw pozostawia ją bez zmian.

​

Wymienni dostawcy kompaktowania

• provider: identyfikator zarejestrowanej wtyczki dostawcy kompaktowania. Pozostaw nieustawione dla domyślnego podsumowywania przez LLM.
• Ustawienie provider wymusza mode: "safeguard".
• Dostawcy otrzymują te same instrukcje kompaktowania i politykę zachowywania identyfikatorów co ścieżka wbudowana.
• Safeguard nadal zachowuje kontekst ostatnich tur i końcówki podzielonej tury po wyjściu dostawcy.
• Jeśli dostawca zawiedzie lub zwróci pusty wynik, OpenClaw automatycznie wraca do wbudowanego podsumowywania przez LLM.
• Sygnały przerwania/timeoutu są ponownie rzucane (nie są przechwytywane), aby respektować anulowanie przez wywołującego.

​

Powierzchnie widoczne dla użytkownika

• /status (w dowolnej sesji czatu)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Tryb szczegółowy: 🧹 Auto-compaction complete + liczba kompaktowań

​

Ciche porządki (NO_REPLY)

• Asystent rozpoczyna wyjście od dokładnego cichego tokena NO_REPLY / no_reply, aby wskazać „nie dostarczaj odpowiedzi użytkownikowi”.
• OpenClaw usuwa/tłumi to w warstwie dostarczania.
• Tłumienie dokładnego cichego tokena nie rozróżnia wielkości liter, więc NO_REPLY i no_reply liczą się tak samo, gdy cały ładunek to tylko ten cichy token.
• Służy to wyłącznie do prawdziwych tur działających w tle / bez dostarczenia; nie jest to skrót dla zwykłych, wymagających działania żądań użytkownika.

​

„Opróżnianie pamięci” przed kompaktowaniem (zaimplementowane)

1. Monitoruje użycie kontekstu sesji.
2. Gdy przekroczy ono „miękki próg” (poniżej progu kompaktowania Pi), uruchamia cichą dyrektywę „zapisz pamięć teraz” do agenta.
3. Używa dokładnego cichego tokena NO_REPLY / no_reply, aby użytkownik niczego nie widział.

• enabled (domyślnie: true)
• softThresholdTokens (domyślnie: 4000)
• prompt (wiadomość użytkownika dla tury opróżniania)
• systemPrompt (dodatkowy prompt systemowy dołączany dla tury opróżniania)

• Domyślny prompt/system prompt zawierają wskazówkę NO_REPLY, aby tłumić dostarczanie.
• Opróżnianie uruchamia się raz na cykl kompaktowania (śledzone w sessions.json).
• Opróżnianie działa tylko dla sesji osadzonego Pi (backendy CLI je pomijają).
• Opróżnianie jest pomijane, gdy obszar roboczy sesji jest tylko do odczytu (workspaceAccess: "ro" lub "none").
• Zobacz Pamięć, aby poznać układ plików obszaru roboczego i wzorce zapisu.

​

Lista kontrolna rozwiązywania problemów

• Nieprawidłowy klucz sesji? Zacznij od /concepts/session i potwierdź sessionKey w /status.
• Niezgodność store i transkryptu? Potwierdź host Gateway i ścieżkę store z openclaw status.
• Spam kompaktowania? Sprawdź:
  • okno kontekstu modelu (za małe)
  • ustawienia kompaktowania (reserveTokens zbyt wysokie względem okna modelu mogą powodować wcześniejsze kompaktowanie)
  • nadmiar toolResult: włącz/dostrój przycinanie sesji
• Wyciekają ciche tury? Potwierdź, że odpowiedź zaczyna się od NO_REPLY (dokładny token, bez rozróżniania wielkości liter) i że używasz kompilacji zawierającej poprawkę tłumienia streamingu.