​

Session Management

• main (default): all DMs share the main session for continuity.
• per-peer: isolate by sender id across channels.
• per-channel-peer: isolate by channel + sender (recommended for multi-user inboxes).
• per-account-channel-peer: isolate by account + channel + sender (recommended for multi-account inboxes). Use session.identityLinks to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using per-peer, per-channel-peer, or per-account-channel-peer.

​

Secure DM mode (recommended for multi-user setups)

Security Warning: If your agent can receive DMs from multiple people, you should strongly consider enabling secure DM mode. Without it, all users share the same conversation context, which can leak private information between users.

• Alice (<SENDER_A>) messages your agent about a private topic (for example, a medical appointment)
• Bob (<SENDER_B>) messages your agent asking “What were we talking about?”
• Because both DMs share the same session, the model may answer Bob using Alice’s prior context.

// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}

• You have pairing approvals for more than one sender
• You use a DM allowlist with multiple entries
• You set dmPolicy: "open"
• Multiple phone numbers or accounts can message your agent

• Default is dmScope: "main" for continuity (all DMs share the main session). This is fine for single-user setups.
• Local CLI onboarding writes session.dmScope: "per-channel-peer" by default when unset (existing explicit values are preserved).
• For multi-account inboxes on the same channel, prefer per-account-channel-peer.
• If the same person contacts you on multiple channels, use session.identityLinks to collapse their DM sessions into one canonical identity.
• You can verify your DM settings with openclaw security audit (see security).
• Session isolation and Workspace Lanes solve different problems. dmScope separates conversation history; workspace lanes separate user-specific workspace files for multi-user-capable personas.

​

Gateway is the source of truth

• In remote mode, the session store you care about lives on the remote gateway host, not your Mac.
• Token counts shown in UIs come from the gateway’s store fields (inputTokens, outputTokens, totalTokens, contextTokens). Clients do not parse JSONL transcripts to “fix up” totals.

​

Where state lives

• On the gateway host:
  • Store file: ~/.openclaw/agents/<agentId>/sessions/sessions.json (per agent).
• Transcripts: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl (Telegram topic sessions use .../<SessionId>-topic-<threadId>.jsonl).
• The store is a map sessionKey -> { sessionId, updatedAt, ... }. Deleting entries is safe; they are recreated on demand.
• Group entries may include displayName, channel, subject, room, and space to label sessions in UIs.
• Session entries include origin metadata (label + routing hints) so UIs can explain where a session came from.
• WednesdayAI does not read legacy Pi/Tau session folders.

​

Maintenance

​

Defaults

• session.maintenance.mode: warn
• session.maintenance.pruneAfter: 30d
• session.maintenance.maxEntries: 500
• session.maintenance.rotateBytes: 10mb
• session.maintenance.resetArchiveRetention: defaults to pruneAfter (30d)
• session.maintenance.maxDiskBytes: unset (disabled)
• session.maintenance.highWaterBytes: defaults to 80% of maxDiskBytes when budgeting is enabled

​

How it works

• mode: "warn": reports what would be evicted but does not mutate entries/transcripts.
• mode: "enforce": applies cleanup in this order:
  1. prune stale entries older than pruneAfter
  2. cap entry count to maxEntries (oldest first)
  3. archive transcript files for removed entries that are no longer referenced
  4. purge old *.deleted.<timestamp> and *.reset.<timestamp> archives by retention policy
  5. rotate sessions.json when it exceeds rotateBytes
  6. if maxDiskBytes is set, enforce disk budget toward highWaterBytes (oldest artifacts first, then oldest sessions)

​

Performance caveat for large stores

• very high session.maintenance.maxEntries values
• long pruneAfter windows that keep stale entries around
• many transcript/archive artifacts in ~/.openclaw/agents/<agentId>/sessions/
• enabling disk budgets (maxDiskBytes) without reasonable pruning/cap limits

• use mode: "enforce" in production so growth is bounded automatically
• set both time and count limits (pruneAfter + maxEntries), not just one
• set maxDiskBytes + highWaterBytes for hard upper bounds in large deployments
• keep highWaterBytes meaningfully below maxDiskBytes (default is 80%)
• run openclaw sessions cleanup --dry-run --json after config changes to verify projected impact before enforcing
• for frequent active sessions, pass --active-key when running manual cleanup

​

Customize examples

{
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "45d",
      maxEntries: 800,
      rotateBytes: "20mb",
      resetArchiveRetention: "14d",
    },
  },
}

{
  session: {
    maintenance: {
      mode: "enforce",
      maxDiskBytes: "1gb",
      highWaterBytes: "800mb",
    },
  },
}

{
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "14d",
      maxEntries: 2000,
      rotateBytes: "25mb",
      maxDiskBytes: "2gb",
      highWaterBytes: "1.6gb",
    },
  },
}

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Plugin correlation and privacy

• session.identityLinks remains configuration used by core identity resolution. Plugin contexts expose resolved fields such as canonicalIdentity and senderIsOwner; they do not expose raw identityLinks.
• channelConversationId identifies the transport conversation or thread. Legacy plugin fields named conversationId refer to this channel identity.
• providerConversationId is an opaque provider/cache correlation id derived by WednesdayAI for model calls. It is not a session storage column and should be stored only as an opaque value.
• turn.turnId identifies one user turn and is the same string value as runId in the v1 plugin contract.
• sessionId and sessionKey may be absent during very early message_received hooks. WednesdayAI omits them when no real session exists instead of fabricating a session value.

