From b648830632be2924d8fb4d0f58387f759e00bb51 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 22 Apr 2026 21:47:22 +0100 Subject: [PATCH] fix: clarify browser playwright-core install guidance --- docs/gateway/troubleshooting.md | 2 +- docs/tools/browser.md | 7 ++++--- extensions/browser/src/browser/routes/agent.shared.ts | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 06891e268a7..de864780ab2 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -475,7 +475,7 @@ Common signatures: - `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs. - `Remote CDP for profile "" is not reachable` → the configured remote CDP endpoint is not reachable from the gateway host. - `Browser attachOnly is enabled ... not reachable` or `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened. -- `Playwright is not available in this gateway build; '' 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. +- `Playwright is not available in this gateway build; '' is unsupported.` → the current gateway install lacks the bundled browser plugin's `playwright-core` runtime dependency; run `openclaw doctor --fix`, then restart the gateway. 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`. - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors. diff --git a/docs/tools/browser.md b/docs/tools/browser.md index 5c6bea6f4ad..a7921ec3b3b 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -637,9 +637,10 @@ What still needs Playwright: Element screenshots also reject `--full-page`; the route returns `fullPage is not supported for element screenshots`. -If you see `Playwright is not available in this gateway build`, install the full -Playwright package (not `playwright-core`) and restart the gateway, or reinstall -OpenClaw with browser support. +If you see `Playwright is not available in this gateway build`, repair the +bundled browser plugin runtime dependencies so `playwright-core` is installed, +then restart the gateway. For packaged installs, run `openclaw doctor --fix`. +For Docker, also install the Chromium browser binaries as shown below. #### Docker Playwright install diff --git a/extensions/browser/src/browser/routes/agent.shared.ts b/extensions/browser/src/browser/routes/agent.shared.ts index ebcdc20d67c..f9f91ff5cdf 100644 --- a/extensions/browser/src/browser/routes/agent.shared.ts +++ b/extensions/browser/src/browser/routes/agent.shared.ts @@ -76,7 +76,7 @@ export async function requirePwAi( 501, [ `Playwright is not available in this gateway build; '${feature}' is unsupported.`, - "Install the full Playwright package (not playwright-core) and restart the gateway, or reinstall with browser support.", + "Repair the bundled browser plugin runtime dependencies so playwright-core is installed, then restart the gateway. In Docker, also install Chromium with the bundled playwright-core CLI.", "Docs: /tools/browser#playwright-requirement", ].join("\n"), );