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/<verb>-<target>.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 <script.js> [args]    # acquire → run → release (300s default)
./scripts/browser-lock.sh run --timeout 120 <script> # custom timeout
./scripts/browser-lock.sh acquire                    # manual: stop OpenClaw browser, start Chrome
./scripts/browser-lock.sh release                    # manual: kill Chrome, release lock
./scripts/browser-lock.sh status                     # show state

Lock file: /tmp/openclaw-browser.lock. Stale locks auto-recover.

Anti-Detection Rules (MANDATORY)

All scripts must use human-like.js. See references/anti-detection.md for the full rule set.

Summary of critical rules:

Exception: setInputFiles() for file uploads is allowed (no human simulation possible), but add random delays before/after.

human-like.js API

Script Naming Convention

<verb>-<target>.js — e.g. publish-deviantart.js, read-inbox.js, reply-comment.js

Example Scripts

Production-tested scripts in scripts/examples/. Copy to your workspace scripts/browser/ and adapt.

Usage pattern:

# Copy examples to workspace
cp scripts/examples/*.js scripts/browser/
cp scripts/utils/human-like.js scripts/browser/utils/

# Run
./scripts/browser-lock.sh run scripts/browser/publish-deviantart.js image.png "Title" "Description" "tag1,tag2"
./scripts/browser-lock.sh run scripts/browser/read-xhs-comments.js --limit 10
./scripts/browser-lock.sh run scripts/browser/reply-xhs-comment.js 0 "回复文字"

All example scripts already use human-like.js for anti-detection.

Cron Integration

cd /path/to/workspace && ./scripts/browser-lock.sh run scripts/browser/task.js

Add jitterWait() at script start to randomize execution time.

Troubleshooting

Environment Variables