​

External session storage

​

Configured-backend-only invariant

• fs-jsonl (legacy default): transcript entries are read and written through *.jsonl files.
• sqlite: transcript entries are read and written through the SQLite ctx_session_entries table.
• postgres: transcript entries are read and written through the Postgres ctx_session_entries table.

• Switching from JSONL to SQLite/Postgres does not require a manual transcript migration; the store metadata file is rebuilt on demand and the database becomes the source of truth for content.
• If you have existing .jsonl files and start with a database backend, the gateway may backfill those files into the database on first startup, but subsequent reads always come from the database. Disable the backfill with session.storage.migration.validateOnStart: false if you want a clean cut-over.
• Running openclaw sessions cleanup still bounds sessions.json and any JSONL archives for the fs-jsonl backend; for database backends it does not mutate the database content directly.

​

Sub-agent and announce output

​

Session pruning

​

Pre-compaction memory flush

​

Mapping transports → session keys

• Direct chats follow session.dmScope (default main).
  • main: agent:<agentId>:<mainKey> (continuity across devices/channels).
    • Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
  • per-peer: agent:<agentId>:dm:<peerId>.
  • per-channel-peer: agent:<agentId>:<channel>:dm:<peerId>.
  • per-account-channel-peer: agent:<agentId>:<channel>:<accountId>:dm:<peerId> (accountId defaults to default).
  • If session.identityLinks matches a provider-prefixed peer id (for example telegram:123), the canonical key replaces <peerId> so the same person shares a session across channels.
• Group chats isolate state: agent:<agentId>:<channel>:group:<id> (rooms/channels use agent:<agentId>:<channel>:channel:<id>).
  • Telegram forum topics append :topic:<threadId> to the group id for isolation.
  • Legacy group:<id> keys are still recognized for migration.
• Inbound contexts may still use group:<id>; the channel is inferred from Provider and normalized to the canonical agent:<agentId>:<channel>:group:<id> form.
• Other sources:
  • Isolated cron assistant-task jobs: cron:<job.id>
  • Webhooks: hook:<uuid> (unless explicitly set by the hook)
  • Node runs: node-<nodeId>

​

Lifecycle

• Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message.
• Daily reset: defaults to 4:00 AM local time on the gateway host. A session is stale once its last update is earlier than the most recent daily reset time.
• Idle reset (optional): idleMinutes adds a sliding idle window. When both daily and idle resets are configured, whichever expires first forces a new session.
• Legacy idle-only: if you set session.idleMinutes without any session.reset/resetByType config, WednesdayAI stays in idle-only mode for backward compatibility.
• Per-type overrides (optional): resetByType lets you override the policy for direct, group, and thread sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
• Per-channel overrides (optional): resetByChannel overrides the reset policy for a channel (applies to all session types for that channel and takes precedence over reset/resetByType).
• Reset triggers: exact /new or /reset (plus any extras in resetTriggers) start a fresh session id and pass the remainder of the message through. /new <model> accepts a model alias, provider/model, or provider name (fuzzy match) to set the new session model. If /new or /reset is sent alone, WednesdayAI runs a short “hello” greeting turn to confirm the reset.
• Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
• Isolated cron assistant-task jobs always mint a fresh sessionId per run (no idle reuse). Main-session cron jobs add a system event or wake-gate nudge to the main heartbeat path instead of creating a cron:<job.id> chat session.

​

Send policy (optional)

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
        // Match the raw session key (including the `agent:<id>:` prefix).
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ],
      default: "allow",
    },
  },
}

• /send on → allow for this session
• /send off → deny for this session
• /send inherit → clear override and use config rules Send these as standalone messages so they register.

​

Configuration (optional rename example)

// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender", // keep group keys separate
    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // Defaults: mode=daily, atHour=4 (gateway host local time).
      // If you also set idleMinutes, whichever expires first wins.
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  },
}

​

Inspecting

• openclaw status — shows store path and recent sessions.
• openclaw sessions --json — dumps every entry (filter with --active <minutes>).
• openclaw gateway call sessions.list --params '{}' — fetch sessions from the running gateway (use --url/--token for remote gateway access).
• Send /status as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
• Send /context list or /context detail to see what’s in the system prompt and injected workspace files (and the biggest context contributors).
• Send /stop (or standalone abort phrases like stop, stop action, stop run, stop openclaw) to abort the current run, clear queued followups for that session, and stop any sub-agent runs spawned from it (the reply includes the stopped count).
• Send /compact (optional instructions) as a standalone message to summarize older context and free up window space. See /concepts/compaction.
• JSONL transcripts can be opened directly to review full turns.

​

Tips

• Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
• When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.

​

Troubleshooting

​

Related

• Session pruning
• Compaction
• Gateway configuration

​

Session origin metadata

• label: human label (resolved from conversation label + group subject/channel)
• provider: normalized channel id (including extensions)
• from/to: raw routing ids from the inbound envelope
• accountId: provider account id (when multi-account)
• threadId: thread/topic id when the channel supports it The origin fields are populated for direct messages, channels, and groups. If a connector only updates delivery routing (for example, to keep a DM main session fresh), it should still provide inbound context so the session keeps its explainer metadata. Extensions can do this by sending ConversationLabel, GroupSubject, GroupChannel, GroupSpace, and SenderName in the inbound context and calling recordSessionMetaFromInbound (or passing the same context to updateLastRoute).