The OpenClaw browser relay

Your agent can fetch a page, but fetching is not the same as using one. The tab that matters is already signed in, it sits on a laptop in another room, and the Gateway runs on a server somewhere else entirely. OpenClaw's answer is to relay browser actions to the machine where the browser actually lives, and then keep them there.

Four places the browser can live

• Local control, the default. The Gateway starts the loopback control service and can launch a local browser. Targetless actions such as open, navigate, or openclaw browser start can launch it; an action that names a tab by targetId, tab id, or label never starts a stopped browser, because a fresh browser cannot contain that tab.
• Remote control through a node host. You run a node host on the machine that has the browser, and the Gateway proxies browser actions to it. The node exposes its own local browser control server through a proxy command, so the Gateway never needs the browser binary at all.
• Remote CDP. Set the cdpUrl key under your profile in browser.profiles, or the legacy single-profile browser.cdpUrl, to attach to a remote Chromium-based browser. In that case OpenClaw will not launch a local browser of its own.
• Attach-only loopback services. For an externally managed CDP service published on 127.0.0.1, Browserless in Docker being the common case, also set attachOnly: true. Loopback CDP without attachOnly is treated as a local OpenClaw-managed profile, and OpenClaw may report that the port is in use but not owned by OpenClaw.

Once an action reaches the node, its follow-up snapshot or settings stay on that node instead of switching browsers.

Routing is decided once, not per action

Automatic routing prefers the host, including a stopped managed browser whose executable is merely installed. An explicit target of node, a node selector, or gateway.nodes.browser.node overrides that preference, while target=host always stays on the host. Whichever owner is selected then keeps everything: existing-session, extension, attach-only and remote CDP connections belong to it even when no managed-browser executable is present, and launch failures, invalid executable settings, permission errors and page-action failures stay on that owner rather than being replayed on another machine. Automatic host fallback from a selected node is allowed only before that node has handled a request, which is the sentence above in practice. This is what makes a multi-step browser task coherent: the snapshot you act on and the element refs it returned describe one browser, not two.

Boundaries the relay keeps

• Profiles come from the node's own browser.profiles config, exactly as they would if you were sitting at that machine. The Gateway does not project its own profile list onto the node.
• Persistent profile mutations are refused through the proxy command no matter how it is configured: create-profile, delete-profile and reset-profile are blocked regardless of allowProfiles. Make those changes on the node directly.
• nodeHost.browserProxy.allowProfiles is optional. Left empty, every configured profile stays reachable through the proxy, which is the legacy default behaviour. Set it and OpenClaw treats it as a least-privilege boundary limiting which profile names the proxy will target. To switch the whole path off, use nodeHost.browserProxy.enabled=false on the node, or gateway.nodes.browser.mode=off on the Gateway, which also accepts auto and manual.

The agent sees one tool for all four arrangements: a single browser tool covering doctor, status, start, stop, tabs, open, focus, close, snapshot, screenshot, navigate, act, requests, errors, text and emulate, with a profile argument for which browser and a target argument of sandbox, host or node for which machine. The same verb can mean different things per mode. Stop on a local managed profile ends the process OpenClaw launched, while on attach-only and remote CDP profiles it closes the active control session and releases the Playwright and CDP emulation overrides for viewport, colour scheme, locale, timezone and offline mode, even though OpenClaw never launched a browser process there. The headless setting follows the same rule, since it only affects local managed profiles that OpenClaw launches. The full action list and its arguments are in the browser tool actions, and what a node host actually is, how it pairs and what else it can carry, is in browser nodes.

Hosted browsers and the three URL shapes

OpenClaw accepts three CDP URL shapes and picks the connection strategy for each automatically. An http:// or https:// base means discovery: OpenClaw calls /json/version, reads the WebSocket debugger URL and connects, with no WebSocket fallback. A direct ws:// or wss:// endpoint with a /devtools/browser, page, worker, shared_worker or service_worker path skips /json/version entirely. A bare WebSocket root with no /devtools path, which is what Browserless and Browserbase hand you, tries HTTP discovery first and falls back to a direct handshake at the root if discovery returns nothing usable. Those URLs usually carry authorisation as a query token or HTTP Basic credentials, and OpenClaw preserves that auth both when calling /json/* endpoints and when opening the CDP WebSocket, so treat the whole URL as a secret and keep it in an environment variable or a secrets manager rather than in a config file. Diagnostics use the same discovery-first, WebSocket-fallback logic as a runtime attach, so a bare root that connects is not reported as unreachable by the browser control API. The one signed-in-browser mode that has no cdpUrl at all is the Chrome extension relay, whose relay owns its loopback endpoint and drives real tabs with nobody at the computer.

On Diali

Diali hosts OpenClaw as a managed service. Every customer gets their own assistant on its own runtime instead of a seat in a shared pool. The runtime configuration is generated from your dashboard and written again at each release, so the browser block you set in the UI is the one the agent boots with. Everything the agent keeps sits on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Hosted OpenClaw on Diali describes the hosted runtime, and Diali pricing lists the plans.

• A node host relays browser actions to the machine that owns the browser.
• Once an action lands on a node, the rest of the task stays there.
• attachOnly stops a loopback CDP service being mistaken for a managed profile.