Fix OpenClaw Browser Errors: Complete Troubleshooting Guide (2026)

How the OpenClaw Browser Service Works

OpenClaw uses Puppeteer and a bundled Chromium binary to give agents the ability to browse the web, take screenshots, extract content, and interact with pages. When you start the OpenClaw gateway, it launches a browser service process in the background. This process opens a controlled Chromium instance that agents connect to via a local WebSocket on port 9222 by default.

When an agent needs to browse a URL, it sends a request to the browser service, which opens a new tab, navigates, extracts the result, and returns it to the agent. The browser service keeps Chromium running between requests to avoid the overhead of launching a new browser every time.

Puppeteer

browser automation layer

Chromium

bundled browser binary

Port 9222

local control interface

Most browser errors fall into three categories: the service is not running, the service started but lost the connection, or the browser opened but the navigation failed. Each has a distinct error message and a distinct fix.

Error 1: “Can’t Reach the OpenClaw Browser Control Service”

This is the most common error. It means the browser service process is not running at all, or it started and immediately crashed before your agent could connect to it.

Error: browser failed: can't reach the OpenClaw browser control service
  at BrowserService.connect (browser-service.js:47)
  at Agent.browse (agent.js:203)

Step 1: Check if the browser service is running

# Check the gateway and browser service status
openclaw gateway status
openclaw browser status

# If the browser service shows as stopped, start it manually
openclaw browser start

# Check the browser logs for startup errors
openclaw browser logs

Step 2: Install missing Chromium dependencies

On Linux (Raspberry Pi, VPS, or WSL), Chromium often fails to start because system libraries are missing. This is the most common root cause on fresh installs.

# Install all Chromium system dependencies on Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y \
  libnss3 \
  libatk1.0-0 \
  libatk-bridge2.0-0 \
  libcups2 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxrandr2 \
  libgbm1 \
  libasound2

# On Raspberry Pi OS (arm64)
sudo apt-get install -y chromium-browser

# After installing dependencies, try starting the browser service again
openclaw browser start

Step 3: Re-download the bundled Chromium binary

# Force Puppeteer to re-download its bundled Chromium
npx puppeteer browsers install chrome

# Or reinstall OpenClaw globally which triggers the download
npm install -g openclaw

# Verify the binary exists and is executable
ls -la ~/.cache/puppeteer/chrome/

Step 4: Check if port 9222 is already in use

# Check if something else is using port 9222
lsof -i :9222

# If another process is using it, either kill that process
# or change the OpenClaw browser port
openclaw config set browser.port 9223
openclaw browser restart

Error 2: “Browser Service Disconnected”

This error appears when the browser service was running and connected, but then lost the connection mid-session. It is different from the first error because the service started successfully. Something caused it to stop or become unreachable after startup.

Error: Browser service disconnected
  WebSocket connection to 'ws://127.0.0.1:9222/json' failed
  Target closed.

Fix A: Prevent Mac sleep from killing the browser

On Mac, App Nap and system sleep suspend background processes, which kills the Chromium process. The browser service then cannot reconnect because the WebSocket is gone.

# Prevent the Mac from sleeping while OpenClaw runs
# Add this to your gateway startup or run it manually
caffeinate -i openclaw gateway start

# Or disable sleep entirely in System Settings:
# System Settings > Battery > Options > Prevent automatic sleeping when display is off

# You can also use pmset to configure sleep behavior
sudo pmset -a sleep 0
sudo pmset -a disksleep 0

Fix B: Check if the OOM killer terminated Chromium

On Linux systems with limited RAM (Raspberry Pi, low-tier VPS), the kernel’s out-of-memory killer terminates Chromium when memory is exhausted.

# Check if OOM killer killed the browser process
dmesg | grep -i "oom|killed|chromium" | tail -20

# If OOM is the issue, limit tabs in OpenClaw config
openclaw config set browser.maxTabs 2

# Add swap space on Raspberry Pi to help with memory pressure
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=1024 (1GB swap)
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Fix C: Enable browser auto-restart

# Tell OpenClaw to automatically restart the browser service on disconnect
openclaw config set browser.autoRestart true
openclaw config set browser.restartDelay 3000

# This makes the browser service restart within 3 seconds
# of any disconnection without manual intervention

Error 3: “Navigation Failed”

Navigation failed errors mean the browser service is running and connected, but the browser could not load the target URL. This is almost always a network issue, a timeout, or the target site blocking automated browsers.

