Why does browser control timeout after 20000ms?

The browser control service cannot connect to CDP in time, often due to blocked port, hung browser process, or relay disconnect.

What is the fastest fix?

Restart the Gateway first, then clear any process holding port 18800 and reconnect the extension relay.

Can this happen if Chrome extension relay is not attached?

Yes. If no tab is connected to the relay, OpenClaw cannot route browser commands and returns timeout or reachability errors.

Fix Browser Control Service Timeout

Error Message Variants

This error appears as a JSON object in the agent tool result. There are five common variants depending on the root cause:

Chrome extension not connected to a tab

{ "status": "error", "tool": "browser", "error": "can't reach the openclaw browser control service. restart the openclaw gateway (openclaw.app menubar, or `openclaw gateway`). do not retry the browser tool — it will keep failing. use an alternative approach or inform the user that the browser is currently unavailable. (error: error: chrome extension relay is running, but no tab is connected. click the openclaw chrome extension icon on a tab to attach it (profile \"chrome\").)" }

Timeout (15000ms or 20000ms)

{ "status": "error", "tool": "browser", "error": "can't reach the openclaw browser control service (timed out after 15000ms). restart the openclaw gateway (openclaw.app menubar, or `openclaw gateway`). do not retry the browser tool — it will keep failing. use an alternative approach or inform the user that the browser is currently unavailable." }

Tab not found

{ "status": "error", "tool": "browser", "error": "can't reach the openclaw browser control service. restart the openclaw gateway (openclaw.app menubar, or `openclaw gateway`). do not retry the browser tool — it will keep failing. use an alternative approach or inform the user that the browser is currently unavailable. (error: error: tab not found)" }

Failed to start Chrome CDP on port 18800

{ "status": "error", "tool": "browser", "error": "can't reach the openclaw browser control service. start (or restart) the openclaw gateway (openclaw.app menubar, or `openclaw gateway`) and try again. (error: error: failed to start chrome cdp on port 18800 for profile \"openclaw\".)" }

No supported browser found

{ "status": "error", "tool": "browser", "error": "can't reach the openclaw browser control service. restart the openclaw gateway (openclaw.app menubar, or `openclaw gateway`). do not retry the browser tool — it will keep failing. use an alternative approach or inform the user that the browser is currently unavailable. (error: error: no supported browser found (chrome/brave/edge/chromium on macos, linux, or windows).)" }

OpenClaw uses a browser control service that connects to Chromium via the Chrome DevTools Protocol (CDP). When this service can't be reached, browser automation tasks (screenshots, clicking, typing) fail silently or with a 20-second timeout.

Related report: openclaw/openclaw#19939.

Quick Fix (3 steps)

1. Quit OpenClaw app from menu bar (or openclaw gateway stop)
2. lsof -ti:18800 | xargs kill -9 (clear CDP port)
3. Reopen app, click OpenClaw Chrome extension icon on active tab

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Jump to Section

Quick Fix Root Causes CDP Port Stuck in Use Chrome Extension Relay Docker / Headless Setup Verify the Fix macOS arm64 Timeout

Quick Fix

Most browser control timeouts are resolved by restarting the Gateway:

Restart Gateway

openclaw gateway restart

If that doesn't work, run the built-in diagnostic:

Auto-diagnose

openclaw doctor --fix

Root Causes

Critical

1. Hung page.evaluate() on blocked CDP transport

A JavaScript evaluation inside the browser gets stuck, freezing the entire CDP connection. All subsequent commands queue up and eventually timeout. This is the most common cause.

Critical

2. CDP port (18800) stuck "in use"

After a crash, a stray Chromium process holds port 18800. The browser control service can't start a new browser because the port is occupied.

Warning

3. Gateway process not running

The Gateway crashed or was never started. The browser control service is part of the Gateway — no Gateway means no browser automation.

Info

4. Chrome Extension Relay disconnected

When using the Chrome Extension mode, you need to click the OpenClaw extension icon on a tab to attach it. Without an active tab connection, browser commands timeout.

Fix: CDP Port Stuck in Use

If port 18800 (the default CDP port) is occupied by a stray browser process, the service can't start. Find and kill it:

macOS / Linux

Find process on CDP port

lsof -i :18800

Kill the stray process

# Replace <PID> with the actual PID from lsof output
kill -9 <PID>

Windows

Find process on CDP port

netstat -ano | findstr :18800

Kill the stray process

REM Replace <PID> with the actual PID from netstat output
taskkill /PID <PID> /F

Then restart the Gateway:

Restart after cleanup

openclaw gateway restart

Fix: Chrome Extension Relay

If you're using the Chrome Extension browser mode (not the isolated/managed mode), the extension relay needs an active tab connection:

Steps to Reconnect

1Open Chrome and navigate to the page you want to automate
2Click the OpenClaw extension icon in the toolbar
3Click "Attach to this tab" — the icon should turn green
4Retry the browser command in OpenClaw

Extension Mode vs Managed Mode

If you don't need to control existing Chrome tabs, consider switching to managed browser mode (the default). Managed mode launches isolated Chromium instances automatically — no extension needed.

Fix: Docker / Headless Environments

In Docker containers, the browser control service needs a Chromium binary available. Common issues:

Chrome/Chromium Not Installed

The base OpenClaw Docker image may not include a browser. Add one to your Compose setup:

docker-compose.yml browser service

services:
  browser:
    image: browserless/chromium
    ports:
      - "3000:3000"
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_BROWSER_CDP_URL=ws://browser:3000

Missing --no-sandbox Flag

Chromium in Docker requires --no-sandbox since containers typically run as root:

Set browser launch args

openclaw config set browser.launchArgs '["--no-sandbox", "--disable-setuid-sandbox"]' --json

Verify the Fix

Test browser connectivity

# Start Gateway with verbose logging
openclaw gateway run --verbose

# In another terminal, trigger a browser action
openclaw run "take a screenshot of https://example.com"

# Check logs for browser control errors
openclaw logs --follow | grep -i 'browser\|CDP\|timeout'

If the screenshot succeeds, the browser control service is working correctly.

Upstream Fix Available

Recent OpenClaw versions include a fix that threads AbortSignal through Playwright operations and force-disconnects hung CDP connections via Runtime.terminateExecution. Updating to the latest version may resolve this permanently.

Update to latest OpenClaw

npm install -g openclaw@latest && openclaw gateway restart

macOS arm64 Specific Timeout

On macOS arm64 (Apple Silicon), build v2026.2.25 has a known issue where the browser act tool times out after 20 seconds even though the underlying CLI browser commands work fine. The browser control wrapper has a shorter timeout than the actual Playwright operation.

Symptoms on arm64 Mac

Browser tool returns timeout after exactly 20000ms
Running openclaw run "take a screenshot" from CLI works fine
Only the agent-invoked browser tool hits the timeout

Fix: Re-attach Chrome Relay After Reinstall

If you recently reinstalled OpenClaw or updated the Chrome extension, the relay needs explicit tab re-attachment:

Steps

1Uninstall and reinstall the OpenClaw Chrome extension
2Open Chrome to any page and click the extension icon
3Click "Attach to this tab" — confirm the icon turns green
4Restart the gateway: openclaw gateway restart

Update to latest (arm64 fix)

npm install -g openclaw@latest && openclaw gateway restart

Seeing Other Errors Too?

Browser issues often come with these related problems: