Browser Automation Ultra

---

name: browser-automation-ultra description: "Zero-token browser automation via Playwright scripts with CDP lock management and human-like interaction. Use when: (1) automating any browser-based workflow (publish, login, scrape, fill forms), (2) reducing token cost by converting browser-tool explorations into replayable scripts, (3) avoiding CDP port conflicts between OpenClaw browser and Playwright, (4) needing anti-detection/human-like mouse/keyboard behavior for platforms with bot detection. NOT for: simple URL fetches (use web_fetch instead), tasks that don't need a real browser session."

---

Browser Automation Ultra

Explore → Record → Replay → Fix. Convert expensive browser-tool interactions into zero-token Playwright scripts that reuse OpenClaw's Chrome session (cookies/login intact).

Prerequisites

Install Playwright (once per machine):

npm install -g playwright
or in workspace: npm init -y && npm install playwright

No browser download needed — scripts connect to OpenClaw's existing Chrome via CDP.

Architecture

Chrome user-data: ~/.openclaw/browser/openclaw/user-data
       ↕ shared cookies/login (mutually exclusive CDP)
┌──────────────┐    ┌──────────────────┐
│ browser tool │ OR │ Playwright script │
│ (explore)    │    │ (zero token)      │
└──────────────┘    └──────────────────┘
       ↕ managed by browser-lock.sh

Only one CDP client can connect at a time. browser-lock.sh handles the mutex.

Setup

1. Copy scripts/browser-lock.sh to your workspace scripts/ directory 2. Copy scripts/utils/human-like.js to your workspace scripts/browser/utils/ 3. chmod +x scripts/browser-lock.sh 4. Create scripts/browser/ for your automation scripts

Core Workflow

1. Explore (browser tool, costs tokens)

Use the OpenClaw browser tool (snapshot/act) to figure out a workflow. Note selectors, page flow, key waits.

2. Record (write a Playwright script)

Convert steps into a script. Save to scripts/browser/-.js. Use the template pattern:

const { chromium } = require('playwright');
const { humanDelay, humanClick, humanType, humanThink, humanBrowse } = require('./utils/human-like');
function discoverCdpUrl() {
  try {
    const { execSync } = require('child_process');
    const ps = execSync("ps aux | grep 'remote-debugging-port' | grep -v grep", { encoding: 'utf8' });
    const match = ps.match(/remote-debugging-port=(\d+)/);
    return http://127.0.0.1:${match ? match[1] : '18800'};
  } catch { return 'http://127.0.0.1:18800'; }
}
async function main() {
  const browser = await chromium.connectOverCDP(discoverCdpUrl());
  const context = browser.contexts()[0]; // reuse existing context (cookies/login)
  const page = await context.newPage();
  try {
    // automation here — use human-like functions
    await page.goto('https://example.com', { waitUntil: 'networkidle', timeout: 30000 });
    await humanBrowse(page); // simulate looking at the page
    await humanClick(page, 'button.submit');
    await humanType(page, 'input[name="title"]', 'Hello World');
  } finally {
    await page.close(); // NEVER browser.close() — kills entire Chrome
  }
}
main().then(() => process.exit(0)).catch(e => { console.error('❌', e.message); process.exit(1); });

3. Replay (zero tokens)

./scripts/browser-lock.sh run scripts/browser/my-task.js [args]
./scripts/browser-lock.sh run --timeout 120 scripts/browser/my-task.js

4. Fix (on error)

1. Read script error output 2. Re-explore the failing step with browser tool (snapshot) to check current UI 3. Update script with corrected selectors/logic 4. Retry

Never guess fixes blindly. Always re-explore the actual page state.

browser-lock.sh

Manages CDP mutex between OpenClaw browser and Playwright scripts.

./scripts/browser-lock.sh run  [args]    # acquire → run → release (300s default)
./scripts/browser-lock.sh run --timeout 120