Use this file to discover all available pages before exploring further.
Session management deep dive
OpenClaw manages sessions end-to-end across these areas:
- Session routing (how inbound messages map to a )
- Session store () and what it tracks
- Transcript persistence () and its structure
- Transcript hygiene (provider-specific fixups before runs)
- Context limits (context window vs tracked tokens)
- Compaction (manual and auto-compaction) and where to hook pre-compaction work
- Silent housekeeping (memory writes that should not produce user-visible output)
If you want a higher-level overview first, start with:
Source of truth: the Gateway
OpenClaw is designed around a single Gateway process that owns session state.
- UIs (macOS app, web Control UI, TUI) should query the Gateway for session lists and token counts.
- In remote mode, session files are on the remote host; “checking your local Mac files” won’t reflect what the Gateway is using.
Two persistence layers
OpenClaw persists sessions in two layers:
-
Session store ()
- Key/value map:
sessionKey -> SessionEntry
- Small, mutable, safe to edit (or delete entries)
- Tracks session metadata (current session id, last activity, toggles, token counters, etc.)
-
Transcript ()
- Append-only transcript with tree structure (entries have + )
- Stores the actual conversation + tool calls + compaction summaries
- Used to rebuild the model context for future turns
- Large pre-compaction debug checkpoints are skipped once the active
transcript exceeds the checkpoint size cap, avoiding a second giant
copy.
On-disk locations
Per agent, on the Gateway host:
- Store:
~/.openclaw/agents/<agentId>/sessions/sessions.json
- Transcripts:
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
- Telegram topic sessions:
.../<sessionId>-topic-<threadId>.jsonl
OpenClaw resolves these via
.
Store maintenance and disk controls
Session persistence has automatic maintenance controls (
) for
, transcript artifacts, and trajectory sidecars:
- : (default) or
- : stale-entry age cutoff (default )
- : cap entries in (default )
- : retention for transcript archives (default: same as ; disables cleanup)
- : optional sessions-directory budget
- : optional target after cleanup (default of )
Normal Gateway writes batch
cleanup for production-sized caps, so a store may briefly exceed the configured cap before the next high-water cleanup rewrites it back down.
openclaw sessions cleanup --enforce
still applies the configured cap immediately.
OpenClaw no longer creates automatic
rotation backups during Gateway writes. The legacy
session.maintenance.rotateBytes
key is ignored and
removes it from older configs.
Enforcement order for disk budget cleanup (
):
- Remove oldest archived, orphan transcript, or orphan trajectory artifacts first.
- If still above the target, evict oldest session entries and their transcript/trajectory files.
- Keep going until usage is at or below .
In
, OpenClaw reports potential evictions but does not mutate the store/files.
Run maintenance on demand:
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce
Cron sessions and run logs
Isolated cron runs also create session entries/transcripts, and they have dedicated retention controls:
- (default ) prunes old isolated cron run sessions from the session store ( disables).
- + prune
~/.openclaw/cron/runs/<jobId>.jsonl
When cron force-creates a new isolated run session, it sanitizes the previous
session entry before writing the new row. It carries safe
preferences such as thinking/fast/verbose settings, labels, and explicit
user-selected model/auth overrides. It drops ambient conversation context such
as channel/group routing, send or queue policy, elevation, origin, and ACP
runtime binding so a fresh isolated run cannot inherit stale delivery or
runtime authority from an older run.
Session keys ()
A
identifies
which conversation bucket you’re in (routing + isolation).
Common patterns:
- Main/direct chat (per agent):
agent:<agentId>:<mainKey>
- Group:
agent:<agentId>:<channel>:group:<id>
- Room/channel (Discord/Slack):
agent:<agentId>:<channel>:channel:<id>
- Cron:
- Webhook: (unless overridden)
The canonical rules are documented at /concepts/session.
Session ids ()
Each
points at a current
(the transcript file that continues the conversation).
Rules of thumb:
- Reset (, ) creates a new for that .
- Daily reset (default 4:00 AM local time on the gateway host) creates a new on the next message after the reset boundary.
- Idle expiry (
session.reset.idleMinutes
- System events (heartbeat, cron wakeups, exec notifications, gateway bookkeeping) may mutate the session row but do not extend daily/idle reset freshness. Reset rollover discards queued system-event notices for the previous session before the fresh prompt is built.
- Thread parent fork guard (
session.parentForkMaxTokens
Implementation detail: the decision happens in
in
src/auto-reply/reply/session.ts
.
Session store schema ()
The store’s value type is
in
.
Key fields (not exhaustive):
- : current transcript id (filename is derived from this unless is set)
- : start timestamp for the current ; daily reset
freshness uses this. Legacy rows may derive it from the JSONL session header.
- : last real user/channel interaction timestamp; idle reset
freshness uses this so heartbeat, cron, and exec events do not keep sessions
alive. Legacy rows without this field fall back to the recovered session start
time for idle freshness.
- : last store-row mutation timestamp, used for listing, pruning, and
bookkeeping. It is not the authority for daily/idle reset freshness.
- : optional explicit transcript path override
- : (helps UIs and send policy)
- , , , , : metadata for group/channel labeling
- Toggles:
- , , ,
- (per-session override)
- Model selection:
- Token counters (best-effort / provider-dependent):
- : how often auto-compaction completed for this session key
- : timestamp for the last pre-compaction memory flush
memoryFlushCompactionCount
The store is safe to edit, but the Gateway is the authority: it may rewrite or rehydrate entries as sessions run.
Transcript structure ()
Transcripts are managed by
@mariozechner/pi-coding-agent
’s
.
The file is JSONL:
- First line: session header (, includes , , , optional )
- Then: session entries with + (tree)
Notable entry types:
- : user/assistant/toolResult messages
- : extension-injected messages that do enter model context (can be hidden from UI)
- : extension state that does not enter model context
- : persisted compaction summary with and
- : persisted summary when navigating a tree branch
OpenClaw intentionally does not “fix up” transcripts; the Gateway uses
to read/write them.
Context windows vs tracked tokens
Two different concepts matter:
- Model context window: hard cap per model (tokens visible to the model)
- Session store counters: rolling stats written into (used for /status and dashboards)
If you’re tuning limits:
- The context window comes from the model catalog (and can be overridden via config).
- in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.
For more, see /token-use.
Compaction: what it is
Compaction summarizes older conversation into a persisted
entry in the transcript and keeps recent messages intact.
After compaction, future turns see:
- The compaction summary
- Messages after
Compaction is persistent (unlike session pruning). See /concepts/session-pruning.
Compaction chunk boundaries and tool pairing
When OpenClaw splits a long transcript into compaction chunks, it keeps
assistant tool calls paired with their matching
entries.
- If the token-share split lands between a tool call and its result, OpenClaw
shifts the boundary to the assistant tool-call message instead of separating
the pair.
- If a trailing tool-result block would otherwise push the chunk over target,
OpenClaw preserves that pending tool block and keeps the unsummarized tail
intact.
- Aborted/error tool-call blocks do not hold a pending split open.
When auto-compaction happens (Pi runtime)
In the embedded Pi agent, auto-compaction triggers in two cases:
- Overflow recovery: the model returns a context overflow error
(, ,
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
- Threshold maintenance: after a successful turn, when:
contextTokens > contextWindow - reserveTokens
Where:
- is the model’s context window
- is headroom reserved for prompts + the next model output
These are Pi runtime semantics (OpenClaw consumes the events, but Pi decides when to compact).
OpenClaw can also trigger a preflight local compaction before opening the next
run when
agents.defaults.compaction.maxActiveTranscriptBytes
is set and the
active transcript file reaches that size. This is a file-size guard for local
reopen cost, not raw archival: OpenClaw still runs normal semantic compaction,
and it requires
so the compacted summary can become a
new successor transcript.
For embedded Pi runs,
agents.defaults.compaction.midTurnPrecheck.enabled: true
adds an opt-in tool-loop guard. After a tool result is appended and before the
next model call, OpenClaw estimates the prompt pressure using the same preflight
budget logic used at turn start. If the context no longer fits, the guard does
not compact inside Pi's
hook. It raises a structured
mid-turn precheck signal, stops the current prompt submission, and lets the
outer run loop use the existing recovery path: truncate oversized tool results
when that is enough, or trigger the configured compaction mode and retry. The
option is disabled by default and works with both
and
compaction modes, including provider-backed safeguard compaction.
This is independent of
: the byte-size guard runs
before a turn opens, while mid-turn precheck runs later in the embedded Pi tool
loop after new tool results have been appended.
Compaction settings (, )
Pi’s compaction settings live in Pi settings:
{
compaction: {
enabled: true,
reserveTokens: 16384,
keepRecentTokens: 20000,
},
}
OpenClaw also enforces a safety floor for embedded runs:
- If
compaction.reserveTokens < reserveTokensFloor
- Default floor is tokens.
- Set
agents.defaults.compaction.reserveTokensFloor: 0
- If it’s already higher, OpenClaw leaves it alone.
- Manual honors an explicit
agents.defaults.compaction.keepRecentTokens
- Set
agents.defaults.compaction.midTurnPrecheck.enabled: true
- Set
agents.defaults.compaction.maxActiveTranscriptBytes
- When
agents.defaults.compaction.truncateAfterCompaction
Why: leave enough headroom for multi-turn “housekeeping” (like memory writes) before compaction becomes unavoidable.
Implementation:
ensurePiCompactionReserveTokens()
in
src/agents/pi-settings.ts
(called from
src/agents/pi-embedded-runner.ts
).
Pluggable compaction providers
Plugins can register a compaction provider via
registerCompactionProvider()
on the plugin API. When
agents.defaults.compaction.provider
is set to a registered provider id, the safeguard extension delegates summarization to that provider instead of the built-in
pipeline.
- : id of a registered compaction provider plugin. Leave unset for default LLM summarization.
- Setting a forces .
- Providers receive the same compaction instructions and identifier-preservation policy as the built-in path.
- The safeguard still preserves recent-turn and split-turn suffix context after provider output.
- Built-in safeguard summarization re-distills prior summaries with new messages
instead of preserving the full previous summary verbatim.
- Safeguard mode enables summary quality audits by default; set
qualityGuard.enabled: false
- If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization automatically.
- Abort/timeout signals are re-thrown (not swallowed) to respect caller cancellation.
Source:
src/plugins/compaction-provider.ts
,
src/agents/pi-hooks/compaction-safeguard.ts
.
User-visible surfaces
You can observe compaction and session state via:
- (in any chat session)
- (CLI)
- /
- Verbose mode:
🧹 Auto-compaction complete
Silent housekeeping ()
OpenClaw supports “silent” turns for background tasks where the user should not see intermediate output.
Convention:
- The assistant starts its output with the exact silent token /
to indicate “do not deliver a reply to the user”.
- OpenClaw strips/suppresses this in the delivery layer.
- Exact silent-token suppression is case-insensitive, so and
both count when the whole payload is just the silent token.
- This is for true background/no-delivery turns only; it is not a shortcut for
ordinary actionable user requests.
As of
, OpenClaw also suppresses
draft/typing streaming when a
partial chunk begins with
, so silent operations don’t leak partial
output mid-turn.
Pre-compaction "memory flush" (implemented)
Goal: before auto-compaction happens, run a silent agentic turn that writes durable
state to disk (e.g.
in the agent workspace) so compaction can’t
erase critical context.
OpenClaw uses the pre-threshold flush approach:
- Monitor session context usage.
- When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent
“write memory now” directive to the agent.
- Use the exact silent token / so the user sees
nothing.
Config (
agents.defaults.compaction.memoryFlush
):
- (default: )
- (optional exact provider/model override for the flush turn, for example )
- (default: )
- (user message for the flush turn)
- (extra system prompt appended for the flush turn)
Notes:
- The default prompt/system prompt include a hint to suppress
delivery.
- When is set, the flush turn uses that model without inheriting the
active session fallback chain, so local-only housekeeping does not silently
fall back to a paid conversation model.
- The flush runs once per compaction cycle (tracked in ).
- The flush runs only for embedded Pi sessions (CLI backends skip it).
- The flush is skipped when the session workspace is read-only ( or ).
- See Memory for the workspace file layout and write patterns.
Pi also exposes a
hook in the extension API, but OpenClaw’s
flush logic lives on the Gateway side today.
Troubleshooting checklist
- Session key wrong? Start with /concepts/session and confirm the in .
- Store vs transcript mismatch? Confirm the Gateway host and the store path from .
- Compaction spam? Check:
- model context window (too small)
- compaction settings ( too high for the model window can cause earlier compaction)
- tool-result bloat: enable/tune session pruning
- Silent turns leaking? Confirm the reply starts with (case-insensitive exact token) and you’re on a build that includes the streaming suppression fix.
Related