Session Management in OpenClaw: Routing and Isolation

OpenClaw directs each incoming message to a session determined by its origin: direct messages, group chats, cron jobs, and so on. The gateway holds all session state, and UI clients retrieve session data from it.

For the default personal agent setup, where a single rolling conversation is shared across all your DM channels and group activity plus background work merges into it, refer to The main session.

How messages are routed

DM isolation

All DMs share one session for continuity by default, which works well for single-user environments.

Warning

If your agent can receive messages from multiple people, activate DM isolation. Without it, every user operates within the same conversation context, making Alice's private messages accessible to Bob.

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

session.dmScope options:

Tip

When the same person contacts you through multiple channels, apply session.identityLinks to link their identities to a single canonical peer ID, so they share a session.

Dock linked channels

Dock commands redirect the reply route of the current direct-chat session to a different linked channel without initiating a new session. Examples, configuration, and troubleshooting are covered in Channel docking.

Confirm your configuration with openclaw security audit.

Incognito sessions

Incognito sessions are accessible only from the Control UI's New thread screen. Enable Incognito before launching the thread to store its session entry, transcript, and compaction state in process memory rather than on disk. The thread disappears when the Gateway restarts, does not trigger OpenClaw's automatic memory flush, and does not produce a transcript archive upon reset or deletion. Codex-backed runs also start their harness thread in ephemeral mode, so Codex writes no rollout or local session-state files; other model providers communicate via HTTP APIs and keep no local provider transcript in OpenClaw.

The incognito- segment is set aside for dashboard, subagent, and hidden internal session keys; openclaw doctor --fix renames any conflicting legacy durable keys.

Incognito does not limit the agent's standard tools. An explicit request to persist data, or any tool-triggered file write, can still save information outside the incognito session store. Your configured model provider still processes the messages you send, diagnostic logging remains unchanged, and OpenClaw continues to record content-free audit metadata like HMAC references.

On multi-user gateways, incognito threads are visible only to admin-scope connections and never appear through another session's agent session tools or transcript search. This shields them from storage and other gateway-mediated users, but not from the gateway owner or process operator, who can always observe active sessions.

Remember across conversations

Separate transcripts govern each conversation's local history. For a personal or fully trusted agent, memory.search.rememberAcrossConversations: true introduces an optional retrieval step across that agent's other private conversations without merging their transcripts.

Private direct and persistent explicit UI conversations can provide relevant context to each other. Groups and channels remain isolated in both directions: their transcripts are not sources for private recall, and replies in those conversations do not receive private transcript context. The current conversation is also omitted because its history is already loaded.

This setting does not affect session keys, DM scope, routing, delivery, or tools.sessions.visibility. Shared workspace memory in MEMORY.md and memory/*.md retains its existing behavior. The current memory provider must support protected private transcript recall; context engines such as Lossless Claw stay independent and can run alongside it. See Active Memory for setup and runtime details.

Session lifecycle

Sessions persist until you reset them manually or choose an automatic reset policy:

• No automatic reset (default mode: "none") - sessions keep the same sessionId; compaction manages the active context as the conversation grows.
• Daily reset (mode: "daily") - opt into a new session at a configured local hour (session.reset.atHour, default 4, 0-23) on the gateway host. Daily freshness is based on when the current sessionId started, not on later metadata writes.
• Idle reset (mode: "idle") - opt into a new session after session.reset.idleMinutes of inactivity. 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 /new or /reset in chat. /new <model> also switches the model.

When both daily and idle resets are configured, whichever expires first takes precedence. 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 follow the same no-automatic-reset default. Use /reset or configure session.reset explicitly when those sessions should expire on a timer.

Opt into automatic resets globally, then override them per chat type or channel:

{
  session: {
    reset: { mode: "daily", atHour: 4 },
    resetByType: {
      group: { mode: "idle", idleMinutes: 120 },
      thread: { mode: "daily", atHour: 6 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
  },
}

resetByType supports direct, group, and thread. Doctor migrates legacy dm entries to direct and session.idleMinutes to session.reset.idleMinutes; the schema rejects both retired forms.

Where state lives

• Runtime session rows: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• Archived transcript files: ~/.openclaw/agents/<agentId>/sessions/
• Legacy row migration source: ~/.openclaw/agents/<agentId>/sessions/sessions.json

The session rows in the per-agent SQLite database maintain separate lifecycle timestamps:

• sessionStartedAt: when the current sessionId began; daily reset uses this.
• lastInteractionAt: last user/channel interaction that extends idle lifetime.
• updatedAt: last store-row mutation; useful for listing and pruning, but not authoritative for daily/idle reset freshness.

During migration from older installs, gateway startup and openclaw doctor --fix import legacy sessions.json rows and hot transcript JSONL history into SQLite automatically. Rows without sessionStartedAt are resolved from the legacy transcript JSONL session header when available. If an older row also lacks lastInteractionAt, idle freshness falls back to that session start time, not to later bookkeeping writes. Use openclaw doctor --session-sqlite inspect --session-sqlite-all-agents and the Doctor migration sequence when you want explicit inspection or validation evidence.

Session maintenance

OpenClaw manages session storage over time with session.maintenance; default settings are listed below:

{
  session: {
    maintenance: {
      mode: "enforce", // "enforce" applies cleanup; "warn" only reports
      pruneAfter: "30d",
      maxEntries: 500,
    },
  },
}

For production-scale maxEntries thresholds, the Gateway runtime uses a small high-water buffer during writes and then batch-cleans back down to the configured limit. Session store reads do not perform pruning or enforce caps during Gateway startup, so startup and isolated cron sessions avoid the cost of a full store cleanup. openclaw sessions cleanup --enforce enforces the cap right away.

Gateway model-run probe sessions are short-lived by default. Rows matching agent:*:explicit:model-run-<uuid> use a fixed 24h retention period, but cleanup is pressure-gated: stale probe rows are removed only when session-entry maintenance or cap pressure is reached, and this cleanup occurs before the broader stale-entry age cutoff and entry cap. Normal direct, group, thread, cron, hook, heartbeat, ACP, and sub-agent sessions do not receive this 24-hour retention.

Maintenance preserves durable external conversation pointers, such as group sessions and thread-scoped chat sessions, while still allowing synthetic cron, hook, heartbeat, ACP, and sub-agent entries to expire.

Archived sessions are user-shelved and excluded from all automatic maintenance paths, including age pruning, entry caps, model-run cleanup, and disk-budget eviction. They stay archived until you unarchive them or delete them explicitly.

If you previously used DM isolation and later set session.dmScope back to main, preview stale peer-keyed DM rows with openclaw sessions cleanup --dry-run --fix-dm-scope. Applying the same flag retires those old direct-DM rows and keeps their transcripts as deleted archives.

Preview any maintenance run with openclaw sessions cleanup --dry-run.

Inspecting sessions

Further reading

• Session search - full-text recall across past transcripts
• 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