From 65dccbdb4b4880a08cd7c805e72da808daf7611c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 22 Feb 2026 12:36:33 +0100 Subject: [PATCH] fix: document onboarding dmScope default as breaking change (#23468) (thanks @bmendonca3) --- CHANGELOG.md | 1 + docs/cli/onboard.md | 1 + docs/concepts/session.md | 1 + docs/gateway/security/index.md | 1 + docs/reference/wizard.md | 1 + docs/start/wizard-cli-reference.md | 1 + docs/start/wizard.md | 1 + 7 files changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3abdeb157cb..c7896ac2879 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai - **BREAKING:** remove legacy Gateway device-auth signature `v1`. Device-auth clients must now sign `v2` payloads with the per-connection `connect.challenge` nonce and send `device.nonce`; nonce-less connects are rejected. - **BREAKING:** unify channel preview-streaming config to `channels..streaming` with enum values `off | partial | block | progress`, and move Slack native stream toggle to `channels.slack.nativeStreaming`. Legacy keys (`streamMode`, Slack boolean `streaming`) are still read and migrated by `openclaw doctor --fix`, but canonical saved config/docs now use the unified names. +- **BREAKING:** CLI local onboarding now sets `session.dmScope` to `per-channel-peer` by default for new/implicit DM scope configuration. If you depend on shared DM continuity across senders, explicitly set `session.dmScope` to `main`. (#23468) Thanks @bmendonca3. ### Fixes diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md index ee6f147f288..fab08d8dae5 100644 --- a/docs/cli/onboard.md +++ b/docs/cli/onboard.md @@ -60,6 +60,7 @@ Flow notes: - `quickstart`: minimal prompts, auto-generates a gateway token. - `manual`: full prompts for port/bind/auth (alias of `advanced`). +- Local onboarding defaults `session.dmScope` to `per-channel-peer` unless `session.dmScope` is already set. - Fastest first chat: `openclaw dashboard` (Control UI, no channel setup). - Custom Provider: connect any OpenAI or Anthropic compatible endpoint, including hosted providers not listed. Use Unknown to auto-detect. diff --git a/docs/concepts/session.md b/docs/concepts/session.md index edd6f415d28..3d1503ab80e 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -49,6 +49,7 @@ Use `session.dmScope` to control how **direct messages** are grouped: Notes: - 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](/cli/security)). diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index f5e46dce43c..7bf0f84abc7 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -332,6 +332,7 @@ This is a messaging-context boundary, not a host-admin boundary. If users are mu Treat the snippet above as **secure DM mode**: - Default: `session.dmScope: "main"` (all DMs share one session for continuity). +- Local CLI onboarding default: writes `session.dmScope: "per-channel-peer"` when unset (keeps existing explicit values). - Secure DM mode: `session.dmScope: "per-channel-peer"` (each channel+sender pair gets an isolated DM context). If you run multiple accounts on the same channel, use `per-account-channel-peer` instead. If the same person contacts you on multiple channels, use `session.identityLinks` to collapse those DM sessions into one canonical identity. See [Session Management](/concepts/session) and [Configuration](/gateway/configuration). diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 19191252e11..3583420a769 100644 --- a/docs/reference/wizard.md +++ b/docs/reference/wizard.md @@ -243,6 +243,7 @@ Typical fields in `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers` (if Minimax chosen) - `gateway.*` (mode, bind, auth, tailscale) +- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved) - `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*` - Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible). - `skills.install.nodeManager` diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index b0b31de8c60..96fd1d87afc 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -215,6 +215,7 @@ Typical fields in `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers` (if Minimax chosen) - `gateway.*` (mode, bind, auth, tailscale) +- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved) - `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*` - Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible) - `skills.install.nodeManager` diff --git a/docs/start/wizard.md b/docs/start/wizard.md index b869c85665f..57a25b15810 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -50,6 +50,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). - Workspace default (or existing workspace) - Gateway port **18789** - Gateway auth **Token** (auto‑generated, even on loopback) + - DM isolation default: `session.dmScope: "per-channel-peer"` (existing explicit `session.dmScope` values are preserved) - Tailscale exposure **Off** - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)