browser-setup

# Browser Setup (No-Root Linux)

Install headless Google Chrome for OpenClaw's `browser` tool on Linux without root access.

## When to Use

- `browser start` fails with "No supported browser found"
- Chrome starts but pages crash ("Page crashed", "Target page closed")
- Running on a cloud container, VPS, or sandboxed environment without `sudo`

## Quick Start

```bash
bash scripts/install-browser.sh
```

The script downloads Chrome, extracts ~40 shared library packages, installs Liberation fonts, creates a wrapper script, and verifies the installation. Takes ~2 minutes.

Then configure OpenClaw:

```bash
openclaw config set browser.executablePath "$HOME/local-libs/chrome-wrapper.sh"
openclaw config set browser.headless true
openclaw config set browser.noSandbox true
openclaw config set browser.attachOnly true
```

Set the CDP port for the openclaw profile (edit `~/data/openclaw.json` or equivalent config):

```json
{
  "browser": {
    "executablePath": "~/local-libs/chrome-wrapper.sh",
    "headless": true,
    "noSandbox": true,
    "attachOnly": true,
    "profiles": {
      "openclaw": { "cdpPort": 18800, "color": "#FF4500" }
    }
  }
}
```

## Critical: attachOnly Must Be true

OpenClaw has two internal paths for browser operations:

- **CDP path** (start/stop/tabs): communicates directly with Chrome's CDP port
- **Playwright path** (navigate/snapshot/act): uses `playwright-core` bundled with OpenClaw

When `attachOnly: false`, Playwright calls `launchOpenClawChrome()` which checks `ensurePortAvailable(cdpPort)`. Since Chrome is already listening on that port, it throws `PortInUseError` on every navigate/snapshot/act call.

When `attachOnly: true`, Playwright uses `connectOverCDP()` to attach to the running Chrome instance. No port conflict.

**Always set `attachOnly: true` when using a wrapper script or manually-started Chrome.**

## Usage Flow

### Starting Chrome

Chrome must be started before OpenClaw can use it. Start it manually:

```bash
~/local-libs/c...