Pre-Bake Chromium Into Your OpenClaw Docker Image: No More Runtime Downloads

If you've self-hosted OpenClaw in Docker and tried to use browser automation, you've probably hit the dreaded Playwright download wall. Every container restart meant waiting for Chromium to download all over again. OpenClaw 2026.2.17 finally solves this with a new build argument: OPENCLAW_INSTALL_BROWSER.

The Problem

OpenClaw's browser tools use Playwright under the hood for web automation, screenshots, and scraping. By default, Playwright downloads browser binaries at runtime—around 150MB for Chromium alone. In Docker, this creates issues:

• Slow cold starts: Every new container spends time downloading browsers
• Network dependencies: Air-gapped or restricted environments can't reach Playwright's CDN
• Ephemeral storage: Containers without persistent volumes re-download on every restart
• CI/CD overhead: Every pipeline run pays the download tax

The Solution

The new OPENCLAW_INSTALL_BROWSER build argument lets you pre-install Chromium and Xvfb directly into your Docker image at build time:

# In your docker build command:
docker build --build-arg OPENCLAW_INSTALL_BROWSER=1 -t my-openclaw .

# Or in docker-compose.yml:
services:
  openclaw:
    build:
      context: .
      args:
        OPENCLAW_INSTALL_BROWSER: "1"

What Gets Installed

When you set OPENCLAW_INSTALL_BROWSER=1, the build process:

1. Installs Chromium via Playwright's dependency installer
2. Adds Xvfb (X Virtual Framebuffer) for headless display
3. Configures environment variables so Playwright finds the pre-installed browser

This increases your image size by roughly 400-500MB, but eliminates all runtime download delays.

When to Use It

Use OPENCLAW_INSTALL_BROWSER=1 when:

• Your agent uses browser automation (browser tool, web scraping)
• You're running in Kubernetes or other orchestrated environments
• You need deterministic, fast container starts
• You're in air-gapped networks without external CDN access

Skip it when:

• You never use browser features
• You're bandwidth-constrained and image size matters more than startup time
• You mount a persistent volume for Playwright's cache directory

Example: Minimal Browser-Ready Image

FROM node:20-slim

ARG OPENCLAW_INSTALL_BROWSER

# Install OpenClaw
RUN npm install -g openclaw

# Pre-install browser if requested
RUN if [ "$OPENCLAW_INSTALL_BROWSER" = "1" ]; then \
      npx playwright install chromium --with-deps; \
      apt-get update && apt-get install -y xvfb && rm -rf /var/lib/apt/lists/*; \
    fi

CMD ["openclaw", "gateway", "start"]

Verifying It Works

After building with the flag, test that Chromium is available:

docker run --rm my-openclaw npx playwright chromium --version

You should see the Chromium version without any download prompts.

Related

• OpenClaw v2026.2.17 Release Notes
• Issue #18449 - Original feature request

This small addition makes a big difference for production Docker deployments. No more waiting, no more network dependencies—just instant browser automation.