OpenClaw Sessions: Inspect, Isolate, Compact, and Clean Up Context

One host produced two very different session counts during this review. A visibility-bounded query returned three conversations and warned that it could see only the current session tree. A cleanup dry run examined 173 stored rows. It proposed deleting none of them, yet still found 421 unreferenced artifacts representing 313,057,446 bytes of potential reclamation. None of those figures contradicts the others. They describe different layers.

That distinction is the useful way to think about OpenClaw sessions. A route chooses a conversation bucket. A session ID identifies the current transcript behind that route. Compaction bounds what the model must carry forward. Maintenance controls old rows and support artifacts. Reset, compact, clean up, and delete are therefore not increasingly aggressive versions of the same button.

The same symptom can point to four state layers

“This conversation is too large” sounds precise, but it can mean at least four things. The model context may be near its limit. The active transcript may contain stale turns. The store may contain old session rows. Or the archive directory may contain files that are no longer referenced by a live row. Each diagnosis has a different owner and a different safe remedy.

OpenClaw’s current runtime owns session rows and transcript events in the per-agent SQLite database on the Gateway host. Archived and legacy support files live alongside that store. A Control UI on a laptop is only a client; a plausible local file is not evidence about a remote Gateway.

The practical consequence is slightly uncomfortable: before taking action, name the contract that failed. If a message reached the wrong person’s context, investigate the route. If recent details disappear under context pressure, inspect compaction. If disk use grows, preview maintenance. If a product needs a fresh conversation, reset. Treating all four as “session cleanup” is how recoverable incidents become data-loss incidents.

Testing a bounded session list

The sessions CLI lists persisted conversation rows; it does not probe Telegram, Discord, Slack, or another transport. A healthy but quiet channel may have no recent row. Conversely, a recent row says nothing about whether the channel can accept a new message now.

openclaw sessions --active 1440 --limit 25 --json

Bound the query first. The CLI defaults to the newest 100 sessions so a long-lived store cannot monopolize the process or Gateway event loop. Its JSON includes total count, applied limit, and whether more rows exist. A caller that ignores hasMore can turn a partial view into a confident but false inventory.

The tool-level query used for this review added another boundary: tree visibility. It returned three rows and explicitly warned that conversations outside the current session tree could be omitted. That was enough to inspect the active work and its children. It was not enough to claim that the agent owned only three sessions.

Scope changes the answer.

Session evidence is often sensitive even when messages are omitted. Keys reveal topology; timestamps reveal activity; provider and model fields reveal deployment choices. Keep raw JSON private, extract only the counts needed for the decision, and do not paste an all-agent inventory into a support ticket.

Route keys are privacy controls, not database labels

OpenClaw routes sources differently. Groups are isolated per group, rooms per room, cron work per run, and webhooks per hook. Direct messages share the main session by default because that is convenient for a single-owner personal agent. It is unsafe when unrelated people can message the same agent privately.

For multi-user private access, per-channel-peer is the conservative general setting: channel and sender both participate in the key. per-account-channel-peer adds account isolation where one provider has several accounts. per-peer deliberately follows the same person across channels. Identity links can join verified identities without weakening the boundary for everyone else.

{
  session: {
    dmScope: "per-channel-peer"
  }
}

Changing DM scope is a product and privacy migration, not a tidy-up. Test with two non-sensitive identities, verify that they receive different keys, and confirm that neither can recall the other’s local transcript. If an older isolated scheme left stale peer-keyed rows after returning to main, preview --fix-dm-scope before enforcing it.

Failure modes: choosing the wrong operation

The operations are easiest to remember by what survives them.

Automatic resets are opt-in. With no reset policy, the session ID continues while compaction manages context. Daily reset freshness is based on when the current session began. Idle reset freshness follows the last real user or channel interaction; cron wakes, heartbeats, exec notifications, and bookkeeping writes do not keep it alive.

A reset is not a storage purge. Current OpenClaw keeps historical SQLite session and transcript state under maintenance and disk-budget rules. That history can remain searchable even after the live key advances to a new session ID. Operators who reset repeatedly to reclaim disk are changing user-visible continuity without necessarily solving the storage problem.

The dry run exposed a second ledger

The read-only maintenance preview is the strongest artifact in this review:

openclaw sessions cleanup --dry-run --json

It inspected 173 rows. The projected row count remained 173: zero stale rows pruned, zero cap removals, zero missing-row repairs, and zero DM-scope retirements. A quick glance at beforeCount and afterCount would suggest that maintenance had nothing to do.

