Session Scoping & Isolation

+15 Mana ✨
OpenClaw Sessions Documentation(DOCUMENTATION)

Introduction

OpenClaw assigns each agent a primary direct-chat session so that every conversation has a clear, persistent context. Understanding how sessions are scoped and isolated is essential for building agents that serve multiple users without leaking private information. This lesson covers DMScope options, session keys, and identity links.

Key Concepts

  • DMScope — controls how direct-message sessions are partitioned across peers and channels.
  • Session Key — a deterministic string that uniquely identifies a session, following the pattern agent:<agentId>:<mainKey>.
  • Identity Links — a mapping inside session.identityLinks that associates provider-prefixed peer IDs with canonical user identities.
  • Isolation Level — the granularity at which conversation history and context are kept separate.

Real World Context

Imagine a customer-support agent deployed across Slack and Discord simultaneously. Without proper session isolation, a question from User A on Slack could bleed into the context seen when User B asks something on Discord. DMScope settings prevent this by controlling exactly how sessions are partitioned, ensuring each user — or each user-per-channel — gets their own conversational sandbox.

Deep Dive

Every agent in OpenClaw maintains one primary direct-chat session per peer by default. All direct messages collapse into a single session key following the format:

agent:<agentId>:<mainKey>

The <mainKey> is typically "main", so a default session key looks like agent:support-bot:main.

DMScope Options

The dmScope property on an agent controls how sessions are partitioned. There are four options:

yaml
# In your agent configuration
dmScope: main          # All DMs share one session (default)
dmScope: per-peer      # Isolate by sender
dmScope: per-channel-peer   # Isolate by channel + sender (recommended for multi-user)
dmScope: per-account-channel-peer  # Full isolation by account + channel + sender

Before looking at what each does, it helps to understand the problem they solve: when multiple users talk to the same agent, should the agent remember all conversations in one context, or keep them separate?

  • main — the default. Every direct message from every user feeds into the same session. Suitable for single-user agents or personal assistants.
  • per-peer — creates a separate session for each unique sender. User A and User B each get their own history.
  • per-channel-peer — isolates by both the channel and the sender. This is the recommended setting for multi-user deployments because the same user messaging from different channels gets appropriately separated contexts.
  • per-account-channel-peer — the most granular option, adding account-level isolation on top of channel and peer.

Session Key Patterns

Different session types produce different key patterns:

text
# Direct message session
agent:support-bot:main

# Group chat session
agent:support-bot:slack-general:group:g_abc123

# Cron job session
cron:daily-report

The key pattern determines where session data is stored and how it is retrieved. Direct sessions use the agent:<agentId>:<mainKey> format, group sessions append the channel and group identifier, and cron sessions use a completely separate cron:<job.id> prefix.

Identity Links

A session object contains an identityLinks map that connects provider-specific peer IDs to canonical identities:

json
{
  "identityLinks": {
    "slack:U12345": "alice",
    "discord:98765": "alice"
  }
}

This mapping allows the agent to recognise that the Slack user U12345 and the Discord user 98765 are actually the same person — Alice. Identity links enable cross-platform continuity when combined with the appropriate DMScope.

Common Pitfalls

  • Using main scope in multi-user deployments — all users share one session, so private information leaks between conversations. Switch to per-channel-peer for multi-user agents.
  • Forgetting that group sessions have different key patterns — group sessions use agent:<agentId>:<channel>:group:<id>, not the direct-message pattern. Assuming all sessions follow the same format leads to lookup failures.
  • Ignoring identity links — without mapping provider-prefixed IDs to canonical identities, the same user on two platforms appears as two separate people, fragmenting their context.

Best Practices

  • Default to per-channel-peer for any agent that will interact with more than one user. It provides the best balance of isolation and simplicity.
  • Configure identity links when your agent is deployed across multiple platforms so cross-platform users maintain a unified history.
  • Use descriptive main keys — while "main" is the default, custom main keys can help organise sessions when an agent handles multiple conversation types.

Summary

  • Each agent gets one primary direct-chat session per peer, with the key format agent:<agentId>:<mainKey>.
  • DMScope controls isolation granularity: main, per-peer, per-channel-peer, or per-account-channel-peer.
  • Group and cron sessions follow distinct key patterns separate from direct-message sessions.
  • Identity links map provider-prefixed peer IDs to canonical identities for cross-platform continuity.
  • For multi-user agents, per-channel-peer is the recommended DMScope setting.
✓ Completed