openclaw/docs/concepts/session.md at 567ca3a56fdb3c0cf5fa191bb467ea4468bfe9bc

mirror of https://github.com/openclaw/openclaw.git synced 2026-04-01 06:56:47 +02:00

Files

Vincent Koc e682b72154 docs: Batch 1 — create automation hub + add Related sections

New page: docs/automation/index.md — single entry point for all automation
mechanisms (heartbeat, cron, tasks, hooks, standing-orders, webhooks) with
a decision flowchart and comparison table.

Add "Related" sections to 5 high-traffic pages that were dead ends:
- gateway/heartbeat.md → links to tasks, cron-vs-heartbeat, timezone, troubleshooting
- concepts/session.md → links to multi-agent, tasks, channel-routing
- concepts/multi-agent.md → links to channel-routing, subagents, ACP, presence, session
- concepts/agent-loop.md → links to tools, hooks, compaction, exec-approvals, thinking
- concepts/timezone.md → links to heartbeat, cron-jobs, date-time

Add automation/index to Mintlify nav as first item in Automation group.

2026-03-30 19:07:18 +09:00

3.6 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

How OpenClaw manages conversation sessions

You want to understand session routing and isolation

You want to configure DM scope for multi-user setups

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

Source	Behavior
Direct messages	Shared session by default
Group chats	Isolated per group
Rooms/channels	Isolated per room
Cron jobs	Fresh session per run
Webhooks	Isolated 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.

3.6 KiB Raw Blame History