But the same report identified 421 unreferenced artifacts older than the configured cutoff. Their potential reclamation was 313,057,446 bytes—about 298.6 MiB. The report therefore set wouldMutate to true even though the row count did not move.

This is why the preview must be read as a set of categories, not a single total. Session rows, transcript rows, reset and delete archives, checkpoints, trajectory sidecars, and legacy artifacts can have different reference and retention status. Physical SQLite and WAL bytes add another dimension when a disk budget is configured.

Counts are not contracts.

No enforcement was run. A dry-run result is evidence for a proposed change, not standing authority to apply it later. Before enforcement, compare the scope, active key protections, maintenance mode, age cutoff, entry cap, and disk policy with the approved preview. If any changed, preview again.

Compaction is continuity work

The active session used in this review reported roughly 147,000 of 220,000 context tokens and three completed compactions. It was still routable and carrying the current task. That snapshot demonstrates the intended relationship: compaction can manage a long conversation without replacing its route or pretending the transcript never existed.

openclaw sessions compact "<verified-session-key>" --json

Without --max-lines, the Gateway summarizes according to the configured compaction lifecycle. With --max-lines N, it keeps a deterministic tail and archives the previous transcript. The second mode is easier to reason about during an emergency, but it discards more conversational detail. Neither should be triggered merely because a store contains many rows.

Validate compaction in two directions. The RPC must report success, and the conversation must still answer a narrow question that depends on recent context. A lower token number alone is a poor success criterion. If the agent has forgotten the active decision, the mechanical operation succeeded while the user-facing continuity contract failed.

Continuity is the success condition.

Trajectory tailing is useful here because it shows progress events without printing prompt text, tool arguments, or result bodies. It can answer “is this run moving?” more safely than dumping the transcript. Even redacted trajectory data still reveals timestamps, tool names, and topology, so keep it bounded and private.

Common issues that deserve separate diagnoses

The list is empty, but messages still arrive

Treat that as a scope or persistence question first. Confirm the agent, activity window, applied limit, and visibility mode. Use a channel probe for transport health. Sending cleanup commands will not make a quiet channel appear in a persisted-session query.

Two private users share details

Stop multi-user ingress and compare their routing keys. Inspect session.dmScope and identity links. Move to peer isolation, test with synthetic messages, and only then reopen access. Resetting both conversations can hide the evidence while leaving the routing flaw intact.

The conversation forgets recent decisions

Check compaction events, context usage, and whether deterministic truncation was used. Restore authoritative facts from approved source artifacts or durable memory; do not paste a complete private archive back into the model context.

Disk use grows while row counts stay flat

Inspect the artifact and physical-byte sections of the maintenance preview. The result from this review is a concrete example: 173 rows stayed 173 while nearly 299 MiB of unreferenced files remained reclaimable.

The local store disagrees with production

Session state belongs to the Gateway host and service user. Confirm the remote target and agent. Current releases use per-agent SQLite for live runtime state; legacy JSON is migration or offline-repair input, not a second authority.

The result must answer the original incident

1. State the failure in user terms. Wrong recipient, lost continuity, context pressure, stale rows, and disk pressure are different incidents.
2. Identify the owner. Route and lifecycle belong to the Gateway; channel liveness belongs to the transport; stored artifacts belong to maintenance policy.
3. Take a bounded view. Select one agent, an activity window, and a limit. Preserve the visibility warning and hasMore result.
4. Choose the narrow operation. Reset for a fresh conversation, compact for context pressure, cleanup for retention, and deletion only for an explicit removal decision.
5. Preview every maintenance scope. Read row actions, artifact actions, and physical-byte projections—not only the before/after count.
6. Verify the original contract. Send a controlled message through the real route, test recent continuity after compaction, or remeasure disk after cleanup.

The skeptical operator’s rule is simple: a session command is not successful because it returned zero or because a count got smaller. It is successful when the intended privacy, continuity, routing, or storage contract is measurably healthier and the other three remain intact.

If you want a managed runtime rather than owning these session boundaries and retention decisions yourself, deploy an AI agent on GolemWorkers. For the adjacent persistence layers, read OpenClaw memory search, OpenClaw multi-agent setup, and the OpenClaw security audit.

Primary evidence behind this teardown

• OpenClaw Sessions CLI — bounded listing, trajectory tail and export, cleanup dry-run, compaction, and terminal behavior.
• OpenClaw session management — routing, DM scope, reset lifecycle, storage, maintenance, and inspection boundaries.
• OpenClaw session management deep dive — SQLite persistence, retained history, archives, disk controls, and Gateway-owned writer paths.