Skip to main content

​
openclaw sessions

List stored conversation sessions. Session lists are not channel/provider liveness checks. They show persisted conversation rows from session stores. A quiet Discord, Slack, Telegram, or other channel can reconnect successfully without creating a new session row until a message is processed. Use openclaw channels status --probe, openclaw status --deep, or openclaw health --verbose when you need live channel connectivity.
Flags: --store accepts the documented legacy selector form, including sessions.json and suffixless custom selectors. OpenClaw resolves that selector to its physical SQLite target, verifies the target exists and is usable, and reports the physical path it actually read. openclaw sessions and the Gateway sessions.list RPC are bounded by default so large long-lived stores cannot monopolize the CLI process or Gateway event loop. The CLI returns the newest 100 sessions by default; pass --limit <n> for a smaller/larger window or --limit all when you intentionally need the full store. JSON responses include totalCount, limitApplied, and hasMore when callers need to show that more rows exist. RPC clients can pass configuredAgentsOnly: true to keep the broad combined discovery source but return only rows for agents currently present in config. Control UI uses that mode by default so deleted or disk-only agent stores do not reappear in the Sessions view. --all-agents reads configured agent stores. Gateway and ACP session discovery are broader: they also include SQLite stores resolved from configured agent roots or a templated session.store root. Legacy selector paths must resolve inside the agent root; symlinks and out-of-root paths are skipped. openclaw sessions --all-agents --json:

​
Archive sessions

Archive one or more sessions through the running Gateway:
Archive uses the same sessions.patch lifecycle operation as the Control UI. It keeps the transcript, marks the session archived, and removes the session from the default active list. For a cloud-worker session with an active placement, the Gateway first stops the worker, reconciles its workspace, and reclaims the environment. If the placement is still transitioning or failed without proof that its environment is gone, the session remains unarchived; wait for the placement to settle, then retry. Agent main sessions remain protected. Already archived sessions are successful no-ops. Use --dry-run to validate every key and preview the result without changing session state.

​
Delete sessions

Delete one or more sessions through the running Gateway:
Delete is destructive. In an interactive terminal it asks once before deleting the valid keys. Non-interactive and --json deletion requires --yes. Use --dry-run first when scripting a bulk cleanup.
Delete uses the same sessions.delete lifecycle operation as the Control UI, with transcript cleanup enabled. The Gateway removes the live session row, transcript generations, session-owned runtime state, bindings, boards, and other lifecycle artifacts. For ordinary sessions it retains the transcript as a verified .jsonl.deleted.<timestamp> archive; incognito transcripts are removed without an archive. If a managed worktree cannot be removed safely, the command reports the preserved branch and path for manual cleanup. Both lifecycle commands:
  • accept multiple keys and report one ordered result per key;
  • use --agent <id> to select the owning agent, which is required for a global key outside the default agent;
  • support --url, --token, --password, and --timeout <ms> Gateway connection overrides;
  • return a non-zero exit when any key is unknown or any operation fails, while still processing the other valid keys;
  • emit one stable JSON envelope with ok, operation, dryRun, and results when --json is set.
Example mixed-result JSON:

​
Tail trajectory progress

openclaw sessions tail renders recent runtime trajectory events as compact progress lines. Without --session-key, it tails running sessions first, then the latest stored session. --tail <count> controls how many existing events print before follow mode; default 80, and 0 starts at the current end. --follow keeps watching the selected SQLite-backed session or an explicit legacy trajectory file. The progress view is intentionally conservative: prompt text, tool arguments, and tool result bodies are not printed. Tool calls show the tool name with {...redacted...}; tool results show status such as ok, error, or done; model completion lines show provider/model and terminal status.

​
Export a trajectory bundle

This is the command path used by the /export-trajectory slash command after the owner approves the exec request. The output directory is always resolved inside .openclaw/trajectory-exports/ under the selected workspace.

​
Cleanup maintenance

Run maintenance now instead of waiting for the next write cycle:
openclaw sessions cleanup uses session.maintenance settings from config (Configuration reference):
  • Scope note: openclaw sessions cleanup maintains session stores, transcripts, trajectory rows, and legacy trajectory sidecars. It does not prune cron run history. Task maintenance retains terminal cron history for 7 days (lost rows for 24 hours) and enforces the newest 2000 rows per job and history class as an additional ceiling (Task maintenance, Cron configuration).
  • Cleanup also prunes unreferenced legacy/archive transcript artifacts, compaction checkpoints, and trajectory sidecars older than session.maintenance.pruneAfter; artifacts still referenced by SQLite session rows are preserved.
  • Cleanup reports short-lived Gateway model-run probe cleanup separately as modelRunPruned. This only matches strict explicit keys shaped like agent:*:explicit:model-run-<uuid>. Retention is a fixed 24h and is pressure-gated: it only removes stale probe rows when session-entry maintenance/cap pressure is reached. When it runs, model-run cleanup happens before global stale cleanup and capping.
  • maxEntries caps the total live session row count. Protected rows are reported as keep and count toward the cap, but they are never automatic eviction targets. If protected rows prevent cleanup from reaching the cap, the store remains above it. --enforce does not remove that protection; unarchive, unpin, wait for active work to finish, or explicitly delete sessions you no longer want to retain.
Flags: When a Gateway is reachable, non-dry-run cleanup for configured agent stores is sent through the Gateway so it shares the same session-store writer as runtime traffic. Use --store <path> for explicit offline repair of a legacy store selector. openclaw sessions cleanup --all-agents --dry-run --json:

​
Compact a session

Reclaim context budget for a wedged or oversized session. openclaw sessions compact <key> is the first-class wrapper around the sessions.compact Gateway RPC and requires a running Gateway.
  • Without --max-lines, the Gateway LLM-summarizes the transcript. The CLI does not impose a client deadline by default; the Gateway owns the configured compaction lifecycle.
  • With --max-lines <n>, it permanently truncates the SQLite transcript to the last n lines. This path does not create a backup archive.
  • --agent <id>: agent that owns the session; required for global keys.
  • --url / --token / --password: Gateway connection overrides.
  • --timeout <ms>: optional client-side RPC timeout in milliseconds.
  • --json: print the raw RPC payload.
The command exits non-zero when the Gateway reports a failed compaction or is unreachable, so crons and scripts never mistake a silent no-op for success.
openclaw agent --message '/compact ...' is not a compaction path. Slash commands from the CLI are rejected by the authorized-sender check; that invocation exits non-zero with guidance pointing here instead of silently no-opping.

​
sessions.compact RPC

openclaw gateway call sessions.compact --params '<json>' accepts: Example LLM-summarize response:
Example truncate response (--max-lines 200):