`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.

openclaw sessions and Gateway sessions.list responses 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.

bash

openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json

Scope selection:

default: configured default agent store
--verbose: verbose logging
--agent <id>: one configured agent store
--all-agents: aggregate all configured agent stores
--store <path>: explicit store path (cannot be combined with --agent or --all-agents)
--limit <n|all>: max rows to output (default 100; all restores full output)

Tail human-readable trajectory progress for stored sessions:

bash

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 renders recent trajectory JSONL 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; the default is 80, and 0 starts at the current end. --follow keeps watching the selected trajectory files, including relocated files referenced by <session>.trajectory-path.json.

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 for a stored session:

bash

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 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.

openclaw sessions --all-agents reads configured agent stores. Gateway and ACP session discovery are broader: they also include disk-only stores found under the default agents/ root or a templated session.store root. Those discovered stores must resolve to regular sessions.json files inside the agent root; symlinks and out-of-root paths are skipped.

JSON examples:

openclaw sessions --all-agents --json:

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": "gpt-5" },
    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
  ]
}

Cleanup maintenance

Run maintenance now (instead of waiting for the next write cycle):

bash

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 config:

Scope note: openclaw sessions cleanup maintains session stores, transcripts, and trajectory sidecars. It does not prune cron run history, which is managed by cron.runLog.keepLines in Cron configuration and explained in Cron maintenance.
Cleanup also prunes unreferenced primary transcripts, compaction checkpoints, and trajectory sidecars older than session.maintenance.pruneAfter; files still referenced by sessions.json are preserved.
--dry-run: preview how many entries would be pruned/capped without writing.
- In text mode, dry-run prints a per-session action table (Action, Key, Age, Model, Flags) so you can see what would be kept vs removed.
--enforce: apply maintenance even when session.maintenance.mode is warn.
--fix-missing: remove entries whose transcript files are missing or header-only/empty, even if they would not normally age/count out yet.
--fix-dm-scope: when session.dmScope is main, retire stale peer-keyed direct-DM rows left behind by earlier per-peer, per-channel-peer, or per-account-channel-peer routing. Use --dry-run first; applying the cleanup removes those rows from sessions.json and preserves their transcripts as deleted archives.
--active-key <key>: protect a specific active key from disk-budget eviction. Durable external conversation pointers, such as group sessions and thread-scoped chat sessions, are also kept by age/count/disk-budget maintenance.
--agent <id>: run cleanup for one configured agent store.
--all-agents: run cleanup for all configured agent stores.
--store <path>: run against a specific sessions.json file.
--json: print a JSON summary. With --all-agents, output includes one summary per store.

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 store file.

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

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
    }
  ]
}

Session config: Configuration reference