From 44da868b8506d04b0afd54e19d0c4b6599ba7edb Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sat, 14 Mar 2026 01:27:32 -0700 Subject: [PATCH] docs(browser): document headless MCP existing-session flows --- docs/tools/browser-linux-troubleshooting.md | 42 ++++++++++++++ docs/tools/browser.md | 64 +++++++++++++++++---- src/config/schema.help.ts | 2 +- 3 files changed, 95 insertions(+), 13 deletions(-) diff --git a/docs/tools/browser-linux-troubleshooting.md b/docs/tools/browser-linux-troubleshooting.md index 1ab51657044..d46e338edad 100644 --- a/docs/tools/browser-linux-troubleshooting.md +++ b/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 | diff --git a/docs/tools/browser.md b/docs/tools/browser.md index ebe352036c5..60a6f285b10 100644 --- a/docs/tools/browser.md +++ b/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..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/` + +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..cdpUrl`, headless `existing-session` launches Chrome through MCP +- with `browser.profiles..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 diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index 215a17d77d8..86ca7977d93 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -257,7 +257,7 @@ export const FIELD_HELP: Record = { "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":