Skip to content
OpenClaw Docs

Session Management

Session Management

Section titled “Session Management”

OpenClaw organizes conversations into sessions. Each message is routed to a session based on where it came from — DMs, group chats, cron jobs, etc.

How messages are routed

Section titled “How messages are routed”
SourceBehavior
Direct messagesShared session by default
Group chatsIsolated per group
Rooms/channelsIsolated per room
Cron jobsFresh session per run
WebhooksIsolated per hook

DM isolation

Section titled “DM isolation”

By default, all DMs share one session for continuity. This is fine for single-user setups.

The fix:

{
  session: {
    dmScope: "per-channel-peer", // isolate by channel + sender
  },
}

Other options:

  • main (default) — all DMs share one session.
  • per-peer — isolate by sender (across channels).
  • per-channel-peer — isolate by channel + sender (recommended).
  • per-account-channel-peer — isolate by account + channel + sender.

Verify your setup with openclaw security audit.

Session lifecycle

Section titled “Session lifecycle”

Sessions are reused until they expire:

  • Daily reset (default) — new session at 4:00 AM local time on the gateway host.
  • Idle reset (optional) — new session after a period of inactivity. Set session.reset.idleMinutes.
  • Manual reset — type /new or /reset in chat. /new <model> also switches the model.

When both daily and idle resets are configured, whichever expires first wins.

Where state lives

Section titled “Where state lives”

All session state is owned by the gateway. UI clients query the gateway for session data.

  • Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
  • Transcripts: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

Session maintenance

Section titled “Session maintenance”

OpenClaw automatically bounds session storage over time. By default, it runs in warn mode (reports what would be cleaned). Set session.maintenance.mode to "enforce" for automatic cleanup:

{
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "30d",
      maxEntries: 500,
    },
  },
}

Preview with openclaw sessions cleanup --dry-run.

Inspecting sessions

Section titled “Inspecting sessions”
  • openclaw status — session store path and recent activity.
  • openclaw sessions --json — all sessions (filter with --active <minutes>).
  • /status in chat — context usage, model, and toggles.
  • /context list — what is in the system prompt.

Further reading

Section titled “Further reading”