Playwright Browser Skill for OpenClaw

一个功能强大的浏览器自动化技能，基于 Playwright 构建，通过 MCP 协议为 OpenClaw 提供 101 个完整的浏览器操作能力。

中文文档 | English

✨ 特性

• 🌐 完整的浏览器控制 - 支持 Chromium、Firefox、WebKit
• 📱 设备模拟 - 模拟 iPhone、Android 等移动设备
• 🎯 智能选择器 - CSS、ARIA、文本、标签等多种选择方式
• 📸 截图和录制 - 页面截图、元素截图、PDF生成、视频录制
• 🌍 网络控制 - 请求拦截、响应模拟、离线模式
• 🔍 内容提取 - 文本、HTML、链接、属性等
• ⚡ 性能监控 - 页面性能指标、控制台日志
• 🎨 高级功能 - Cookie管理、LocalStorage、地理位置、时间控制

📦 安装

前置要求

• Node.js 18 或更高版本
• npm 或 yarn
• Windows 10/11, macOS, 或 Linux

安装方式

方式一：下载发行版（推荐，适合普通用户）

最简单的安装方式！ 下载预编译的独立包，无需构建，开箱即用。

Windows 用户：

1. 下载 playwright-browser-skill-windows-v2.1.0.zip
2. 解压到任意目录
3. 双击运行 auto-deploy.cmd（推荐）或 auto-deploy.ps1
4. 重启 OpenClaw，开始使用！

注意： 推荐使用 .cmd 文件，大部分 Windows 电脑默认禁止运行 PowerShell 脚本。

Mac/Linux 用户：

1. 下载 playwright-browser-skill-macos-linux-v2.1.0.tar.gz
2. 解压：tar -xzf playwright-browser-skill-macos-linux-v2.1.0.tar.gz
3. 进入目录并运行：chmod +x auto-deploy.sh && ./auto-deploy.sh
4. 重启 OpenClaw，开始使用！

发行版优势：

• ✅ 无需 npm install，节省时间
• ✅ 无需构建，开箱即用
• ✅ 包含完整依赖，离线可用
• ✅ 一键自动部署
• ✅ 适合非开发者用户

方式二：从源码安装（适合开发者）

# 克隆仓库
git clone https://github.com/91fapiao-cn/playwright-browser-skill.git
cd playwright-browser-skill

# 安装依赖
npm install

# 安装浏览器驱动
npm run install-browsers

# 构建项目
npm run build

🚀 使用方法

一键自动部署（推荐）

我们提供了跨平台的自动部署脚本，支持中英文版本，可以自动检测 OpenClaw 配置路径并完成所有配置：

Windows (PowerShell) - 推荐

# 中文版
.\auto-deploy.ps1

# 英文版
.\auto-deploy-en.ps1

# 跳过构建（如果已构建）
.\auto-deploy.ps1 -SkipBuild

# 指定自定义路径
.\auto-deploy.ps1 -OpenClawPath "C:\custom\path\.openclaw"

Windows (CMD)

REM 中文版
auto-deploy.cmd

REM 英文版
auto-deploy-en.cmd

REM 跳过构建
auto-deploy.cmd --skip-build

REM 指定自定义路径
auto-deploy.cmd --openclaw-path "C:\custom\path\.openclaw"

Mac/Linux

# 添加执行权限（首次使用）
chmod +x auto-deploy.sh auto-deploy-en.sh

# 中文版
./auto-deploy.sh

# 英文版
./auto-deploy-en.sh

# 跳过构建
./auto-deploy.sh --skip-build

# 指定自定义路径
./auto-deploy.sh --openclaw-path "/custom/path/.openclaw"

自动部署功能：

• ✅ 自动检测 OpenClaw 配置路径
• ✅ 自动构建项目（可选跳过）
• ✅ 自动部署 Skill 文件
• ✅ 自动配置 MCP 服务器
• ✅ 自动备份现有配置
• ✅ 支持自定义安装路径

📖 查看详细部署文档

手动部署

如果需要手动部署，请参考以下步骤：

1. 部署 Skill 文件

# Windows
copy skill-package\skills\SKILL.md %USERPROFILE%\.openclaw\skills\playwright-browser\

# macOS/Linux
cp skill-package/skills/SKILL.md ~/.openclaw/skills/playwright-browser-skill/

2. 配置 MCP 服务器

在 ~/.openclaw/settings/mcp.json 中添加：

{
  "mcpServers": {
    "playwright-browser": {
      "command": "node",
      "args": ["<项目路径>/dist/mcp-server.js"],
      "disabled": false,
      "autoApprove": ["browser_launch", "browser_goto", "browser_close"]
    }
  }
}

3. 重启 OpenClaw

重启 OpenClaw 以加载新的技能。

4. 在 OpenClaw 中启用技能

重启后，在 OpenClaw 对话中输入：

请使用 Playwright Browser Skill 技能来访问互联网和控制浏览器

或者直接测试：

使用 Playwright Browser Skill 启动浏览器并访问 example.com

这样 OpenClaw 就会知道使用这个技能来处理所有浏览器相关的任务。

📚 工具列表

浏览器管理 (8个)

• browser_launch - 启动浏览器
• browser_close - 关闭浏览器
• browser_new_page - 创建新页面
• browser_switch_page - 切换页面
• 更多...

页面导航 (4个)

• browser_goto - 导航到URL
• browser_go_back - 返回上一页
• browser_go_forward - 前进
• browser_reload - 刷新页面

