OpenClaw Browser Not Opening — How to Fix It 2026

When OpenClaw's browser tool fails to open, it's usually a missing dependency, misconfigured Playwright installation, or a display/headless issue. Here's how to diagnose and fix it systematically.

Step 1: Verify Playwright is Installed

# Check Playwright installation:
npx playwright --version

# If not installed:
npm install -g playwright
npx playwright install chromium

# Verify Chromium is available:
npx playwright install --list
# Should show: chromium INSTALLED

Step 2: Test Browser Launch Directly

# Quick test script:
node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log('Browser works! Title:', await page.title());
  await browser.close();
})();
"

Step 3: Fix Missing System Dependencies (Linux/Ubuntu)

# Install required system libraries:
sudo apt-get update
sudo apt-get install -y \
  libgbm1 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
  libxdamage1 libxfixes3 libxrandr2 libglib2.0-0 \
  libgtk-3-0 libpango-1.0-0 libx11-6 libxext6

# Or let Playwright install them:
npx playwright install --with-deps chromium

Step 4: Fix Headless Mode Issues

# Error: "Failed to launch browser" on server
# Fix 1: Ensure headless is enabled (default)
{
  "browser": {
    "headless": true
  }
}

# Fix 2: Add --no-sandbox (required in Docker/some VPS):
{
  "browser": {
    "headless": true,
    "args": ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"]
  }
}

Step 5: Fix Chromium Not Found Error

# Error: "Executable doesn't exist at /path/to/chromium"

# Find where Playwright installed Chromium:
npx playwright show-browser-path chromium

# Force reinstall:
npx playwright install chromium --force

# Set custom executable path in openclaw.json:
{
  "browser": {
    "executablePath": "/usr/bin/chromium-browser"  // Use system Chromium
  }
}

Step 6: Fix Display Issues (Linux with GUI)

# Error: "cannot open display :0"
# Cause: Trying to run headed browser without a display

# Option 1: Use headless mode (recommended)
openclaw config set browser.headless true

# Option 2: Use Xvfb for virtual display:
sudo apt-get install -y xvfb
export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 &
openclaw gateway restart

Step 7: Memory Issues

# Error: Browser crashes immediately (often on Pi or low-RAM VPS)
# Add memory-reducing args:
{
  "browser": {
    "args": [
      "--no-sandbox",
      "--disable-dev-shm-usage",
      "--disable-gpu",
      "--single-process",
      "--no-zygote"
    ]
  }
}

Verify the Fix

openclaw gateway logs --tail 20 | grep -i browser
# Should show: browser tool initialized successfully

# Ask your agent:
"Open https://example.com and tell me the page title"

Get the complete setup guide in The OpenClaw Playbook — everything you need to master OpenClaw for $9.99.