diff --git a/docs/tools/browser-control.md b/docs/tools/browser-control.md
index 78abfee9d8c..f88d8504c60 100644
--- a/docs/tools/browser-control.md
+++ b/docs/tools/browser-control.md
@@ -28,7 +28,10 @@ For local integrations only, the Gateway exposes a small loopback HTTP API:
 - State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
 - Settings: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
 
-All endpoints accept `?profile=<name>`.
+All endpoints accept `?profile=<name>`. `POST /start?headless=true` requests a
+one-shot headless launch for local managed profiles without changing persisted
+browser config; attach-only, remote CDP, and existing-session profiles reject
+that override because OpenClaw does not launch those browser processes.
 
 If shared-secret gateway auth is configured, browser HTTP routes require auth too:
 
@@ -122,6 +125,7 @@ All commands accept `--browser-profile <name>` to target a specific profile, and
 ```bash
 openclaw browser status
 openclaw browser start
+openclaw browser start --headless # one-shot local managed headless launch
 openclaw browser stop            # also clears emulation on attach-only/remote CDP
 openclaw browser tabs
 openclaw browser tab             # shortcut for current tab
diff --git a/docs/tools/browser-linux-troubleshooting.md b/docs/tools/browser-linux-troubleshooting.md
index dd00cc62414..0f909c7405c 100644
--- a/docs/tools/browser-linux-troubleshooting.md
+++ b/docs/tools/browser-linux-troubleshooting.md
@@ -37,7 +37,8 @@ Other common Linux launch failures:
   `WAYLAND_DISPLAY` are both unset. If you set `OPENCLAW_BROWSER_HEADLESS=0`,
   `browser.headless: false`, or `browser.profiles.<name>.headless: false`,
   remove that headed override, set `OPENCLAW_BROWSER_HEADLESS=1`, start `Xvfb`,
-  or run OpenClaw in a real desktop session.
+  run `openclaw browser start --headless` for a one-shot managed launch, or run
+  OpenClaw in a real desktop session.
 
 ### Solution 1: Install Google Chrome (Recommended)