Error: Navigation failed: net::ERR_NAME_NOT_RESOLVED
Error: Navigation failed: Timeout of 30000ms exceeded
Error: Navigation failed: net::ERR_CONNECTION_REFUSED

Fix A: Increase the navigation timeout

# Default timeout is 30 seconds (30000ms). Increase for slow sites.
openclaw config set browser.timeout 60000

# For very slow or JS-heavy pages
openclaw config set browser.timeout 90000

# Restart the browser service after changing the config
openclaw browser restart

Fix B: Check DNS resolution from the host machine

# Test if the host can resolve DNS at all
nslookup google.com
dig google.com

# If DNS fails inside Docker containers
# Add a DNS server to the Docker run command
docker run --dns 8.8.8.8 your-openclaw-image

# Or set DNS in docker-compose.yml
# services:
#   openclaw:
#     dns:
#       - 8.8.8.8
#       - 1.1.1.1

Fix C: Handle sites that block automated browsers

Some sites detect headless Chromium and block requests. You can make the browser less detectable by setting a realistic user agent and disabling automation flags.

# Set a realistic user agent in OpenClaw browser config
openclaw config set browser.userAgent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

# Disable the automation fingerprint
openclaw config set browser.args '["--disable-blink-features=AutomationControlled"]'

# Restart to apply
openclaw browser restart

Running the Browser on a VPS or Remote Server

A VPS has no graphical display. If OpenClaw tries to launch Chromium in non-headless mode on a VPS, it fails immediately because there is no display server to connect to.

Option A: Headless mode (recommended)

# Enable headless mode — Chromium runs without any display
openclaw config set browser.headless true

# Restart the browser service
openclaw browser restart

# Verify it is running
openclaw browser status

Option B: Xvfb virtual display (for tools that need a real display)

If you need to capture screenshots with full CSS rendering or run a tool that explicitly requires a display, set up Xvfb as a virtual framebuffer.

# Install Xvfb
sudo apt-get install -y xvfb

# Start a virtual display on display :99
Xvfb :99 -screen 0 1280x720x24 &

# Export the display before starting OpenClaw
export DISPLAY=:99
openclaw gateway start

# To keep Xvfb running across reboots with systemd:
sudo tee /etc/systemd/system/xvfb.service << 'EOF'
[Unit]
Description=X Virtual Frame Buffer
After=network.target

[Service]
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x720x24
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable xvfb
sudo systemctl start xvfb

Sandbox Errors After a Security Update

Several users on Reddit have reported that a recent Chromium sandbox security update breaks browser access, particularly in Docker containers and when running as root. The error looks like this:

[0227/123456.789:FATAL:zygote_host_impl_linux.cc(116)] No usable sandbox!
Running as root without --no-sandbox is not supported.

Fix for Docker containers

# Add --no-sandbox to the browser args in OpenClaw config
openclaw config set browser.args '["--no-sandbox", "--disable-setuid-sandbox"]'

# Or set it via environment variable
export OPENCLAW_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox"

# Alternatively, run the Docker container with SYS_ADMIN capability
docker run --cap-add=SYS_ADMIN your-openclaw-image

Fix for Linux non-root users (kernel namespaces)

# Check if user namespaces are enabled
cat /proc/sys/kernel/unprivileged_userns_clone

# If the value is 0, enable it
sudo sysctl -w kernel.unprivileged_userns_clone=1

# To persist across reboots
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
sudo sysctl --system

# Restart the browser service after the kernel change
openclaw browser restart

Note: The --no-sandbox flag reduces Chromium’s process isolation. It is safe to use inside Docker containers or isolated VMs, but avoid it on shared machines where untrusted content might be loaded.

Memory Issues: Limiting Tabs and Closing Unused Pages

Each open browser tab in Chromium uses 50-200 MB of RAM depending on the page. On a Raspberry Pi with 1-2 GB of RAM, or a budget VPS, this adds up quickly. If Chromium is using too much memory, reduce the number of concurrent tabs and close pages when done.

# Limit concurrent browser tabs
openclaw config set browser.maxTabs 2

# Close pages after each request instead of keeping them open
openclaw config set browser.closePagesAfterUse true

# Reduce Chromium memory usage with flags
openclaw config set browser.args '[
  "--disable-dev-shm-usage",
  "--disable-extensions",
  "--disable-plugins",
  "--disable-background-networking",
  "--disable-sync",
  "--no-first-run",
  "--single-process"
]'