元素交互 (12个)

• browser_click - 点击元素
• browser_fill - 填写表单
• browser_type - 输入文本
• browser_select - 选择下拉框
• 更多...

内容提取 (11个)

• browser_get_text - 获取文本
• browser_get_html - 获取HTML
• browser_get_links - 获取链接
• 更多...

查看完整工具列表

💡 使用示例

无头模式说明

浏览器支持两种运行模式：

有界面模式（headless: false） - 推荐用于调试和开发

browser_launch({ "headless": false })  // 显示浏览器窗口

无头模式（headless: true） - 推荐用于生产环境和自动化

browser_launch({ "headless": true })   // 后台运行，不显示窗口
// 或者省略参数，默认为无头模式
browser_launch()

无头模式优势：

• ⚡ 更快的执行速度
• 💾 更低的资源占用
• 🔒 适合服务器环境
• 🤖 适合批量自动化任务

基础网页访问

// 1. 启动浏览器（有界面模式，便于观察）
browser_launch({ "headless": false })

// 2. 访问网页
browser_goto({ "url": "https://example.com" })

// 3. 获取标题
browser_get_title()

// 4. 截图
browser_screenshot({ "path": "screenshot.png", "fullPage": true })

// 5. 关闭浏览器
browser_close()

无头模式自动化示例

// 无头模式运行，适合自动化任务
browser_launch({ "headless": true })
browser_goto({ "url": "https://example.com" })
browser_get_title()
browser_screenshot({ "path": "screenshot.png" })
browser_close()

表单填写

// 使用有界面模式便于调试
browser_launch({ "headless": false })
browser_goto({ "url": "https://example.com/login" })
browser_fill({ "selector": "#username", "value": "user@example.com" })
browser_fill({ "selector": "#password", "value": "password123" })
browser_click({ "selector": "button[type='submit']" })
browser_wait_for_selector({ "selector": ".dashboard" })
browser_close()

数据抓取

// 数据抓取推荐使用无头模式，速度更快
browser_launch({ "headless": true })
browser_goto({ "url": "https://example.com/products" })
browser_count({ "selector": ".product-item" })
browser_get_links()
browser_evaluate({ 
  "script": "Array.from(document.querySelectorAll('.price')).map(e => e.textContent)" 
})
browser_close()

查看更多示例

🧪 测试

# 运行所有测试
npm test

# 运行基础测试
npm run test:basic

# 运行高级测试
npm run test:advanced

# 运行交互测试
npm run test:interaction

# 运行MCP服务器测试
npm run test:mcp

📖 文档

• 配置指南 - 无头模式、浏览器选项等详细配置说明
• 自动部署指南 - 跨平台自动部署详细说明 | English
• 完整工具文档 - 所有101个工具的详细说明
• Windows 使用指南 - Windows 平台特定说明
• Mac/Linux 使用指南 - Mac 和 Linux 平台特定说明
• 快速开始指南 - 快速上手教程
• API 文档 - API 参考
• 架构说明 - 项目架构

🔧 开发

项目结构

playwright-browser-skill/
├── src/
│   ├── index.ts              # 核心功能实现
│   ├── mcp-server.ts         # MCP 服务器
│   └── tools-registry.ts     # 工具注册表
├── skill-package/
│   ├── skills/
│   │   └── SKILL.md  # 技能定义文件
│   └── settings/
│       └── mcp.json          # MCP 配置示例
├── test/                     # 测试文件
├── examples/                 # 示例代码
└── docs/                     # 文档

构建

# 开发模式（监听文件变化）
npm run dev

# 生产构建
npm run build

🌍 平台支持

平台	状态	说明
Windows 10/11	✅ 完全支持	已测试
macOS	✅ 完全支持	理论支持
Linux	✅ 完全支持	理论支持

🤝 贡献

欢迎贡献！请查看 贡献指南。

📝 更新日志

v2.1.0 (2026)

• 🚀 新增跨平台自动部署脚本
• 🔍 自动检测 OpenClaw 配置路径
• 💾 自动备份现有配置
• 📦 支持自定义安装路径
• 📚 完整的自动部署文档

v2.1.0 (2026)

• ✨ 新增 13 个高级工具（从88个增加到101个）
• 🎯 完善键盘鼠标控制（mouseDown, mouseUp, keyboardInsertText）
• 🔍 增强选择器功能（getByAltText, getByTitle）
• ⏱️ 完整时间控制（pauseClock, resumeClock）
• 📊 代码覆盖率支持（getCoverage, stopCoverage）
• 🌐 地理位置管理（clearGeolocation, touchscreenTap）
• ⏳ 高级等待功能（waitForFunction, waitForLoadState）
• 📈 总体覆盖率从69%提升到88%

v2.0.0 (2026)

• ✨ 新增 88 个完整的浏览器操作工具
• 📚 完整的中文文档
• 🪟 Windows 平台完整支持
• 🎯 智能选择器支持
• 📸 截图和录制功能
• 🌍 网络控制和模拟

v1.0.0

• 🎉 初始版本

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• Playwright - 强大的浏览器自动化框架
• OpenClaw - AI 助手平台
• Model Context Protocol - MCP 协议

📞 支持

• 📧 Email: 91fapiao@gmail.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

⭐ Star History

如果这个项目对你有帮助，请给它一个 Star！

---

Made with ❤️ for OpenClaw Community