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

DM isolation

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

The fix:

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

Other options:

• text

  Copy

  main
  (default) -- all DMs share one session.
• text

  Copy

  per-peer
  -- isolate by sender (across channels).
• text

  Copy

  per-channel-peer
  -- isolate by channel + sender (recommended).
• text

  Copy

  per-account-channel-peer
  -- isolate by account + channel + sender.

Dock linked channels

Dock commands let a user move the current direct-chat session's reply route to another linked channel without starting a new session. See Channel docking for examples, config, and troubleshooting.

Verify your setup with

.

Session lifecycle

Sessions are reused until they expire:

• Daily reset (default) -- new session at 4:00 AM local time on the gateway host. Daily freshness is based on when the current
  text

  Copy

  sessionId
  started, not on later metadata writes.
• Idle reset (optional) -- new session after a period of inactivity. Set
  text

  Copy

  session.reset.idleMinutes
  . Idle freshness is based on the last real user/channel interaction, so heartbeat, cron, and exec system events do not keep the session alive.
• Manual reset -- type
  text

  Copy

  /new
  or
  text

  Copy

  /reset
  in chat.
  text

  Copy

  /new <model>
  also switches the model.

When both daily and idle resets are configured, whichever expires first wins. Heartbeat, cron, exec, and other system-event turns may write session metadata, but those writes do not extend daily or idle reset freshness. When a reset rolls the session, queued system-event notices for the old session are discarded so stale background updates are not prepended to the first prompt in the new session.

Sessions with an active provider-owned CLI session are not cut by the implicit daily default. Use

or configure explicitly when those sessions should expire on a timer.

Where state lives

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

• Store:
  text

  Copy

  ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcripts:
  text

  Copy

  ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

keeps separate lifecycle timestamps:

• text

  Copy

  sessionStartedAt
  : when the current
  text

  Copy

  sessionId
  began; daily reset uses this.
• text

  Copy

  lastInteractionAt
  : last user/channel interaction that extends idle lifetime.
• text

  Copy

  updatedAt
  : last store-row mutation; useful for listing and pruning, but not authoritative for daily/idle reset freshness.

Older rows without

are resolved from the transcript JSONL session header when available. If an older row also lacks , idle freshness falls back to that session start time, not to later bookkeeping writes.

Session maintenance

OpenClaw automatically bounds session storage over time. By default, it runs in

mode (reports what would be cleaned). Set to for automatic cleanup:

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

For production-sized

limits, Gateway runtime writes use a small high-water buffer and clean back down to the configured cap in batches. This avoids running full store cleanup on every isolated cron session. applies the cap immediately.

Preview with

.

Inspecting sessions

• text

  Copy

  openclaw status
  -- session store path and recent activity.
• text

  Copy

  openclaw sessions --json
  -- all sessions (filter with
  text

  Copy

  --active <minutes>
  ).
• text

  Copy

  /status
  in chat -- context usage, model, and toggles.
• text

  Copy

  /context list
  -- what is in the system prompt.

Further reading

• Session Pruning -- trimming tool results
• Compaction -- summarizing long conversations
• Session Tools -- agent tools for cross-session work
• Session Management Deep Dive -- store schema, transcripts, send policy, origin metadata, and advanced config
• Multi-Agent — routing and session isolation across agents
• Background Tasks — how detached work creates task records with session references
• Channel Routing — how inbound messages are routed to sessions

Related

• Session pruning
• Session tools
• Command queue