Browser Setup#

One-time environment initialization, run on a fresh openclaw container. No root required.

Notes#

The openclaw environment ships with Chromium pre-installed by default; setup.sh prefers it and only falls back to downloading via Playwright if it's not found.

The primary path for screenshots and browser actions is: Chrome + direct CDP. setup.sh creates a ~/.local/bin/chrome-cdp launcher script.

mcp doctor --probe gives false positives. It returning ok only means the MCP server process started — not that Chromium can actually run. The only reliable check is: playwright__browser_navigate actually returning page content.

Execution order#

Step 1: Run the core setup script#

bash

bash scripts/setup.sh

The script does three things:

1. Chromium detection: prefers the system-preinstalled Chromium, falling back to a Playwright download if not found
2. chrome-cdp launcher script: ~/.local/bin/chrome-cdp, wrapping the --headless=new --no-sandbox --remote-allow-origins=* flags
3. Chinese fonts: downloads WenQuanYi Micro Hei from GitHub into ~/.local/share/fonts/

Step 2: Try configuring the built-in browser (optional, often ineffective)#

Edit ~/.openclaw/openclaw.json ( config.patch refuses to modify protected paths, so the file must be written by hand):

json

{
  "browser": {
    "noSandbox": true,
    "ssrfPolicy": {
      "allowedHostnames": [
        "your target product domain (e.g. app.example.com)",
        "the corresponding login domain (e.g. xxx.us.auth0.com)"
      ]
    }
  }
}

After editing: browser stop → gateway restart → wait 15s → browser start

⚠️ The SSRF allowlist often doesn't take effect (the gateway has a runtime cache and doesn't always pick up the file). If browser navigate still reports blocked by policy, immediately abandon the built-in browser and switch to direct CDP (see TOOLS.md) rather than continuing to restart-and-retry.

Step 4: Initialize TOOLS.md#

bash

cp "$(dirname "$0")/../TOOLS.md" ./TOOLS.md

Step 6 (optional): Install browser-use#

bash

bash scripts/setup-optional.sh

Step 7: Smoke test#

bash

# Start Chrome CDP
chrome-cdp &
sleep 2

# Verify CDP is reachable
curl -s http://localhost:9223/json | python3 -m json.tool | head -20

# Verify with a screenshot (see the CDP screenshot flow in REFERENCE.md)

Acceptance criteria: CDP /json returns a target list, and Chinese text in screenshots renders cleanly with no mojibake.