​

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

• Trasowanie sesji (jak wiadomości przychodzące są mapowane na sessionKey)
• Magazyn sesji (sessions.json) i co śledzi
• Trwałość transkryptów (*.jsonl) i ich struktura
• Higiena transkryptów (poprawki specyficzne dla dostawcy przed uruchomieniami)
• Limity kontekstu (okno kontekstu a śledzone tokeny)
• Kompaktowanie (ręczne + automatyczne kompaktowanie) oraz miejsca, w których można podpiąć działania przed kompaktowaniem
• Ciche porządki (na przykład zapisy pamięci, które nie powinny generować widocznych dla użytkownika wyników)

• /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 interfejs 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. Magazyn 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 tylko do dopisywania o strukturze drzewa (wpisy mają id + parentId)
   • Przechowuje rzeczywistą rozmowę + wywołania narzędzi + podsumowania kompaktowania
   • Jest używany do odtworzenia kontekstu modelu dla przyszłych tur

​

Lokalizacje na dysku

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

​

Utrzymanie magazynu i kontrola dysku

• mode: warn (domyślnie) albo enforce
• pruneAfter: granica wieku nieaktualnych wpisów (domyślnie 30d)
• maxEntries: limit wpisów w sessions.json (domyślnie 500)
• rotateBytes: rotacja sessions.json, gdy jest zbyt duży (domyślnie 10mb)
• resetArchiveRetention: retencja archiwów transkryptów *.reset.<timestamp> (domyślnie: taka sama jak pruneAfter; false wyłącza czyszczenie)
• maxDiskBytes: opcjonalny budżet 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 przekraczasz cel, 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 z magazynu 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łówna/czat bezpośredni (na agenta): 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.
• Reset dzienny (domyślnie o 4:00 czasu lokalnego na hoście gateway) 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 skonfigurowane są jednocześnie tryb dzienny i bezczynność, wygrywa to, które wygaśnie wcześniej.
• Strażnik rozwidlenia od rodzica wątku (session.parentForkMaxTokens, domyślnie 100000) pomija rozwidlanie z transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna od zera. Ustaw 0, aby wyłączyć.

​

Schemat magazynu 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 zasadom wysyłania)
• provider, subject, room, space, displayName: metadane do etykiet grup/kanałów
• Przełączniki:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (nadpisanie dla danej sesji)
• Wybór modelu:
  • providerOverride, modelOverride, authProfileOverride
• Liczniki tokenów (best-effort / zależne od dostawcy):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: ile razy automatyczne kompaktowanie zakończyło się dla tego klucza sesji
• memoryFlushAt: znacznik czasu ostatniego zrzutu pamięci przed kompaktowaniem
• memoryFlushCompactionCount: liczba kompaktowań w momencie ostatniego zrzutu

​

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 wstrzyknięte przez rozszerzenie, które wchodzą do kontekstu modelu (mogą być ukryte przed 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 a śledzone tokeny

1. Okno kontekstu modelu: twardy limit dla modelu (tokeny widoczne dla modelu)
2. Liczniki magazynu sesji: kroczące statystyki zapisywane w sessions.json (używane przez /status i panele)

• Okno kontekstu pochodzi z katalogu modeli (i może zostać nadpisane przez konfigurację).
• contextTokens w magazynie to wartość szacunkowa/raportowa w czasie działania; nie traktuj jej jako ścisłej gwarancji.

​

Kompaktowanie: czym jest

• Podsumowanie kompaktowania
• Wiadomości po firstKeptEntryId

​

Granice fragmentów kompaktowania i parowanie narzędzi

• Jeśli podział według udziału tokenów wypada pomiędzy wywołaniem narzędzia a jego wynikiem, OpenClaw przesuwa granicę do wiadomości asystenta z wywołaniem narzędzia, zamiast rozdzielać tę parę.
• Jeśli końcowy blok wyniku narzędzia w przeciwnym razie wypchnąłby fragment ponad zakładany cel, 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.

​

Kiedy następuje automatyczne kompaktowanie (środowisko 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) → skompaktuj → 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 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.

​

Powierzchnie widoczne dla użytkownika

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

​

Ciche porządki (NO_REPLY)

• Asystent rozpoczyna swoje wyjście od dokładnego cichego tokenu NO_REPLY / no_reply, aby wskazać „nie dostarczaj odpowiedzi użytkownikowi”.
• OpenClaw usuwa/tłumi to w warstwie dostarczania.
• Tłumienie dokładnego cichego tokenu jest nieczułe na wielkość liter, więc NO_REPLY i no_reply są uznawane, gdy cały ładunek to wyłącznie cichy token.
• Jest to przeznaczone wyłącznie dla prawdziwych tur w tle/bez dostarczenia; nie jest to skrót dla zwykłych, wykonalnych żądań użytkownika.

​

„Zrzut pamięci” przed kompaktowaniem (zaimplementowane)

1. Monitoruj użycie kontekstu sesji.
2. Gdy przekroczy „miękki próg” (poniżej progu kompaktowania Pi), uruchom cichą dyrektywę „zapisz pamięć teraz” dla agenta.
3. Użyj dokładnego cichego tokenu NO_REPLY / no_reply, aby użytkownik niczego nie zobaczył.

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

• Domyślny prompt/system prompt zawiera wskazówkę NO_REPLY, aby tłumić dostarczanie.
• Zrzut uruchamia się raz na cykl kompaktowania (śledzone w sessions.json).
• Zrzut działa tylko dla osadzonych sesji Pi (backendy CLI go pomijają).
• Zrzut jest pomijany, gdy workspace sesji jest tylko do odczytu (workspaceAccess: "ro" lub "none").
• Zobacz Pamięć, aby poznać układ plików workspace i wzorce zapisu.

​

Lista kontrolna rozwiązywania problemów

• Nieprawidłowy klucz sesji? Zacznij od /concepts/session i potwierdź sessionKey w /status.
• Niezgodność magazynu i transkryptu? Potwierdź host Gateway i ścieżkę magazynu z openclaw status.
• Spam kompaktowania? Sprawdź:
  • okno kontekstu modelu (zbyt małe)
  • ustawienia kompaktowania (reserveTokens ustawione zbyt wysoko względem okna modelu może powodować wcześniejsze kompaktowanie)
  • rozrost wyników narzędzi: włącz/dostrój przycinanie sesji
• Ciche tury przeciekają? Potwierdź, że odpowiedź zaczyna się od NO_REPLY (dokładny token, nieczuły na wielkość liter) i że używasz wersji zawierającej poprawkę tłumienia strumieniowania.