OpenClaw Browser

Use this skill whenever a task needs a real browser under OpenClaw control.

This skill is for:

• opening websites in a managed browser
• operating pages with click/type/wait flows
• using browser snapshots and refs
• keeping browser sessions isolated by profile
• checking tabs, status, screenshots, requests, and errors

This skill is not for:

• simple web search that can be answered with search/fetch tools alone
• launching a random system browser window with no automation follow-up
• bypassing OpenClaw browser via standalone Playwright/Puppeteer unless the user explicitly asks

Core rule

When real browser automation is needed, prefer the OpenClaw-managed browser flow.

Do not default to:

• the system default browser
• ad-hoc Chrome launches
• standalone Playwright/Puppeteer
• another agent's shared browser profile

Interface priority

Prefer the highest-level OpenClaw browser surface available in the current environment:

1. Built-in browser tool when the runtime exposes it
2. openclaw browser CLI when the CLI is available

Official CLI form:

openclaw browser --browser-profile <profile> <subcommand> ...

The rule is not "use this exact shell string at all costs". The real rule is:

• stay inside the OpenClaw browser control surface
• use an explicit profile when possible
• do not fall back to a generic unmanaged browser flow

Local debugging note

The OpenClaw browser system is backed by a loopback control service. For normal work, use the browser tool or CLI first. Raw HTTP access is mainly for local debugging/integration, not the default operator workflow.

Built-in browser tool guidance

If the runtime exposes the OpenClaw browser tool, prefer it over shelling out.

Use the tool's browser operations with an explicit profile whenever possible.

Typical operation sequence is the same:

• status
• start
• open / navigate
• snapshot
• act (click/type/hover/select/drag)
• wait
• screenshot / requests / errors for debugging

The same profile rules in this skill still apply when using the built-in tool.

Profile policy

Default behavior

Always choose an explicit browser profile when possible:

--browser-profile <profile>

Preferred profile order

1. Current agent's dedicated configured profile
2. Task-specific profile explicitly requested by the user
3. Configured OpenClaw default profile
4. openclaw as the safe fallback

Profile rules

• Prefer a dedicated profile per agent / workflow / long-running task.
• Do not assume arbitrary profile names exist; prefer already-configured profiles.
• If no dedicated configured profile is known, use openclaw.
• Do not reuse another agent's profile unless the user explicitly wants shared state.
• Use user only when the task truly needs the user's signed-in browser session and the user is present to approve attach prompts.

Naming guidance for dedicated profiles

If the environment already supports multiple configured profiles, prefer names that identify ownership or scope, for example:

• agent-main
• agent-research
• shopify-ops
• session-foo

But do not invent and rely on a new profile name unless it is actually configured.

What OpenClaw browser is

OpenClaw browser is a managed browser system with:

• isolated browser profiles
• deterministic tab control
• snapshots that return action refs
• page actions such as click/type/hover/select/drag/wait
• screenshots, requests, console, errors, cookies, storage, and downloads

The browser is controlled through OpenClaw's local browser control service. The service is loopback-only and its port family is derived from gateway.port. Profile CDP ports are also managed by OpenClaw. Normally, do not hardcode raw ports for normal work; use the OpenClaw browser CLI/tool surface first.

Standard operating procedure

1) Check status

openclaw browser --browser-profile <profile> status

2) Start the browser if needed

openclaw browser --browser-profile <profile> start

3) Open the target page

openclaw browser --browser-profile <profile> open <url>

4) Take a snapshot before acting

openclaw browser --browser-profile <profile> snapshot

For dense pages, prefer interactive snapshots:

openclaw browser --browser-profile <profile> snapshot --interactive

5) Operate using refs from the snapshot

Examples:

openclaw browser --browser-profile <profile> click <ref>
openclaw browser --browser-profile <profile> type <ref> "hello" --submit
openclaw browser --browser-profile <profile> wait --text "Done"

6) Re-snapshot after navigation or large DOM changes

Refs are not stable across navigations. If an action fails or the page changed, take a fresh snapshot and use the new refs.

High-value commands

Browser / tabs

openclaw browser --browser-profile <profile> tabs
openclaw browser --browser-profile <profile> tab
openclaw browser --browser-profile <profile> focus <targetId>
openclaw browser --browser-profile <profile> close <targetId>

Inspection

openclaw browser --browser-profile <profile> snapshot --interactive
openclaw browser --browser-profile <profile> screenshot
openclaw browser --browser-profile <profile> console --level error
openclaw browser --browser-profile <profile> errors
openclaw browser --browser-profile <profile> requests --filter api

Actions

openclaw browser --browser-profile <profile> navigate <url>
openclaw browser --browser-profile <profile> click <ref>
openclaw browser --browser-profile <profile> type <ref> "text"
openclaw browser --browser-profile <profile> hover <ref>
openclaw browser --browser-profile <profile> select <ref> <value>
openclaw browser --browser-profile <profile> press Enter
openclaw browser --browser-profile <profile> wait "#main" --url "**/dashboard" --load networkidle

Decision rules

Use OpenClaw browser when

• the task needs a real logged-in or stateful browser session
• the task needs clicking, typing, file upload, downloading, or page verification
• the task needs deterministic tab control or screenshots
• the task should stay isolated in a dedicated browser profile

Use user profile only when

• the task truly requires the user's live signed-in browser state
• the user is at the computer to approve browser attach prompts
• the increased risk of acting in the user's real session is acceptable

Do not switch away from OpenClaw browser just because

• a page looks dynamic
• you want raw selectors
• another automation stack feels more familiar

First try the OpenClaw browser flow properly: status → start → open → snapshot → act → re-snapshot.

Debugging workflow

If something fails:

1. Run a fresh interactive snapshot.
2. Use the newest ref.
3. If targeting is unclear, use highlight or screenshot.
4. Inspect errors and requests.
5. If the page navigated or rerendered, re-snapshot.

Useful commands:

openclaw browser --browser-profile <profile> highlight <ref>
openclaw browser --browser-profile <profile> screenshot --full-page
openclaw browser --browser-profile <profile> errors --clear
openclaw browser --browser-profile <profile> requests --filter api --clear

Anti-patterns

Avoid these unless the user explicitly asks:

• launching a generic browser with no OpenClaw control path
• mixing one agent's task into another agent's profile
• assuming refs remain valid after navigation
• skipping snapshots and guessing actions blindly
• bypassing OpenClaw browser with standalone Playwright/Puppeteer for ordinary website work
• hardcoding raw browser control ports for normal usage when the CLI/tool already exposes the operation

Minimal quick-start template

PROFILE=<configured-profile-or-openclaw>

openclaw browser --browser-profile "$PROFILE" status
openclaw browser --browser-profile "$PROFILE" start
openclaw browser --browser-profile "$PROFILE" open https://example.com
openclaw browser --browser-profile "$PROFILE" snapshot --interactive

Success criteria

A correct OpenClaw browser workflow should usually show all of the following:

• browser status can be queried
• a target page can be opened in the selected profile
• snapshot returns page structure with refs or a readable page tree
• at least one follow-up action such as click/type/wait/screenshot works in the same profile

If these are true, the page is being controlled through the proper OpenClaw browser path.