OpenClaw browser control

An assistant that can browse is only useful if the way it addresses a page is stable enough to script. OpenClaw exposes the same browser runtime three ways: an agent tool, a command line, and an optional loopback HTTP API for local integrations. The HTTP half is opt in, and until the relevant environment variable is set in the gateway service environment and the gateway is restarted, nothing listens on the loopback control port even though the tool and the command line keep working. The reference behind it is unusually blunt about what is volatile, what is enforced elsewhere and what breaks the moment the page navigates.

How you address things

• Tab handles are scoped to a browser host or node and to a profile, the suggested target identifier returned by a tab listing is the handle to prefer, labels and short tab handles are accepted, and raw target identifiers still work but remain volatile diagnostic values.
• Actions take a reference produced by a snapshot rather than a CSS selector, which is a deliberate restriction, and clicking by viewport coordinates exists for the case where a visible position is the only reliable target.
• Three snapshot styles coexist: an AI snapshot with native frame qualified references, a role snapshot resolved through an accessibility role lookup with an index for duplicates, and an accessibility tree snapshot whose references are only actionable when they can be bound through backend document identifiers.
• References are not stable across navigations, a batch stops after a committed main frame navigation including a same address reload and reports the action number it reached with a skipped count, and unknown or stale accessibility references fail fast instead of falling through to another selector.

Tab listings are observations, not authorization: every subsequent content read or action still enforces its own checks.

The batch runtime

The batch command runs an array of nested actions in a single call, so a plan can combine a wait, a click, some typing and an evaluation without a round trip for each step. What it accepts is a closed union of action kinds rather than arbitrary command line subcommands, which is why opening a page, navigating and taking a snapshot all sit outside the batch. References come from a snapshot taken before the batch starts, and any nested action that changes page state can invalidate the references that follow it, so state changing actions belong first or in a follow up batch after a fresh snapshot. A nested action may omit the target identifier or repeat the request level one, but an explicit nested identifier that resolves to a different tab is rejected before any action runs. By default the batch stops at the first failure and the results array ends there, while a continue flag makes it cover every action instead. Every entry reports its own outcome in order, a nested batch occupies one parent result that reports its first child error, and each batch applies its own stop on error setting independently of its parent. Any failed entry makes the command exit with a nonzero status, and the full ordered response stays available in machine readable form. Plans read from a file or from standard input are capped at one million bytes, and existing session profiles do not support batching at all.

Limits worth knowing

• Several features need Playwright, including navigation, actions, AI snapshots, selector based element screenshots and full browser PDF export, while accessibility snapshots, role snapshots over a per tab debugging socket and ordinary page screenshots still work without it.
• A live view token is minted once, is forty eight hexadecimal characters long, expires after sixty seconds and can be consumed a single time, with invalid, expired and reused tokens rejected before the socket upgrade.
• Stream frames are paced at roughly twenty frames per second, slow viewers skip frames instead of building a queue, navigation immediately retires the capture session, and a new capture session starts only after the address has been allowed.

Uploads are limited to the OpenClaw temporary uploads root and to managed inbound media, which the browser tool can address through a media reference or through a path relative to the sandbox, while traversal, symlinks, hardlinks and arbitrary local paths are rejected.

Why it refuses selectors

The design keeps choosing the stricter option. CSS selectors are not accepted for actions because a reference from a snapshot ties the action to something the agent actually observed, and a tab listing is described as an observation rather than a permission, with every later read or action checked again on its own. Blocked navigation returns an empty address and a reason instead of leaking the address or the lookup details. Evaluation and predicate waits run arbitrary JavaScript in the page context, prompt injection can steer that, and the reference says plainly that it can be switched off in configuration when it is not needed. The browser profile may hold logged in sessions, so it deserves the same care as any credential store, which is where tool approvals and prompt injection belong in the conversation. Remote debugging endpoints are powerful, the advice is to tunnel and protect them, and the host is meant to stay on loopback or a private network. Read together, the page is less an API tour than a list of the ways browser automation goes wrong.

On Diali

On Diali each customer runs their own assistant, and the runtime configuration is generated from the dashboard and replaced at each release, so configuration is not a file you maintain by hand. State lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Hosted OpenClaw on Diali covers the hosted shape and Diali pricing covers what it costs.

• Refs come from snapshots and die at navigation.
• The loopback HTTP API is off until you opt in.
• Evaluate runs page JavaScript, so treat it as a risk.