​

Sessiebeheer & Compactie (Diepgaande uitleg)

• Sessierouting (hoe inkomende berichten worden toegewezen aan een sessionKey)
• Sessiestore (sessions.json) en wat deze bijhoudt
• Transcriptpersistentie (*.jsonl) en de structuur ervan
• Transcript-hygiëne (provider-specifieke correcties vóór runs)
• Contextlimieten (contextvenster versus bijgehouden tokens)
• Compactie (handmatige + auto-compactie) en waar je pre-compactiewerk kunt inhaken
• Stille huishoudtaken (bijv. geheugenschrijvingen die geen voor de gebruiker zichtbare uitvoer mogen produceren)

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

​

Bron van waarheid: de Gateway

• UI’s (macOS-app, web Control UI, TUI) moeten de Gateway raadplegen voor sessielijsten en tokentellingen.
• In remote-modus staan sessiebestanden op de externe host; “je lokale Mac-bestanden controleren” weerspiegelt niet wat de Gateway gebruikt.

​

Twee persistentielagen

1. Sessiestore (sessions.json)
   • Sleutel/waarde-map: sessionKey -> SessionEntry
   • Klein, muteerbaar, veilig om te bewerken (of items te verwijderen)
   • Houdt sessiemetadata bij (huidige sessie-id, laatste activiteit, toggles, tokentellers, enz.)
2. Transcript (<sessionId>.jsonl)
   • Alleen-aanvulbaar transcript met boomstructuur (items hebben id + parentId)
   • Slaat het daadwerkelijke gesprek + tool-aanroepen + compactiesamenvattingen op
   • Wordt gebruikt om de modelcontext voor toekomstige beurten opnieuw op te bouwen

​

Locaties op schijf

• Opslag: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcripties: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram-topic-sessies: .../<sessionId>-topic-<threadId>.jsonl

​

Sessiesleutels (sessionKey)

• Hoofd/direct chat (per agent): agent:<agentId>:<mainKey> (standaard main)
• Groep: agent:<agentId>:<channel>:group:<id>
• Kamer/kanaal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> of ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (tenzij overschreven)

​

Sessie-id’s (sessionId)

• Reset (/new, /reset) maakt een nieuwe sessionId voor die sessionKey.
• Dagelijkse reset (standaard 4:00 uur lokale tijd op de Gateway-host) maakt een nieuwe sessionId bij het eerstvolgende bericht na de resetgrens.
• Inactiviteitsverval (session.reset.idleMinutes of legacy session.idleMinutes) maakt een nieuwe sessionId wanneer een bericht arriveert na het inactiviteitsvenster. Als dagelijkse + inactiviteit beide zijn geconfigureerd, wint degene die het eerst verloopt.

​

Schema van de sessiestore (sessions.json)

• sessionId: huidige transcript-id (bestandsnaam wordt hiervan afgeleid tenzij sessionFile is ingesteld)
• updatedAt: tijdstempel van laatste activiteit
• sessionFile: optionele expliciete overschrijving van het transcriptpad
• chatType: direct | group | room (helpt UI’s en verzendbeleid)
• provider, subject, room, space, displayName: metadata voor groeps-/kanaallabeling
• Toggles:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (per-sessie-overschrijving)
• Modelselectie:
  • providerOverride, modelOverride, authProfileOverride
• Tokentellers (best-effort / provider-afhankelijk):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: hoe vaak auto-compactie voor deze sessiesleutel is voltooid
• memoryFlushAt: tijdstempel van de laatste pre-compactie geheugen-flush
• memoryFlushCompactionCount: compactietelling toen de laatste flush draaide

​

Transcriptstructuur (*.jsonl)

• Eerste regel: sessieheader (type: "session", bevat id, cwd, timestamp, optioneel parentSession)
• Daarna: sessie-items met id + parentId (boom)

