docs(browser): document headless MCP existing-session flows

docs/tools/browser-linux-troubleshooting.md

@@ -110,6 +110,48 @@ curl -s -X POST http://127.0.0.1:18791/start
 curl -s http://127.0.0.1:18791/tabs
 ```
 
+## Existing-session MCP on Linux / VPS
+
+If you want Chrome DevTools MCP instead of the managed `openclaw` CDP profile,
+you now have two Linux-safe options:
+
+1. Let MCP launch headless Chrome for an `existing-session` profile:
+
+```json
+{
+  "browser": {
+    "headless": true,
+    "noSandbox": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "defaultProfile": "user"
+  }
+}
+```
+
+2. Attach MCP to a running debuggable Chrome instance:
+
+```json
+{
+  "browser": {
+    "headless": true,
+    "defaultProfile": "user",
+    "profiles": {
+      "user": {
+        "driver": "existing-session",
+        "cdpUrl": "http://127.0.0.1:9222",
+        "color": "#00AA00"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `driver: "existing-session"` still uses Chrome MCP transport, not the extension relay.
+- `cdpUrl` on an `existing-session` profile is interpreted as the MCP browser target (`browserUrl` or `wsEndpoint`), not the normal OpenClaw CDP driver.
+- If you omit `cdpUrl`, headless MCP launches Chrome itself.
+
 ### Config Reference
 
 | Option                   | Description                                                          | Default                                                     |

docs/tools/browser.md

@@ -359,9 +359,13 @@ Notes:
 
 ## Chrome existing-session via MCP
 
-OpenClaw can also attach to a running Chrome profile through the official
-Chrome DevTools MCP server. This reuses the tabs and login state already open in
-that Chrome profile.
+OpenClaw can also use the official Chrome DevTools MCP server for two different
+flows:
+
+- desktop attach via `--autoConnect`, which reuses a running Chrome profile and
+  its existing tabs/login state
+- headless or remote attach, where MCP either launches headless Chrome itself
+  or connects to a running debuggable browser URL/WS endpoint
 
 Official background and setup references:
 
@@ -375,7 +379,7 @@ Built-in profile:
 Optional: create your own custom existing-session profile if you want a
 different name or color.
 
-Then in Chrome:
+Desktop attach flow:
 
 1. Open `chrome://inspect/#remote-debugging`
 2. Enable remote debugging
@@ -398,30 +402,66 @@ What success looks like:
 - `tabs` lists your already-open Chrome tabs
 - `snapshot` returns refs from the selected live tab
 
-What to check if attach does not work:
+What to check if desktop attach does not work:
 
 - Chrome is version `144+`
 - remote debugging is enabled at `chrome://inspect/#remote-debugging`
 - Chrome showed and you accepted the attach consent prompt
 
+Headless / Linux / VPS flow:
+
+- Set `browser.headless: true`
+- Set `browser.noSandbox: true` when running as root or in common container/VPS setups
+- Optional: set `browser.executablePath` to a stable Chrome/Chromium binary path
+- Optional: set `browser.profiles.<name>.cdpUrl` on an `existing-session` profile to an
+  MCP target like `http://127.0.0.1:9222` or
+  `ws://127.0.0.1:9222/devtools/browser/<id>`
+
+Example:
+
+```json5
+{
+  browser: {
+    headless: true,
+    noSandbox: true,
+    executablePath: "/usr/bin/google-chrome-stable",
+    defaultProfile: "user",
+    profiles: {
+      user: {
+        driver: "existing-session",
+        cdpUrl: "http://127.0.0.1:9222",
+        color: "#00AA00",
+      },
+    },
+  },
+}
+```
+
+Behavior:
+
+- without `browser.profiles.<name>.cdpUrl`, headless `existing-session` launches Chrome through MCP
+- with `browser.profiles.<name>.cdpUrl`, MCP connects to that running browser URL
+- non-headless `existing-session` keeps using the interactive `--autoConnect` flow
+
 Agent use:
 
 - Use `profile="user"` when you need the user’s logged-in browser state.
 - If you use a custom existing-session profile, pass that explicit profile name.
 - Prefer `profile="user"` over `profile="chrome-relay"` unless the user
   explicitly wants the extension / attach-tab flow.
-- Only choose this mode when the user is at the computer to approve the attach
-  prompt.
-- the Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
+- On desktop `--autoConnect`, only choose this mode when the user is at the
+  computer to approve the attach prompt.
+- The Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
+  for desktop attach, or use MCP headless/browserUrl/wsEndpoint modes for Linux/VPS paths.
 
 Notes:
 
 - This path is higher-risk than the isolated `openclaw` profile because it can
   act inside your signed-in browser session.
-- OpenClaw does not launch Chrome for this driver; it attaches to an existing
-  session only.
-- OpenClaw uses the official Chrome DevTools MCP `--autoConnect` flow here, not
-  the legacy default-profile remote debugging port workflow.
+- OpenClaw uses the official Chrome DevTools MCP server for this driver.
+- On desktop, OpenClaw uses MCP `--autoConnect`.
+- In headless mode, OpenClaw can launch Chrome through MCP or connect MCP to a
+  configured browser URL/WS endpoint.
 - Existing-session screenshots support page captures and `--ref` element
   captures from snapshots, but not CSS `--element` selectors.
 - Existing-session `wait --url` supports exact, substring, and glob patterns

src/config/schema.help.ts

@@ -257,7 +257,7 @@ export const FIELD_HELP: Record<string, string> = {
   "browser.profiles.*.cdpPort":
     "Per-profile local CDP port used when connecting to browser instances by port instead of URL. Use unique ports per profile to avoid connection collisions.",
   "browser.profiles.*.cdpUrl":
-    "Per-profile CDP websocket URL used for explicit remote browser routing by profile name. Use this when profile connections terminate on remote hosts or tunnels.",
+    "Per-profile browser endpoint URL. For openclaw/extension drivers this is the CDP URL; for existing-session it is passed to Chrome DevTools MCP as browserUrl/wsEndpoint so headless or remote MCP attach can target a running debuggable browser.",
   "browser.profiles.*.driver":
     'Per-profile browser driver mode: "openclaw" (or legacy "clawd") or "extension" depending on connection/runtime strategy. Use the driver that matches your browser control stack to avoid protocol mismatches.',
   "browser.profiles.*.attachOnly":