Abstract: Browser automation issues in OpenClaw are often not “browser bugs.” They are install-path and dependency mismatches across Ubuntu versions and CPU architecture. This guide gives a practical install matrix for Ubuntu 22/24 on ARM64 and x64, with clear command paths, verification checks, and recovery steps you can run during SetupClaw handoff and later operations.
The most common post-handoff browser incident sounds like this: “It worked last week, now browser actions fail.” In most cases, the root cause is not random instability. It is environment drift, missing system libraries, or Chromium binaries disappearing after rebuild/restart.
That is why SetupClaw should use a matrix-first install model. One tested path per environment. One verification checklist per path. One recovery sequence when something drifts.
If you only keep one generic install guide, operators end up improvising under pressure. The matrix avoids that.
Why a matrix matters more than a single install recipe
Ubuntu 22 and 24 are close enough to feel the same, but package sets and runtime behaviour can differ. ARM64 and x64 are both supported, but in many teams ARM64 tends to surface dependency and persistence mismatches sooner.
So a practical matrix does two things:
- It reduces ambiguity during setup.
- It shortens mean time to recovery when browser actions degrade.
The goal is repeatability, not elegance.
Core rule: use OpenClaw-compatible Playwright install paths
For containerised deployments, prefer the bundled Playwright CLI path over ad hoc npx usage. It reduces version and path mismatch issues between runtime and installed browser binaries.
Example install command for common container layouts where app root is /app:
node /app/node_modules/playwright-core/cli.js install chromiumAfter install changes, restart the Gateway and run verification checks before reopening browser-dependent automations.
Prerequisites checklist by environment
Use this as your baseline matrix checklist. Keep it versioned in your handoff docs.
Ubuntu 22.04 ARM64
- Host packages and browser dependencies installed
- Playwright/Chromium installed via bundled CLI path
- Browser binary cache path persisted
- Gateway restart completed
- Verification suite passed
Ubuntu 22.04 x64
- Host packages and browser dependencies installed
- Playwright/Chromium installed via bundled CLI path
- Browser binary cache path persisted
- Gateway restart completed
- Verification suite passed
Ubuntu 24.04 ARM64
- Host packages and browser dependencies installed
- Playwright/Chromium installed via bundled CLI path
- Browser binary cache path persisted
- Gateway restart completed
- Verification suite passed
Ubuntu 24.04 x64
- Host packages and browser dependencies installed
- Playwright/Chromium installed via bundled CLI path
- Browser binary cache path persisted
- Gateway restart completed
- Verification suite passed
The exact dependency package list can vary over time, so pin it in your own runbook by OS release and review after major apt updates.
Persistence is the non-negotiable control
A clean install is not enough if Chromium binaries live on non-persistent paths.
When cache paths are ephemeral, rebuilds and restarts can remove browser binaries and recreate “browser not found” incidents. This is especially common when teams assume home-directory paths persist the same way across all deployment styles.
Set and persist the browser path explicitly, then test persistence by restarting and rerunning verification.
Mandatory verification checks (handoff and post-change)
Do not mark browser automation as healthy until all checks pass.
- Browser status check
- Open URL
- Snapshot capture
- Screenshot capture
- One scripted action (click/type/select) on a safe target
Pass criteria should be explicit: status is healthy, no missing-browser errors, screenshot is generated, and scripted action completes without unexpected prompts.
If any step fails, do not proceed to cron/browser workloads. Fix the install path first.
Practical verification command flow
Run this sequence after install, rebuild, and dependency updates:
openclaw status
openclaw gateway status
openclaw browser statusThen execute a minimal browser smoke workflow (status, navigate, snapshot, screenshot) through your standard OpenClaw browser tooling path.
Capture pass/fail in the runbook, not just in chat history.
Recovery order for path drift incidents
When browser actions fail unexpectedly, use fixed order:
- Confirm Gateway health
- Confirm Playwright availability
- Reinstall Chromium via bundled CLI
- Recheck persistent browser path
- Restart Gateway
- Rerun full verification checklist
This avoids full reinstall reflexes that hide the actual persistence issue.
Security and operations boundaries during recovery
Keep control-plane access private during install and troubleshooting. Do not expose management surfaces publicly just to debug browser issues faster.
Also keep Telegram usable as your control channel while browser subsystem is degraded. Browser outages should not require full platform downtime.
If fixes require config or Dockerfile changes, run them through PR review and post-merge validation. Install-path changes are production-affecting changes.
Cron and browser dependency coupling
Browser install drift frequently shows up first in scheduled jobs.
Any cron task that depends on browser actions should include preflight checks and clear failure handling so missing binaries do not create noisy repeated failures.
In practice, browser reliability and cron reliability are linked operationally.
One-page matrix table for customer handoff
Your handoff pack should include a compact table with:
- OS + architecture
- Install command block
- Required libraries
- Browser binary path
- Verification steps
- Rollback notes
That one page is usually enough to prevent ad hoc fixes and reduce repeat incidents across environments.
A strong matrix will not prevent third-party UI drift or anti-bot behaviour changes, but it will remove a large class of avoidable install and path failures that otherwise look like random browser instability.