Browser agent tools

The single browser tool, its actions, and the arguments an agent passes

The agent gets one tool for browser automation:

browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act/requests/errors/text/emulate

How it maps:

browser snapshot returns a stable UI tree (AI or ARIA).
Snapshot query keeps lines containing all whitespace-separated query tokens, ignoring case. Matching lines retain element refs; the result reports the match count and respects maxChars. It searches the returned snapshot, so increase the snapshot scope if the source was truncated.
browser requests reads the collected network log. Optional filter matches a substring in the URL or resource type; limit keeps the most recent entries (default 50). Results report total matching collected requests and returned entries; the output budget may reduce that count further. clear=true clears the entire collected log after reading, including entries omitted by filtering or limits.
browser errors reads collected page errors. limit keeps the most recent entries (default 50). Results report total collected errors and returned entries; the output budget may reduce that count further. clear=true clears the entire collected log after reading, including entries omitted by limits. Page errors remain untrusted external content.
browser text extracts visible prose using the first explicit selector match, otherwise the first article, main, or body. maxChars must be positive; it defaults to and cannot exceed 40,000 characters. The tool's output budget may truncate further. Page text remains untrusted external content.
browser emulate applies one or more of device (a Playwright device name), colorScheme (dark, light, no-preference, or none to clear), timezoneId, and locale. Settings apply in that order and return an applied list; they are not atomic. These four actions support local and node targets but not Chrome MCP existing-session profiles.
browser navigate also returns the loaded page's snapshot inline (efficient interactive tier, so the payload stays compact and bounded), so the agent does not need a follow-up snapshot call. Batch act results that report a cross-document navigation include the same fresh page state. Navigations that resolve to a download skip it.
browser act uses the snapshot ref IDs to click/type/drag/select. When a captured control disappears, its bound ref fails. Take a new snapshot before retrying the action.
browser screenshot captures pixels (full page, element, or labeled refs).
If a screenshot times out while the browser is still capturing or restoring page settings, further screenshots, resizing, and device changes on that tab return a recovery error. Retry after the capture finishes. If it stays stuck, close and reopen the affected tab; other tabs remain available.
browser doctor checks Gateway, plugin, profile, browser, and tab readiness.
browser accepts:
- profile to choose a named browser profile (openclaw, chrome, or remote CDP).
- target (sandbox | host | node) to select where the browser lives.
- Omit target and node to use configured routing. When a sandbox browser bridge is available, managed profiles use it. Without a sandbox bridge, an enabled gateway.nodes.browser.node pin selects that node, including in manual routing mode; an unavailable pinned node fails rather than switching to the host.
- Without a pin, automatic routing prefers an available host browser and can select a single connected browser node when node routing is available. Manual routing without a pin and disabled node routing use the host. Standalone runs use the host unless a Gateway or node route is selected; see Remote and hosted browsers.
- Explicit target="host" selects the Gateway host and bypasses configured node routing. Explicit target="node" or a node selector requests node routing; gateway.nodes.browser.mode="off" rejects it.
- In sandboxed sessions, both host and node control require agents.defaults.sandbox.browser.allowHostControl=true. Existing-session profiles cannot use the sandbox browser. When a bridge is available, they use the host unless a node is explicitly selected, subject to the same host-control policy.
- With an enabled node pin, no sandbox bridge, and host control allowed, the tool description identifies the configured node as the default. Other configurations retain the existing tool description; the guidance does not depend on live node connectivity.

This keeps the agent deterministic and avoids brittle selectors.

Example agent tool arguments (reuse a targetId from tabs or open):

{ "action": "requests", "targetId": "t1", "filter": "fetch", "limit": 20, "clear": true }

{ "action": "text", "targetId": "t1", "selector": "article", "maxChars": 6000 }

{ "action": "snapshot", "targetId": "t1", "query": "sign in", "maxChars": 4000 }

For a Browser dashboard, use its stable widget name instead of a tab ID:

{ "action": "snapshot", "dashboard": "service-status", "refs": "aria" }

The dashboard selector applies to the current session. Create the saved browser:dashboard widget with the dashboard tool first; its props choose the URL and optional managed profile. browser resolves the same page shown in the dashboard for snapshots, clicks, typing, and navigation. Do not combine the selector with an explicit profile, node, or target ID. open explicitly resumes a stopped dashboard, and close stops its running browser. Other actions leave a stopped dashboard stopped. Ordinary raw-tab closing cannot close a dashboard-owned tab.

{
  "action": "emulate",
  "targetId": "t1",
  "device": "iPhone 15",
  "colorScheme": "dark",
  "timezoneId": "America/New_York",
  "locale": "en-US"
}