diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md
index fab08d8dae5..0d39ab87d0c 100644
--- a/docs/cli/onboard.md
+++ b/docs/cli/onboard.md
@@ -60,7 +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.
+- Local onboarding DM scope behavior: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals).
 - 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/reference/wizard.md b/docs/reference/wizard.md
index 3583420a769..1bd83a0bc28 100644
--- a/docs/reference/wizard.md
+++ b/docs/reference/wizard.md
@@ -243,7 +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)
+- `session.dmScope` (behavior details: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals))
 - `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.md b/docs/start/wizard.md
index 57a25b15810..d653574f488 100644
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -50,7 +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)
+    - DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals)
     - Tailscale exposure **Off**
     - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
   </Tab>
diff --git a/src/commands/onboard-config.test.ts b/src/commands/onboard-config.test.ts
index 7c9060ea6d3..ac98bdc4f28 100644
--- a/src/commands/onboard-config.test.ts
+++ b/src/commands/onboard-config.test.ts
@@ -25,4 +25,15 @@ describe("applyOnboardingLocalWorkspaceConfig", () => {
 
     expect(result.session?.dmScope).toBe("main");
   });
+
+  it("preserves explicit non-main dmScope values", () => {
+    const baseConfig: OpenClawConfig = {
+      session: {
+        dmScope: "per-account-channel-peer",
+      },
+    };
+    const result = applyOnboardingLocalWorkspaceConfig(baseConfig, "/tmp/workspace");
+
+    expect(result.session?.dmScope).toBe("per-account-channel-peer");
+  });
 });
diff --git a/src/commands/onboard-config.ts b/src/commands/onboard-config.ts
index 579e5f9d700..3fb6e730822 100644
--- a/src/commands/onboard-config.ts
+++ b/src/commands/onboard-config.ts
@@ -1,6 +1,7 @@
 import type { OpenClawConfig } from "../config/config.js";
+import type { DmScope } from "../config/types.base.js";
 
-export const ONBOARDING_DEFAULT_DM_SCOPE = "per-channel-peer";
+export const ONBOARDING_DEFAULT_DM_SCOPE: DmScope = "per-channel-peer";
 
 export function applyOnboardingLocalWorkspaceConfig(
   baseConfig: OpenClawConfig,