浏览器 ↔ Playwright 桥接机制

OpenClaw 的浏览器工具与外部 Playwright 脚本无法同时共享同一个 CDP 连接。本能力提供基于锁的桥接方案：先暂停 OpenClaw 浏览器 → 使用相同的 Chrome 用户配置（保留 Cookie 与登录态）运行 Playwright → 完成后释放控制权，使 OpenClaw 可重新连接。

架构

Chrome（CDP 端口）  ← 共享 user-data-dir（~/.openclaw/browser/openclaw/user-data）
       ↕ 互斥访问
┌──────────────┐    ┌──────────────────┐
│ OpenClaw     │ OR │ Playwright 脚本  │
│ 浏览器工具   │    │ （零 token 成本） │
└──────────────┘    └──────────────────┘
       ↕ 由 browser-lock.sh 统一管理

初始化配置

1. 在 workspace 中安装 Playwright（仅需一次）：

cd  && npm install playwright

注意：无需执行 npx playwright install。Playwright 通过 CDP 直接连接已存在的 Chrome 实例 —— 无需下载本地浏览器。

2. 将 scripts/browser-lock.sh 复制到你的 workspace 的 scripts/ 目录中：

chmod +x scripts/browser-lock.sh

发现 CDP 端口

CDP 端口为动态分配，切勿硬编码。请使用下方介绍的 discoverCdpUrl() 函数，或 browser-lock.sh 中提供的等效 Shell 命令。

Shell 一行命令获取端口：

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

验证 CDP 是否响应：

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

使用方式

运行 Playwright 脚本（推荐）

./scripts/browser-lock.sh run scripts/my-task.js [args...]
./scripts/browser-lock.sh run --timeout 120 scripts/my-task.js  # 自定义超时时间

默认超时：300 秒。若脚本执行超时，看门狗（watchdog）将终止该进程并自动释放锁。

该命令会自动完成以下流程：检查锁状态 → 暂停 OpenClaw 浏览器 → 启动带 CDP 支持的 Chrome → 执行脚本 → 清理资源 → 释放锁。

手动加锁 / 解锁

./scripts/browser-lock.sh acquire    # 暂停 OpenClaw 浏览器，启动 Chrome
node scripts/my-task.js              # 执行脚本
./scripts/browser-lock.sh release    # 终止 Chrome，释放锁

查看当前状态

./scripts/browser-lock.sh status

编写 Playwright 脚本

建议以 scripts/playwright-template.js 为起点开始开发。

CDP 发现辅助函数

所有脚本均应使用 discoverCdpUrl() 获取 CDP 地址，禁止硬编码端口：

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

/**
 * 通过解析 Chrome 进程参数发现 CDP URL。
 * 若失败，则回退至环境变量 CDP_PORT；再失败则探测常见端口。
 */
function discoverCdpUrl() {
  // 方法 1：从正在运行的 Chrome 进程中提取
  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 {}

  // 方法 2：读取 CDP_PORT 环境变量
  if (process.env.CDP_PORT) {
    return `http://127.0.0.1:${process.env.CDP_PORT}`;
  }

  // 方法 3：探测常见端口
  // 18800 是 OpenClaw 默认端口；其余为通用 CDP 约定端口
  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 端口。请确认 Chrome 是否以 --remote-debugging-port 参数启动？');
}

脚本模板结构

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

async function main() {
  let browser;
  try {
    browser = await chromium.connectOverCDP(discoverCdpUrl());
  } catch (e) {
    console.error('❌ 无法连接 Chrome CDP：', e.message);
    console.error('   请确保已调用 browser-lock.sh acquire，或 Chrome 已以 --remote-debugging-port 启动');
    process.exit(1);
  }

  const context = browser.contexts()[0]; // 复用现有上下文（保留 Cookie！）
  const page = await context.newPage();

  try {
    // ====== 在此处添加你的自动化逻辑 ======
    await page.goto('https://example.com');
    console.log('标题：', await page.title());
    // ======================================
  } catch (e) {
    console.error('❌ 脚本执行错误：', e.message);
    throw e;
  } finally {
    await page.close();     // 仅关闭当前标签页
    // 切勿调用 browser.close() —— 否则会终止整个 Chrome 进程
  }
}

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

关键规则：

• browser.contexts()[0] —— 复用已有上下文，继承 Cookie 与登录态
• 仅调用 page.close() —— 严禁调用 browser.close()
• 成功时务必显式调用 process.exit(0) —— 否则 Playwright 会持续持有事件循环
• 对 connectOverCDP 必须包裹 try-catch —— 快速失败并输出清晰错误信息

工作流：探索 → 录制 → 回放

1. 探索 —— 使用 OpenClaw 浏览器工具（snapshot/act）梳理新业务流程
2. 录制 —— 请求 Agent 将操作步骤转换为 Playwright 脚本
3. 回放 —— 通过 browser-lock.sh run 执行 —— 零 token 成本、确定性高

Cron / 定时任务

在 Cron 任务中，请直接调用 browser-lock.sh：

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

锁文件（/tmp/openclaw-browser.lock）防止并发浏览器访问。若锁处于“陈旧”状态（持有者进程已退出），系统将自动恢复。

故障排查

环境变量