diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 6d4afc7e465..8ff07e86b3c 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -17,9 +17,17 @@ Use `session.dmScope` to control how **direct messages** are grouped: - `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) +### Secure DM mode (recommended for multi-user setups) -If your agent can receive DMs from **multiple people** (pairing approvals for more than one sender, a DM allowlist with multiple entries, or `dmPolicy: "open"`), enable **secure DM mode** to avoid cross-user context leakage: +> **Security Warning:** If your agent can receive DMs from **multiple people**, you should enable secure DM mode. Without it, all users share the same conversation context, which can leak private information between users. + +**Example of the problem with default settings:** + +- User A (+1555) messages your agent about their medical appointment +- User B (+2666) messages your agent asking "What were we talking about?" +- User B sees User A's private medical information because they share the same session + +**The fix:** Set `dmScope` to isolate sessions per user: ```json5 // ~/.openclaw/openclaw.json @@ -31,9 +39,16 @@ If your agent can receive DMs from **multiple people** (pairing approvals for mo } ``` +**When to enable this:** + +- 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 + Notes: -- Default is `dmScope: "main"` for continuity (all DMs share the main session). +- Default is `dmScope: "main"` for continuity (all DMs share the main session). This is fine for single-user setups. - 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.