diff --git a/docs/cli/browser.md b/docs/cli/browser.md
index 11e36603cdf..dbe047a2ca1 100644
--- a/docs/cli/browser.md
+++ b/docs/cli/browser.md
@@ -42,6 +42,14 @@ openclaw browser stop
 openclaw browser --browser-profile openclaw reset-profile
 ```
 
+Notes:
+
+- For `attachOnly` and remote CDP profiles, `openclaw browser stop` closes the
+  active control session and clears temporary emulation overrides even when
+  OpenClaw did not launch the browser process itself.
+- For local managed profiles, `openclaw browser stop` stops the spawned browser
+  process.
+
 ## If the command is missing
 
 If `openclaw browser` is an unknown command, check `plugins.allow` in
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index f5175f7f007..5d4637589af 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -307,6 +307,7 @@ Common signatures:
 - `Playwright is not available in this gateway build; '<feature>' is unsupported.` → the current gateway install lacks the full Playwright package; ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
 - `fullPage is not supported for element screenshots` → screenshot request mixed `--full-page` with `--ref` or `--element`.
 - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` screenshot calls must use page capture or a snapshot `--ref`, not CSS `--element`.
+- stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile <name>` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
 
 Related:
 
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 8497937b279..95fb8f10880 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -245,6 +245,15 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
 - **Remote CDP:** set `browser.profiles.<name>.cdpUrl` (or `browser.cdpUrl`) to
   attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.
 
+Stopping behavior differs by profile mode:
+
+- local managed profiles: `openclaw browser stop` stops the browser process that
+  OpenClaw launched
+- attach-only and remote CDP profiles: `openclaw browser stop` closes the active
+  control session and releases Playwright/CDP emulation overrides (viewport,
+  color scheme, locale, timezone, offline mode, and similar state), even
+  though no browser process was launched by OpenClaw
+
 Remote CDP URLs can include auth:
 
 - Query tokens (e.g., `https://provider.example?token=<token>`)
@@ -638,6 +647,13 @@ Inspection:
 - `openclaw browser snapshot --selector "#main" --interactive`
 - `openclaw browser snapshot --frame "iframe#main" --interactive`
 - `openclaw browser console --level error`
+
+Lifecycle note:
+
+- For attach-only and remote CDP profiles, `openclaw browser stop` is still the
+  right cleanup command after tests. It closes the active control session and
+  clears temporary emulation overrides instead of killing the underlying
+  browser.
 - `openclaw browser errors --clear`
 - `openclaw browser requests --filter api --clear`
 - `openclaw browser pdf`