• message: user/assistant/toolResult-berichten
• custom_message: door extensies geïnjecteerde berichten die wel de modelcontext ingaan (kunnen verborgen zijn voor de UI)
• custom: extensiestatus die niet de modelcontext ingaat
• compaction: persistente compactiesamenvatting met firstKeptEntryId en tokensBefore
• branch_summary: persistente samenvatting bij het navigeren van een boomtak

​

Contextvensters versus bijgehouden tokens

1. Modelcontextvenster: harde limiet per model (tokens zichtbaar voor het model)
2. Sessiestore-tellers: rollende statistieken die in sessions.json worden geschreven (gebruikt voor /status en dashboards)

• Het contextvenster komt uit de modelcatalogus (en kan via config worden overschreven).
• contextTokens in de store is een runtime-schatting/rapportagewaarde; behandel dit niet als een strikte garantie.

​

Compactie: wat het is

• De compactiesamenvatting
• Berichten na firstKeptEntryId

​

Wanneer auto-compactie plaatsvindt (Pi-runtime)

1. Overflow-herstel: het model retourneert een context-overflowfout → compacteren → opnieuw proberen.
2. Drempelonderhoud: na een succesvolle beurt, wanneer:

• contextWindow het contextvenster van het model is
• reserveTokens gereserveerde ruimte is voor prompts + de volgende modeluitvoer

​

Compactie-instellingen (reserveTokens, keepRecentTokens)

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

• Als compaction.reserveTokens < reserveTokensFloor, verhoogt OpenClaw dit.
• Standaardvloer is 20000 tokens.
• Stel agents.defaults.compaction.reserveTokensFloor: 0 in om de vloer uit te schakelen.
• Als deze al hoger is, laat OpenClaw het ongemoeid.

​

Voor de gebruiker zichtbare oppervlakken

• /status (in elke chatsessie)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Verbose-modus: 🧹 Auto-compaction complete + compactietelling

​

Stille huishoudtaken (NO_REPLY)

• De assistant begint zijn uitvoer met NO_REPLY om aan te geven “geen antwoord aan de gebruiker afleveren”.
• OpenClaw stript/onderdrukt dit in de afleverlaag.

​

Pre-compactie “geheugen-flush” (geïmplementeerd)

1. Monitor sessiecontextgebruik.
2. Wanneer dit een “zachte drempel” overschrijdt (onder Pi’s compactiedrempel), voer een stille “schrijf nu geheugen”-instructie uit naar de agent.
3. Gebruik NO_REPLY zodat de gebruiker niets ziet.

• enabled (standaard: true)
• softThresholdTokens (standaard: 4000)
• prompt (gebruikersbericht voor de flush-beurt)
• systemPrompt (extra systeemprompt die voor de flush-beurt wordt toegevoegd)

• De standaardprompt/systeemprompt bevat een NO_REPLY-hint om aflevering te onderdrukken.
• De flush draait eenmaal per compactiecyclus (bijgehouden in sessions.json).
• De flush draait alleen voor ingebedde Pi-sessies (CLI-backends slaan dit over).
• De flush wordt overgeslagen wanneer de sessiewerkruimte alleen-lezen is (workspaceAccess: "ro" of "none").
• Zie Memory voor de indeling van werkruimtebestanden en schrijfpatronen.

​

Checklist voor problemen oplossen

• Sessiesleutel onjuist? Begin met /concepts/session en bevestig de sessionKey in /status.
• Store- versus transcript-mismatch? Bevestig de Gateway-host en het store-pad uit openclaw status.
• Compactiespam? Controleer:
  • modelcontextvenster (te klein)
  • compactie-instellingen (reserveTokens te hoog voor het modelvenster kan eerdere compactie veroorzaken)
  • tool-result-bloat: schakel sessie-pruning in of stel het af
• Lekken stille beurten? Bevestig dat het antwoord begint met NO_REPLY (exact token) en dat je op een build zit die de streaming-onderdrukkingsfix bevat.