Summary

Calling browser(action="start") or browser(action="open") before browser(action="snapshot") or browser(action="screenshot") causes a PortInUseError that makes all functional browser tool calls fail until gateway restart.

Steps to reproduce

1. Call browser(action="start", profile="openclaw") or browser(action="open", targetUrl="...", profile="openclaw")
2. Call browser(action="snapshot", ...) or browser(action="screenshot", ...)
3. Error: "PortInUseError: Port 18800 is already in use"
4. All subsequent snapshot/screenshot/act/navigate calls fail with the same error
5. Restarting the gateway restores normal function

Alternatively: call snapshot or screenshot after any previous browser session left a stale Chromium process (e.g. after a gateway restart without pkill).

Expected behavior

snapshot/screenshot/act should work regardless of whether start or open was called first. The browser control service should either reuse the existing Chromium instance or handle the port conflict gracefully.

Actual behavior

Calling start or open launches Chromium directly with --remote-debugging-port=18800. When snapshot or screenshot is subsequently called, the browser control service attempts to start its own Chromium on the same port and fails with:

"Can't reach the OpenClaw browser control service. (Error: PortInUseError: Port 18800 is already in use.)"

All functional browser tool calls (snapshot, screenshot, act, navigate) then fail for the remainder of the gateway session. Gateway restart is required to recover.

OpenClaw version

2026.2.18

Operating system

Linux — Debian 12 (bookworm), x86_64

Install method

Nix (home-manager, headless server, no sandbox: noSandbox: true)

Logs, screenshots, and evidence

Gateway log pattern (repeatable):

[browser/chrome] 🦞 openclaw browser started (custom) profile "openclaw" on 127.0.0.1:18800 (pid 2692478)
[tools] browser failed: Can't reach the OpenClaw browser control service. ... (Error: PortInUseError: Port 18800 is already in use.)

Port check after start/open:
$ ss -tlnp | grep 18800
LISTEN 0 10 127.0.0.1:18800 0.0.0.0:* users:(("chromium",pid=2692478,fd=64))

Workaround that works:
1. pkill -9 chromium
2. Call browser(action="screenshot", targetUrl="...", profile="openclaw")  ← bootstraps control service's own Chromium
3. Call browser(action="tabs", ...) to get targetId
4. Call browser(action="navigate", targetId=..., targetUrl="...")
5. Call browser(action="snapshot", targetId=...) ← works

Impact and severity

Affected: Any agent on Linux using browser(action="start") or browser(action="open") as an initialization step (which the tool description implies is the correct entry point)
Severity: High — blocks all browser automation until gateway restart
Frequency: 100% reproducible
Consequence: Browser tool is effectively unusable unless the agent happens to know the workaround; the documented/intuitive usage pattern (start → open → snapshot) reliably breaks it

Additional information

The workaround is: never call start or open; instead bootstrap with browser(action="screenshot", targetUrl="...") which lets the browser control service manage Chromium itself. start and open appear to use a different code path that spawns a competing Chromium on port 18800.

Gateway restart also clears the stuck state, but is obviously disruptive.

The tool description in the system prompt currently recommends "start" and "open" for initialization — this should either be corrected or the underlying conflict fixed.