​

Sessionshantering och kompaktering (fördjupning)

• Sessionsroutning (hur inkommande meddelanden mappar till en sessionKey)
• Sessionslagring (sessions.json) och vad den spårar
• Persistens av transkript (*.jsonl) och dess struktur
• Transkripthygien (leverantörsspecifika korrigeringar före körningar)
• Kontextgränser (kontextfönster vs spårade tokens)
• Kompaktering (manuell + automatisk kompaktering) och var man kan haka in arbete före kompaktering
• Tyst städning (t.ex. minnesskrivningar som inte ska ge användarsynlig utdata)

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

​

Sanningskälla: Gateway

• UI:er (macOS-app, webbaserat Control UI, TUI) ska fråga Gateway om sessionslistor och tokenräkningar.
• I fjärrläge ligger sessionsfilerna på fjärrvärden; att ”kontrollera dina lokala Mac-filer” återspeglar inte vad Gateway använder.

​

Två persistenslager

1. Sessionslagring (sessions.json)
   • Nyckel/värde-karta: sessionKey -> SessionEntry
   • Liten, muterbar, säker att redigera (eller radera poster)
   • Spårar sessionsmetadata (aktuellt sessions-id, senaste aktivitet, växlar, tokenräknare m.m.)
2. Transkript (<sessionId>.jsonl)
   • Append-only-transkript med trädstruktur (poster har id + parentId)
   • Lagrar den faktiska konversationen + verktygsanrop + kompakteringssammanfattningar
   • Används för att bygga upp modellkontexten för framtida vändor

​

Platser på disk

• Lagring: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transkript: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram-ämnessessioner: .../<sessionId>-topic-<threadId>.jsonl

​

Sessionsnycklar (sessionKey)

• Huvud-/direktchatt (per agent): agent:<agentId>:<mainKey> (standard main)
• Grupp: agent:<agentId>:<channel>:group:<id>
• Rum/kanal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> eller ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (om inte åsidosatt)

​

Sessions-id:n (sessionId)

• Återställning (/new, /reset) skapar ett nytt sessionId för den sessionKey.
• Daglig återställning (standard 04:00 lokal tid på Gateway-värden) skapar ett nytt sessionId vid nästa meddelande efter återställningsgränsen.
• Idle utgång (session.reset.idleMinutes eller äldre session.idleMinutes) skapar en ny sessionId när ett meddelande kommer efter tomgångsfönstret. När dagligen + inaktiv är båda konfigurerade, vilket som löper ut första vinner.

​

Schema för sessionslagring (sessions.json)

• sessionId: aktuellt transkript-id (filnamn härleds från detta om inte sessionFile är satt)
• updatedAt: tidsstämpel för senaste aktivitet
• sessionFile: valfri explicit åsidosättning av transkriptsökväg
• chatType: direct | group | room (hjälper UI:er och sändpolicy)
• provider, subject, room, space, displayName: metadata för grupp-/kanaletikettering
• Växlar:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (åsidosättning per session)
• Modellval:
  • providerOverride, modelOverride, authProfileOverride
• Tokenräknare (best-effort / leverantörsberoende):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: hur ofta automatisk kompaktering har slutförts för denna sessionsnyckel
• memoryFlushAt: tidsstämpel för senaste pre-kompakterings-minnesflush
• memoryFlushCompactionCount: kompakteringsräkning när senaste flush kördes

​

Transkriptstruktur (*.jsonl)

• Första raden: sessionshuvud (type: "session", inkluderar id, cwd, timestamp, valfri parentSession)
• Därefter: sessionsposter med id + parentId (träd)

• message: användar-/assistent-/toolResult-meddelanden
• custom_message: tilläggsinjicerade meddelanden som kommer in i modellkontext (kan döljas från UI)
• custom: tilläggstillstånd som inte kommer in i modellkontext
• compaction: persisterad kompakteringssammanfattning med firstKeptEntryId och tokensBefore
• branch_summary: persisterad sammanfattning vid navigering av en trädgren

​

Kontextfönster vs spårade tokens

1. Modellens kontextfönster: hård gräns per modell (tokens synliga för modellen)
2. Räknare i sessionslagringen: rullande statistik som skrivs till sessions.json (används för /status och dashboards)

• Kontextfönstret kommer från modellkatalogen (och kan åsidosättas via konfig).
• contextTokens i lagringen är ett körtidsestimat/rapporteringsvärde; behandla det inte som en strikt garanti.

​

Kompaktering: vad det är

• Kompakteringssammanfattningen
• Meddelanden efter firstKeptEntryId

​

När automatisk kompaktering sker (Pi runtime)

1. Återhämtning vid överskridande: modellen returnerar ett fel om kontextöverskridande → kompakta → försök igen.
2. Tröskelunderhåll: efter en lyckad vända, när:

• contextWindow är modellens kontextfönster
• reserveTokens är marginal reserverad för promptar + nästa modellutdata

​

Inställningar för kompaktering (reserveTokens, keepRecentTokens)

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

• Om compaction.reserveTokens < reserveTokensFloor, höjer OpenClaw det.
• Standardgolvet är 20000 tokens.
• Sätt agents.defaults.compaction.reserveTokensFloor: 0 för att inaktivera golvet.
• Om det redan är högre lämnar OpenClaw det orört.

​

Användarsynliga ytor

• /status (i valfri chattsession)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Utförligt läge: 🧹 Auto-compaction complete + kompakteringsräkning

​

Tyst städning (NO_REPLY)

• Assistenten inleder sin utdata med NO_REPLY för att indikera ”leverera inget svar till användaren”.
• OpenClaw strimlar/undertrycker detta i leveranslagret.

​

”Minnesflush” före kompaktering (implementerad)

1. Övervaka sessionens kontextanvändning.
2. När den passerar en ”mjuk tröskel” (under Pis kompakteringströskel), kör en tyst ”skriv minne nu”-direktiv till agenten.
3. Använd NO_REPLY så att användaren inte ser något.

• enabled (standard: true)
• softThresholdTokens (standard: 4000)
• prompt (användarmeddelande för flush-vändan)
• systemPrompt (extra systemprompt som läggs till för flush-vändan)

• Standardprompt/systemprompt innehåller en NO_REPLY-hint för att undertrycka leverans.
• Flush körs en gång per kompakteringscykel (spåras i sessions.json).
• Flush körs endast för inbäddade Pi-sessioner (CLI-backends hoppar över den).
• Flush hoppas över när sessionens arbetsyta är skrivskyddad (workspaceAccess: "ro" eller "none").
• Se Memory för arbetsytans fillayout och skrivmönster.

​

Felsökningschecklista

• Sessionsnyckel fel? Börja med /concepts/session och bekräfta sessionKey i /status.
• Lagra vs utskrift felaktigt? Bekräfta Gateway-värden och butikssökvägen från openclaw status.
• Komprimering skräppost? Kontroll:
  • modellens kontextfönster (för litet)
  • kompakteringsinställningar (reserveTokens för högt i förhållande till modellfönstret kan orsaka tidigare kompaktering)
  • uppblåst tool-result: aktivera/justera session pruning
• Tysta svängar läckande? Bekräfta svaret börjar med NO_REPLY (exakt token) och du är på en byggnad som inkluderar strömmande dämpning fix.