The agent-browser Skill Reference Guide for OpenClaw

The agent-browser skill is OpenClaw's most powerful browser automation tool. This is the complete reference guide covering every action, parameter, configuration option, and advanced pattern.

Overview

agent-browser gives AI agents programmatic control over web browsers. It abstracts complexity and provides a clean interface optimized for agents.

Key capabilities: Open pages, take snapshots, click elements, fill forms, execute JavaScript, take screenshots, handle uploads, manage cookies.

Profiles

openclaw Profile

Isolated agent-managed browser: { "profile": "openclaw" }

Use when starting fresh, no auth needed, testing, or scraping.

chrome Profile

Takeover existing Chrome: { "profile": "chrome" }

Requires Browser Relay extension. Use for authenticated sessions, sites detecting bots, or logged-in state.

Core Actions

open - Navigate to URL

{
  "action": "open",
  "url": "https://example.com",
  "profile": "openclaw",
  "timeoutMs": 30000,
  "loadState": "networkidle"
}

Parameters: url (required), profile, timeoutMs, loadState (load, domcontentloaded, networkidle)

snapshot - Capture DOM

{
  "action": "snapshot",
  "refs": "role",
  "labels": true,
  "maxChars": 50000
}

Parameters: refs (role or aria), labels, maxChars, depth, compact

Returns element references like e12, e13 and content structure.

act - Perform Actions

Common action kinds:

click:

{ "kind": "click", "ref": "e12", "button": "left" }

type:

{ "kind": "type", "ref": "e14", "text": "[email protected]" }

press:

{ "kind": "press", "key": "Enter" }

fill (multiple fields):

{
  "kind": "fill",
  "fields": [
    { "ref": "e14", "text": "email" },
    { "ref": "e15", "text": "password" }
  ]
}

wait:

{ "kind": "wait", "text": "Loading complete" }

Or wait for text to disappear:

{ "kind": "wait", "textGone": "Loading..." }

evaluate (run JavaScript):

{ "kind": "evaluate", "fn": "() => document.title" }

Other kinds: hover, drag, select, resize

screenshot - Capture Visual

{
  "action": "screenshot",
  "type": "png",
  "fullPage": true
}

upload - File Upload

{
  "action": "upload",
  "selector": "input[type=file]",
  "paths": ["/path/to/file.pdf"]
}

Advanced Patterns

Pattern 1: Keep targetId Consistent

When using refs from snapshot, pass targetId to actions:

const snapshot = await browser.snapshot();
await browser.act({
  kind: "click",
  ref: "e12",
  targetId: snapshot.targetId
});

Pattern 2: aria Refs for Stability

For cross-session automation:

const snapshot = await browser.snapshot({ refs: "aria" });
// aria refs persist across snapshots

Pattern 3: Multi-Step Forms

for (const step of steps) {
  const snapshot = await browser.snapshot();
  for (const field of step.fields) {
    await browser.act({ kind: "type", ...field });
  }
  const nextButton = findElement(snapshot, "Next");
  await browser.act({ kind: "click", ref: nextButton.ref });
}

Pattern 4: Screenshot on Error

try {
  await automateWorkflow();
} catch (error) {
  const screenshot = await browser.screenshot({ fullPage: true });
  await saveDebugScreenshot(screenshot);
  throw error;
}

Pattern 5: Infinite Scroll

while (true) {
  const snapshot = await browser.snapshot();
  const items = extractItems(snapshot.content);
  allItems.push(...items);
  
  await browser.act({
    kind: "evaluate",
    fn: "() => window.scrollTo(0, document.body.scrollHeight)"
  });
  
  const newHeight = await getPageHeight();
  if (newHeight === previousHeight) break;
  previousHeight = newHeight;
}

Performance Tips

Use networkidle sparingly (slow)

Batch actions with fill instead of multiple type

Minimize snapshots (only when needed)

Reuse browser instance

Security

Validate URLs before opening

Sanitize user input before typing

Clear cookies and storage after sensitive operations

Debugging

Enable debug mode:

export OPENCLAW_BROWSER_DEBUG=1

Take debug screenshots:

if (DEBUG) {
  await browser.screenshot({ type: "png" });
}

Print snapshot content to review elements.

Common Workflows

Form Submission

await browser.open({ url });
const snapshot = await browser.snapshot();

await browser.act({
  kind: "fill",
  fields: [
    { selector: "input[name=email]", text: "[email protected]" },
    { selector: "input[name=password]", text: "pass123" }
  ]
});

await browser.act({ kind: "click", selector: "button[type=submit]" });
await browser.act({ kind: "wait", text: "Welcome" });

Data Extraction

await browser.open({ url });
const snapshot = await browser.snapshot();
const data = parseData(snapshot.content);
return data;

Monitoring

while (true) {
  await browser.open({ url });
  const snapshot = await browser.snapshot();
  const status = checkStatus(snapshot.content);
  if (status.hasChanged) await alert();
  await sleep(60000);
}

Wrapping Up

The agent-browser skill is OpenClaw's Swiss Army knife for web automation. Master it, and your agents can interact with any web interface.

Start simple: navigate, snapshot, click. Build up to complex workflows. The patterns here handle most real-world scenarios.

The web is your agent's playground. Go automate.