openclaw sessions CLI Reference: List Stored Conversation Sessions

openclaw sessions

Display saved conversation sessions.

Session lists do not verify whether a channel or provider is currently active. They show stored conversation entries from session databases. A quiet Discord, Slack, Telegram, or similar channel can reconnect without generating a new session entry until a message is handled. To check live channel connectivity, use openclaw channels status --probe, openclaw status --deep, or openclaw health --verbose.

openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --store ./tmp/sessions.json
openclaw sessions --json

Flags:

openclaw sessions and the Gateway sessions.list RPC have default limits so that large, long-lived stores cannot monopolize the CLI process or Gateway event loop. By default the CLI returns the 100 most recent sessions; supply --limit <n> for a different window size or --limit all when you need the entire store. JSON responses include totalCount, limitApplied, and hasMore so callers can indicate that additional rows exist.

RPC clients can provide configuredAgentsOnly: true to keep the wide combined discovery source while returning only rows for agents currently listed in configuration. Control UI uses this mode by default, preventing deleted or disk-only agent stores from reappearing in the Sessions view.

--all-agents reads configured agent stores. Gateway and ACP session discovery are broader: they also include SQLite stores found from configured agent roots or a templated session.store root. Legacy selector paths must resolve within the agent root; symlinks and paths outside the root are ignored.

openclaw sessions --all-agents --json:

{
  "path": null,
  "stores": [
    { "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
    { "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
  ],
  "allAgents": true,
  "count": 2,
  "totalCount": 2,
  "limitApplied": 100,
  "hasMore": false,
  "activeMinutes": null,
  "sessions": [
    { "agentId": "main", "key": "agent:main:main", "model": "openai/gpt-5.6-sol" },
    { "agentId": "work", "key": "agent:work:main", "model": "anthropic/claude-sonnet-4-6" }
  ]
}

Tail trajectory progress

openclaw sessions tail
openclaw sessions tail --follow
openclaw sessions tail --session-key "agent:main:telegram:direct:123" --tail 25
openclaw sessions --agent work tail --follow
openclaw sessions --all-agents tail --follow

openclaw sessions tail displays recent runtime trajectory events as compact progress lines. Without --session-key, it follows running sessions first, then the most recent stored session. --tail <count> controls how many existing events appear before follow mode; default 80, and 0 begins at the current end. --follow continues watching the selected SQLite-backed session or an explicit legacy trajectory file.

The progress view is deliberately restrained: prompt text, tool arguments, and tool result bodies are not shown. Tool calls display 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

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json

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

Cleanup maintenance

Run maintenance immediately instead of waiting for the next write cycle:

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --dry-run --fix-dm-scope
openclaw sessions cleanup --json

openclaw sessions cleanup uses session.maintenance settings from configuration (Configuration reference):

• Scope note: openclaw sessions cleanup maintains session stores, transcripts, trajectory rows, and legacy trajectory sidecars. It does not prune cron run history, which automatically keeps the newest 2000 rows per job (Cron configuration).
• Cleanup also removes 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 occurs before global stale cleanup and capping.

Flags:

When a Gateway is accessible, non-dry-run cleanup for configured agent stores is routed through the Gateway so it uses the same session-store writer as live traffic. Use --store <path> for explicit offline repair of a legacy store selector.

openclaw sessions cleanup --all-agents --dry-run --json:

{
  "allAgents": true,
  "mode": "warn",
  "dryRun": true,
  "stores": [
    {
      "agentId": "main",
      "storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
      "beforeCount": 120,
      "afterCount": 80,
      "missing": 0,
      "dmScopeRetired": 0,
      "pruned": 40,
      "capped": 0
    },
    {
      "agentId": "work",
      "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
      "beforeCount": 18,
      "afterCount": 18,
      "missing": 0,
      "dmScopeRetired": 0,
      "pruned": 0,
      "capped": 0
    }
  ]
}

Compact a session

Free up context budget for a stuck or oversized session. openclaw sessions compact <key> is the primary wrapper around the sessions.compact Gateway RPC and needs a running Gateway.

openclaw sessions compact "agent:main:main"
openclaw sessions compact "agent:main:main" --max-lines 200
openclaw sessions compact "agent:work:main" --agent work --json

• Without --max-lines, the Gateway uses LLM summarization on the transcript. By default the CLI does not set a client deadline; the Gateway manages the configured compaction lifecycle.
• With --max-lines <n>, it cuts down to the last n transcript lines and stores the earlier transcript as a .bak sidecar.
• --agent <id>: agent that owns the session; mandatory for global keys.
• --url / --token / --password: overrides for Gateway connection.
• --timeout <ms>: optional client-side RPC timeout in milliseconds.
• --json: display the raw RPC payload.

The command returns a non-zero exit code when the Gateway reports a failed compaction or is unreachable, so cron jobs and scripts never treat a silent no-op as success.

Note

openclaw agent --message '/compact ...' is not a compaction method. Slash commands from the CLI are rejected by the authorized-sender check; that invocation exits non-zero with guidance pointing here rather than silently no-opping.

sessions.compact RPC

openclaw gateway call sessions.compact --params '<json>' accepts:

Example LLM-summarize response:

{
  "ok": true,
  "key": "agent:main:main",
  "compacted": true,
  "result": { "tokensBefore": 243868, "tokensAfter": 34941 }
}

Example truncate response (--max-lines 200):

{
  "ok": true,
  "key": "agent:main:main",
  "compacted": true,
  "archived": "/home/user/.openclaw/agents/main/sessions/transcripts/<id>.jsonl.bak",
  "kept": 200
}

Related

• Session config
• Session management
• Compaction
• CLI reference