OpenClaw's Browser Tool Can Finally Reach Your Signed-In Chrome From a Remote Gateway

The Host-Only Wall That Blocked Remote Gateways

OpenClaw's browser tool has long supported two operating modes: sandboxed browser instances and “existing-session” mode, which attaches to a user's real, signed-in Chrome session. The second mode is what makes OpenClaw useful for tasks that require authentication — logging into dashboards, interacting with web apps that demand a session cookie, or automating workflows behind a login wall.

But there was a catch. Existing-session mode was hard-coded to run only on the host machine. If you ran OpenClaw through a remote gateway — the standard architecture for headless servers, cloud deployments, or multi-node setups — the browser tool would refuse to attach to a signed-in Chrome instance on a connected browser node. The documentation described node-host browser proxy as the standard remote pattern. The code disagreed.

That restriction is now gone. When a browser node is connected, existing-session requests automatically route to it. Explicit targeting still works: target="host" pins to the host machine, target="node" forces node routing, and if no node is available, the request falls back to the host. The sandbox rejection for existing-session profiles remains in place — you still can't attach a signed-in Chrome inside a throwaway sandbox container. That would defeat the purpose.

Why Bare WebSocket URLs Were Silently Killing Browser Startup

If you pointed OpenClaw's browser.cdpUrl at a bare WebSocket URL — something like ws://localhost:9222 without a /devtools/browser/... path — the browser tool would fail with a misleading error: “Browser attachOnly is enabled and profile is not running.” Chrome was running. The CDP endpoint was healthy. But the code treated every WebSocket URL as a direct handshake endpoint, and Chrome only accepts WebSocket upgrades on specific paths returned by its /json/version HTTP endpoint.

The fix introduces a three-tier connection strategy. URLs with explicit /devtools/ paths skip discovery and connect directly — the fast path, unchanged. Bare WebSocket roots now attempt HTTP discovery first: a GET /json/version call retrieves Chrome's real DevTools websocket URL, and OpenClaw uses that. If HTTP discovery fails — because the provider doesn't support the endpoint — it falls back to attempting a direct WebSocket handshake with the original URL. HTTP and HTTPS URLs continue using discovery only, as before.

This matters most for users connecting to managed browser providers like Browserless and Browserbase, which expose bare WebSocket roots without /devtools/ paths. It also fixes a common local development scenario: Chrome launched with --remote-debugging-port=9222 where the user naturally reaches for ws://localhost:9222 as the connection URL.

The Security Tradeoffs

Routing signed-in Chrome sessions to remote nodes raises an obvious question: could this expose a node-local browser profile to an unauthorized gateway? The answer is that the routing change aligns with OpenClaw's already-documented architecture for browser nodes. If you've connected a browser node, you've already authorized the gateway to use it. The target="host" pin remains available for operators who want to keep existing-session requests explicitly local.

On the CDP side, the WebSocket discovery fix includes SSRF policy enforcement across all three connection paths. Fuzz testing with 200 iterations covers URL parsing edge cases, and the test suite now reports 100% statement, branch, function, and line coverage for the three affected files — 238 tests in total.

What Changed in the Docs

Why This Matters

OpenClaw's browser tool is what separates it from most AI assistant frameworks. It doesn't just fetch web pages — it drives a real browser, with real sessions, cookies, and authentication state. But until now, that power was effectively tethered to a single machine. If you ran your gateway remotely, you couldn't reach the signed-in Chrome on the machine sitting under your desk. You had to choose: remote gateway flexibility, or authenticated browsing.

These two changes eliminate that tradeoff. A remote gateway can now attach to a signed-in Chrome on a browser node across the network. A bare ws:// URL to a managed browser provider now connects instead of crashing. They're not flashy features. They're the kind of infrastructure fixes that make the architecture the documentation already described actually work as advertised.

For self-hosters running OpenClaw on a headless cloud server with a browser node on their local workstation, the signed-in-Chrome restriction was the last missing piece. That setup just got a lot more practical.