# Monitor Chromium memory usage
ps aux | grep chromium | awk '{print $6/1024 " MB	" $11}'

# Restart the browser service periodically (every 24h) to free leaked memory
# Add to crontab:
# 0 4 * * * openclaw browser restart

Full Diagnostic Checklist

Run these commands in order when a browser error appears. They cover the most common root causes in sequence from quickest to check to most complex.

# 1. Check gateway and browser service status
openclaw gateway status
openclaw browser status

# 2. View the last 50 lines of browser logs
openclaw browser logs --lines 50

# 3. Check if Chromium binary exists and is executable
ls -la ~/.cache/puppeteer/chrome/

# 4. Check if port 9222 is in use by another process
lsof -i :9222

# 5. Test DNS resolution from the host
nslookup google.com

# 6. Check system memory
free -m

# 7. Check for OOM kills in the kernel log (Linux)
dmesg | grep -i oom | tail -10

# 8. Restart the browser service clean
openclaw browser stop
sleep 2
openclaw browser start
openclaw browser logs

Related Guides

OpenClaw Mac Always-On Guide

Keep your Mac running agents 24/7 without interruption

OpenClaw Gateway Daemon Guide

Run the OpenClaw gateway as a background service

Frequently Asked Questions

What does 'can't reach the OpenClaw browser control service' mean?

This error means the browser service process is not running or failed to start. OpenClaw uses a background Chromium process to handle web browsing tasks. When that process is not running, any agent that tries to use the browser skill gets this error. The fix is to ensure Chromium is installed, the browser service is started, and nothing is blocking the port it listens on. Run 'openclaw browser start' and check logs with 'openclaw browser logs' to diagnose the root cause.

Why does the browser service keep disconnecting?

Browser service disconnections are usually caused by one of three things: the host machine going to sleep, a memory limit being hit that causes the process to be killed, or a timeout set too low. On Mac, disable App Nap for the terminal process. On Linux/VPS, check that no OOM killer is terminating the Chromium process. Increase the browser timeout in your OpenClaw config and limit concurrent tabs to reduce memory pressure.

How do I run the OpenClaw browser on a VPS with no display?

A VPS has no graphical display, so Chromium needs to run in headless mode or with a virtual display. The recommended approach is to set headless mode in your OpenClaw config: 'openclaw config set browser.headless true'. If an agent or tool explicitly requires a real display (for example, to capture screenshots with CSS animations), install Xvfb with 'sudo apt install xvfb' and start it with 'Xvfb :99 -screen 0 1280x720x24 &', then set 'DISPLAY=:99' in your environment.

Which Chromium or Chrome version works with OpenClaw?

OpenClaw's browser service uses Puppeteer under the hood, which bundles a specific version of Chromium. You do not need to install Chrome separately in most cases. If you run into missing dependency errors on Linux (libglib, libnss, libatk, etc.), install them with 'sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1'. On Mac, Chromium is downloaded automatically when you install OpenClaw. System-installed Chrome can conflict with the bundled version, so prefer the bundled one unless you have a specific reason to override.

How do I increase browser timeout in OpenClaw?

The default browser navigation timeout is 30 seconds. For slow sites or heavy pages, this is often too short. Set a higher timeout with: 'openclaw config set browser.timeout 60000' (value is in milliseconds). For agents that do a lot of scraping, 90000 (90 seconds) is a reasonable ceiling. You can also set a per-task timeout in the agent's SOUL.md skills section by passing a timeout parameter to the browse skill.

The sandbox update broke my browser access. How do I fix it?

Several Reddit users have reported that a recent sandbox security update in Chromium causes the browser to fail to start, typically with 'Running as root without --no-sandbox is not supported'. If you are running OpenClaw as root (not recommended) or in a Docker container, add the no-sandbox flag: 'openclaw config set browser.args ["--no-sandbox", "--disable-setuid-sandbox"]'. For non-root users, the proper fix is to ensure user namespaces are enabled on the kernel: 'sudo sysctl -w kernel.unprivileged_userns_clone=1'. The Docker case specifically requires '--no-sandbox' because containers do not have user namespaces by default.

Deploy Agents That Actually Work

Get a complete, pre-configured OpenClaw agent package with SOUL.md, browser setup, deployment scripts, and support. No more guessing at config flags.

OpenClaw Setup Guide Build Your Agent