Session Management (OpenClaw)

Sessions organize conversations across channels. The Gateway owns all session state; routing, isolation scope, lifecycle, and cleanup are each configurable independently.

Message Routing

Session assignment depends on message origin:

Origin	Default Session
Direct messages	Shared (`main`)
Group chats	Isolated per group
Rooms / channels	Isolated per room
Cron jobs	Fresh session per run
Webhooks	Isolated per hook

DM Isolation (`session.dmScope`)

DMs default to a single shared session — a privacy risk in multi-user setups. Override with:

Value	Isolation
`main`	All DMs share one session (default)
`per-peer`	Isolated by sender across channels
`per-channel-peer`	Isolated by channel + sender (recommended)
`per-account-channel-peer`	Isolated by account + channel + sender

Lifecycle

Sessions persist until:

Daily reset at 4:00 AM (local gateway time, default)
Idle reset — session.reset.idleMinutes
Manual reset — /new or /reset

/new <model> also switches the active model at session start.

State Storage

~/.openclaw/agents/<agentId>/sessions/
  sessions.json          ← session metadata
  <sessionId>.jsonl      ← full conversation transcript (append-only)

The Gateway manages all session state. The .jsonl transcript is the durable record — compare with Anthropic's externalized model in Durable Session Storage.

Maintenance & Cleanup

Setting	Default	Effect
`session.maintenance.mode`	`warn`	Reports stale sessions; set `"enforce"` to prune automatically
`pruneAfter`	30 days	Age threshold for cleanup
`maxEntries`	500	Max entries before enforcement

Preview cleanup: openclaw sessions cleanup --dry-run

Inspection

Command	What it shows
`openclaw status`	Session paths and recent activity
`openclaw sessions --json`	All sessions with filtering
`/status` (in chat)	Context usage and model info
`/context list` (in chat)	System prompt contents

Session Pruning — per-request in-memory tool output trimming
Compaction — durable conversation summarization at context limit
Session Tool — agent-facing cross-session API (7 tools)
Durable Session Storage — Anthropic's externalized session model (contrast)
OpenClaw Gateway — Gateway owns session routing and state
Source - Session Management (OpenClaw Docs)