OpenClaw Browser Guide

OpenClaw with built-in browser control via Playwright MCP, plus an optional Browserbase add-on for managed remote browsers.

Overview

OpenClaw Browser is the OpenClaw runtime configured with a browser MCP server (Microsoft's Playwright MCP) pre-wired so the agent can drive a real Chromium browser headlessly. Suitable for scraping, form automation, and any tool use that needs a real DOM. Works identically on Docker hosts and Firecracker micro-VMs.

Docker Image

The template ships a pre-baked image with Chromium + Playwright MCP already installed, so cold start is under 10 seconds — no apt-get or playwright install at boot.

Image: ghcr.io/mariagorskikh/openclaw-browser:2026.5.24 — built from backend/templates/openclaw_browser/Dockerfile via the .github/workflows/build-openclaw-browser.yml workflow. Override via OPENCLAW_BROWSER_IMAGE in backend env to swap registries or pin a different tag.

How It Works

Maritime injects a browser MCP server entry into openclaw.json on first boot. The browser launches with --headless --no-sandboxbecause Chromium runs as non-root (UID 1000) inside Docker without CAP_SYS_ADMIN.PLAYWRIGHT_BROWSERS_PATH points at /opt/playwright in the pre-baked image, or /data/playwright when running browser as an add-on on a stock openclaw image.

// Inside openclaw.json:
"mcp": {
  "servers": {
    "browser": {
      "command": "playwright-mcp",
      "args": ["--browser", "chromium", "--headless", "--no-sandbox"],
      "env": { "PLAYWRIGHT_BROWSERS_PATH": "/opt/playwright" }
    }
  }
}

Browserbase Add-on (optional)

For sites with anti-bot protection (Cloudflare, Datadome, captchas) the local Chromium will get blocked. Wire up a managed Browserbase session as a second MCP server by setting these env vars on any openclaw-family agent (works on plain openclaw, maritime, or openclaw_browser):

BROWSERBASE_API_KEY=bb_live_...
BROWSERBASE_PROJECT_ID=prj_...
# Required: Stagehand (Browserbase's automation layer) needs its own
# LLM — a Google AI Studio key. GOOGLE_API_KEY works too.
GEMINI_API_KEY=AIzaSy...
# Optional: override the automation model (default google/gemini-2.5-flash;
# keep the provider/ prefix):
# BROWSERBASE_MODEL_NAME=google/gemini-2.5-pro

Maritime detects the pair at boot and injects a browserbase MCP server alongside the local browser entry. The agent gets both tools and the LLM picks per task — you pay Browserbase directly for the sessions you use. No Maritime tier gating.

"browserbase": {
  "command": "npx",
  "args": [
    "-y", "@browserbasehq/mcp@2.4.3",
    "--browserbaseApiKey", "...",
    "--browserbaseProjectId", "...",
    "--modelName", "google/gemini-2.5-flash"
  ],
  "env": { "GEMINI_API_KEY": "..." }
}

Tier Requirements

Chromium needs more than 512 MB to render reliably. The Smart tier is blocked at create time — Extended ($5/mo, 1 GB) is the minimum. The container also provisions /dev/shm at 512 MB so multiple Chromium tabs don't crash on shared memory exhaustion. On Firecracker, browser-flavored VMs are auto-bumped to 1024 MB RAM.

Environment Variables

Standard OpenClaw variables apply — set OPENAI_API_KEY or ANTHROPIC_API_KEY, or rely on the Maritime LLM proxy. Add BROWSERBASE_API_KEY + BROWSERBASE_PROJECT_ID + GEMINI_API_KEY for the remote-browser add-on.

Deploy

Select Template → OpenClaw Browser in the Create Agent modal, or:

maritime create my-agent --template openclaw_browser --tier extended