# Send Browser Playwright Bridge to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "browser-playwright-bridge",
    "name": "Browser Playwright Bridge",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/swaylq/browser-playwright-bridge",
    "canonicalUrl": "https://clawhub.ai/swaylq/browser-playwright-bridge",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/browser-playwright-bridge",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=browser-playwright-bridge",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "scripts/browser-lock.sh",
      "scripts/playwright-template.js"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/browser-playwright-bridge"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/browser-playwright-bridge",
    "downloadUrl": "https://openagent3.xyz/downloads/browser-playwright-bridge",
    "agentUrl": "https://openagent3.xyz/skills/browser-playwright-bridge/agent",
    "manifestUrl": "https://openagent3.xyz/skills/browser-playwright-bridge/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/browser-playwright-bridge/agent.md"
  }
}
```
## Documentation

### Browser ↔ Playwright Bridge

OpenClaw's browser tool and external Playwright scripts cannot share the same CDP connection simultaneously. This skill provides a lock-based bridge: stop OpenClaw browser → run Playwright with the same Chrome profile (cookies/login intact) → release for OpenClaw to reconnect.

### Architecture

Chrome (CDP port)  ←  shared user-data-dir (~/.openclaw/browser/openclaw/user-data)
       ↕ mutually exclusive
┌──────────────┐    ┌──────────────────┐
│ OpenClaw     │ OR │ Playwright script │
│ browser tool │    │ (zero token cost) │
└──────────────┘    └──────────────────┘
       ↕ managed by browser-lock.sh

### Setup

Install Playwright in the workspace (once):

cd <workspace> && npm install playwright

Note: npx playwright install is NOT needed. Playwright connects to the existing Chrome via CDP — no local browser download required.

Copy scripts/browser-lock.sh to your workspace scripts/ directory:

chmod +x scripts/browser-lock.sh

### Discovering the CDP Port

The CDP port is dynamically assigned. Never hardcode it. Use discoverCdpUrl() (see below) or the shell equivalent in browser-lock.sh.

Shell one-liner:

ps aux | grep 'remote-debugging-port=' | grep -v grep | grep -o 'remote-debugging-port=[0-9]*' | head -1 | cut -d= -f2

Verify CDP is responding:

curl -s --max-time 1 http://127.0.0.1:<port>/json/version

### Run a Playwright script (recommended)

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

Default timeout: 300s. If the script exceeds it, the watchdog kills it and releases the lock.

This automatically: checks lock → stops OpenClaw browser → starts Chrome with CDP → runs script → cleans up → releases lock.

### Manual acquire/release

./scripts/browser-lock.sh acquire    # stop OpenClaw browser, start Chrome
node scripts/my-task.js              # run script(s)
./scripts/browser-lock.sh release    # kill Chrome, release lock

### Check status

./scripts/browser-lock.sh status

### Writing Playwright Scripts

Use scripts/playwright-template.js as starting point.

### CDP Discovery Helper

All scripts should use discoverCdpUrl() instead of hardcoding a port:

const { execSync } = require('child_process');

/**
 * Discover the CDP URL by inspecting Chrome process args.
 * Falls back to CDP_PORT env var, then probes common ports.
 */
function discoverCdpUrl() {
  // Method 1: extract from running Chrome process
  try {
    const ps = execSync(
      "ps aux | grep 'remote-debugging-port=' | grep -v grep",
      { encoding: 'utf8', timeout: 3000 }
    );
    const match = ps.match(/remote-debugging-port=(\\d+)/);
    if (match) return \`http://127.0.0.1:${match[1]}\`;
  } catch {}

  // Method 2: CDP_PORT env var
  if (process.env.CDP_PORT) {
    return \`http://127.0.0.1:${process.env.CDP_PORT}\`;
  }

  // Method 3: probe common ports
  // 18800 is the typical OpenClaw default; others are common CDP conventions
  const { execSync: probe } = require('child_process');
  for (const port of [18800, 9222, 9229]) {
    try {
      probe(\`curl -s --max-time 1 http://127.0.0.1:${port}/json/version\`, {
        encoding: 'utf8', timeout: 2000
      });
      return \`http://127.0.0.1:${port}\`;
    } catch {}
  }

  throw new Error('CDP port not found. Is Chrome running with --remote-debugging-port?');
}

### Script Pattern

const { chromium } = require('playwright');

async function main() {
  let browser;
  try {
    browser = await chromium.connectOverCDP(discoverCdpUrl());
  } catch (e) {
    console.error('❌ Cannot connect to Chrome CDP:', e.message);
    console.error('   Ensure browser-lock.sh acquire was called, or Chrome is running with --remote-debugging-port');
    process.exit(1);
  }

  const context = browser.contexts()[0]; // reuse existing context (cookies!)
  const page = await context.newPage();

  try {
    // ====== Your automation here ======
    await page.goto('https://example.com');
    console.log('Title:', await page.title());
    // ==================================
  } catch (e) {
    console.error('❌ Script error:', e.message);
    throw e;
  } finally {
    await page.close();     // close only your tab
    // NEVER call browser.close() — it kills the entire Chrome
  }
}

main().then(() => process.exit(0)).catch(e => {
  console.error('❌', e.message);
  process.exit(1);
});

Critical rules:

browser.contexts()[0] — reuse the existing context to inherit cookies/login
page.close() only — never browser.close()
Always process.exit(0) on success — Playwright keeps event loops alive otherwise
Wrap connectOverCDP in try-catch — fail fast with a clear message

### Workflow: Explore → Record → Replay

Explore — Use OpenClaw browser tool (snapshot/act) to figure out a new workflow
Record — Ask the agent to convert the steps into a Playwright script
Replay — Run via browser-lock.sh run — zero token cost, deterministic

### Cron / Scheduled Tasks

In cron tasks, call browser-lock.sh directly:

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

The lock file (/tmp/openclaw-browser.lock) prevents concurrent browser access. If a lock is stale (owner process dead), it auto-recovers.

### Troubleshooting

ProblemFixLock held by PID xxx./scripts/browser-lock.sh release to force-releasePlaywright connectOverCDP timeoutEnsure OpenClaw browser is stopped first (acquire does this)CDP port not foundChrome isn't running; call browser-lock.sh acquire firstopenclaw browser stop doesn't kill ChromeKnown issue; browser-lock.sh kills the process directlyScript hangs after completionAdd process.exit(0) at the endLogin expiredUse OpenClaw browser tool to re-login, then run scripts again

### Environment Variables

VarDefaultDescriptionCDP_PORTauto-discoverOverride CDP port (skips process detection)CHROME_BINauto-detectPath to Chrome/Chromium binaryHEADLESSautoSet true/1 to force headless; false/0 to force headed. Auto-detects on Linux without DISPLAY
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: swaylq
- Version: 1.1.0
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-04-30T16:55:25.780Z
- Expires at: 2026-05-07T16:55:25.780Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/browser-playwright-bridge)
- [Send to Agent page](https://openagent3.xyz/skills/browser-playwright-bridge/agent)
- [JSON manifest](https://openagent3.xyz/skills/browser-playwright-bridge/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/browser-playwright-bridge/agent.md)
- [Download page](https://openagent3.xyz/downloads/browser-playwright-bridge)