Using Playwright and Puppeteer with OpenClaw to Capture Screenshots

For a screenshot through OpenClaw, start with its native browser command: openclaw browser screenshot. OpenClaw documents browser profiles backed by Playwright, including full-page, element/reference, and labeled screenshot modes. Puppeteer can capture screenshots in its own automation API, but the reviewed OpenClaw documentation does not establish Puppeteer as an interchangeable built-in browser driver. Treat it as a separate option unless your OpenClaw version or extension documents otherwise.

This guide covers OpenClaw CLI captures, profile differences, Docker setup, and standalone Playwright and Puppeteer examples. OpenClaw command and profile behavior can change between releases, so check the documentation that matches your installed version.

1. Choose the right screenshot path

Use OpenClaw’s integrated browser control when the page is already part of an OpenClaw workflow or you want its profile-specific screenshot features. Use standalone Playwright or Puppeteer when you are writing a separate browser automation script and want to control navigation and capture directly.

Approach	Best fit	What to know
OpenClaw browser CLI	Capturing a page from an OpenClaw-controlled browser	Screenshot modes and labeling depend on the selected browser profile.
Standalone Playwright	A script or application that directly controls a browser	Use Playwright’s page screenshot API; this is separate from the OpenClaw CLI.
Standalone Puppeteer	A script or application built around Puppeteer	Puppeteer documents its own screenshot API; do not assume OpenClaw uses it as a built-in driver.

2. Prepare OpenClaw’s browser profile

OpenClaw documents a managed browser profile named openclaw as the default. It also supports profiles that attach to an existing browser session. Check the profile before capturing: managed and existing-session profiles differ in how they connect and in which screenshot features they expose.

Confirm browser control is enabled in the OpenClaw configuration.
Choose the managed openclaw profile, or select the documented existing-session profile if you need to attach to a running browser.
Make sure the browser executable is available to the environment running the Gateway. Configure the executable path there if needed.
For a container deployment, use an OpenClaw browser-enabled Docker image and configure a profile for its local Chromium.

In a container, a browser path that exists only on the host will not resolve inside the Gateway. A mounted home or cache directory can also hide the image’s bundled Playwright-managed browser, so check mounts if browser discovery fails.

3. Capture a page or element with OpenClaw

The documented command family is openclaw browser screenshot. The following examples show the documented mode flags; run the command’s help in your installed release to confirm any required target or output arguments.

Viewport screenshot

openclaw browser screenshot

This captures the current browser page in the selected profile. Open or select the target page in the OpenClaw browser workflow first.

Full-page screenshot

openclaw browser screenshot --full-page

Use this for a page-length capture rather than just the visible viewport. OpenClaw documents --full-page as incompatible with --ref and --element; use a separate element/reference capture when you need a clip.

Capture an element from a snapshot reference

openclaw browser screenshot --ref e12

Replace e12 with a current reference obtained from the browser page snapshot. References describe page elements and can become stale after navigation or substantial page changes. Take a fresh snapshot before reusing a reference if the page has changed.

Capture by CSS selector

openclaw browser screenshot --element "main article"

CSS --element capture depends on the profile. The documented existing-session profile does not support this mode. If the selected profile rejects the flag, use a supported snapshot reference or switch to a compatible profile.

Add screenshot labels

openclaw browser screenshot --labels

On Playwright-backed profiles, labels can be used with full-page, reference, and element-clip modes. The labeled output can include annotations with bounding boxes. Existing-session profiles use a different overlay path and do not return those annotations, so do not expect identical label output across profiles.

4. Use standalone Playwright

When you need an independent script, Playwright’s screenshot API captures the current viewport by default. Set fullPage for the whole document or call locator.screenshot() to capture one element. This JavaScript example uses Chromium and writes PNG files.

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });

try {
  await page.goto('https://example.com', { waitUntil: 'networkidle' });
  await page.screenshot({ path: 'viewport.png' });
  await page.screenshot({ path: 'full-page.png', fullPage: true });
  await page.locator('main').screenshot({ path: 'main.png' });
} finally {
  await browser.close();
}

Install the Playwright package and its browser binaries using the official Playwright installation instructions for your environment. If a site keeps connections open and never reaches network idle, use a different readiness condition, such as waiting for a known selector, before capture.

5. Use standalone Puppeteer

Puppeteer’s screenshot guide covers viewport and full-page captures through its own API. The following Node.js example launches a browser, writes both files, and closes the browser even if navigation or capture fails.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1440, height: 900 });
  await page.goto('https://example.com', { waitUntil: 'networkidle2' });
  await page.screenshot({ path: 'viewport.png' });
  await page.screenshot({ path: 'full-page.png', fullPage: true });
} finally {
  await browser.close();
}

For an element clip, locate the element and use Puppeteer’s element screenshot API:

const element = await page.$('main');
if (!element) throw new Error('Could not find main element');
await element.screenshot({ path: 'main.png' });

Install Puppeteer and its supported browser setup according to the official guide. This is a standalone Puppeteer workflow; it does not make Puppeteer an OpenClaw profile driver.

6. Keep captures reliable

Wait for the content you need. Network-idle waits may be unsuitable for pages with analytics, streaming, or long-lived connections. Waiting for a meaningful selector can be more reliable.
Refresh references after page changes. Navigation can invalidate element references. OpenClaw also warns that raw browser target IDs may change; prefer stable tab IDs or suggested target IDs in longer workflows.
Set the viewport deliberately. Responsive layout changes can alter element positions and page height. Use a consistent viewport when comparing captures.
Choose viewport, full-page, or clip intentionally. Full-page capture can create a very tall image; element capture is better for a specific component.
Close standalone browsers in a finally block. This releases browser processes if navigation or screenshot writing throws an error.
Check the runtime environment. In Docker, the Gateway needs access to Chromium inside the container; host-only paths are not sufficient.

7. Troubleshooting

Problem	Likely cause	Fix
OpenClaw cannot find or launch a browser	Browser control is disabled, the executable path is wrong, or the browser is unavailable in the Gateway environment.	Check browser configuration and executable path. In Docker, use the browser-enabled image and ensure the path resolves inside the container.
Browser discovery broke after mounting a home/cache directory	The mount may hide the image’s bundled Playwright-managed Chromium.	Review the mount and make a browser available at a path visible inside the container.
`--full-page` conflicts with another flag	Full-page mode cannot be combined with `--ref` or `--element`.	Run a full-page capture separately, or omit that flag for the element/reference capture.
`--element` is unsupported	The selected profile may be an existing-session profile, which does not support CSS element capture.	Use a compatible Playwright-backed profile or capture through a supported snapshot reference.
Labels appear without expected annotations	Existing-session profiles use a different overlay path and do not return bounding-box annotations.	Use a Playwright-backed profile for the documented annotation behavior.
A reference points to the wrong element or fails	The page changed after the snapshot, making the reference stale.	Take a new snapshot and use a current reference.
Standalone script hangs waiting for readiness	The page may keep network connections open, so network-idle is never reached.	Wait for a specific selector or use an appropriate navigation readiness condition for the page.
Screenshot is blank or missing content	The page may not have finished rendering, or the browser may have captured before the target content appeared.	Wait for a page-specific selector or other reliable readiness signal before taking the screenshot.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF. It can be useful when you need a capture without installing or managing a browser in your script or Gateway.

For a complete list of parameters and response behavior, see the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. See the docs for available capture options and setup details.

9. Cost and operational notes

With self-managed Playwright or Puppeteer, account for the compute and maintenance involved in running browsers, installing compatible binaries, and handling page failures in your own environment. OpenClaw deployments also need browser resources available in the Gateway runtime. The sources reviewed provide no comparable benchmark, so choose based on integration needs and operational setup rather than assumed speed.

ScreenshotNeo’s published plan options are Free: 1,000 shots per month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; and Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is available on every plan. Only clean shots are billed: bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Check the product site for current plan details.

10. Frequently asked questions

Can OpenClaw capture only one element?

Yes, through a supported reference capture or CSS --element mode, depending on the profile. Existing-session profiles do not support CSS element capture.

Does OpenClaw require Puppeteer?

The reviewed OpenClaw documentation describes Playwright-backed profiles. It does not establish Puppeteer as an equivalent built-in driver.

Can I use an already running browser?

OpenClaw documents existing-session profiles for attaching to a running browser. Their screenshot and labeling support differs from managed Playwright-backed profiles.

Why use a screenshot API instead of browser automation?

An API can remove browser installation and runtime management from a capture workflow. Browser automation remains useful when the task needs direct control of browser behavior or is already integrated into OpenClaw.