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:
{ "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\").)" }{ "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." }{ "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)" }{ "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\".)" }{ "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.
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
Jump to Section
Quick Fix
Most browser control timeouts are resolved by restarting the Gateway:
openclaw gateway restart
If that doesn't work, run the built-in diagnostic:
openclaw doctor --fix
Root Causes
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.
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.
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.
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
lsof -i :18800
# Replace <PID> with the actual PID from lsof output kill -9 <PID>
Windows
netstat -ano | findstr :18800
REM Replace <PID> with the actual PID from netstat output taskkill /PID <PID> /F
Then restart the Gateway:
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:
services:
browser:
image: browserless/chromium
ports:
- "3000:3000"
openclaw:
image: openclaw/openclaw:latest
environment:
- OPENCLAW_BROWSER_CDP_URL=ws://browser:3000Missing --no-sandbox Flag
Chromium in Docker requires --no-sandbox since containers typically run as root:
openclaw config set browser.launchArgs '["--no-sandbox", "--disable-setuid-sandbox"]' --json
Verify the Fix
# 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.
npm install -g openclaw@latest && openclaw gateway restart
Seeing Other Errors Too?
Browser issues often come with these related problems:
Did this guide solve your problem?