Skip to main content

​
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

SourceBehavior
Direct messagesShared session by default
Group chatsIsolated per group
Rooms/channelsIsolated per room
Cron jobsFresh session per run
WebhooksIsolated per hook

​
DM isolation

By default, all DMs share one session for continuity. This is fine for single-user setups.
If multiple people can message your agent, enable DM isolation. Without it, all users share the same conversation context — Alice’s private messages would be visible to Bob.
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.
If the same person contacts you from multiple channels, use session.identityLinks to link their identities so they share one session.
Verify your setup with openclaw security audit.

​
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

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

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

  • 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