在 CoPaw/OpenClaw 中安装浏览器控制技能教程

作者：安娜 (Ana) | 日期：2026年3月6日
更新版本：1.0 | 适用：Copaw、OpenClaw 及其他类似AI代理平台

---

📋 目录

1. 概述
2. 方法一：自动安装 (推荐)
3. 方法二：手动安装 (本地压缩包)
4. 浏览器技能使用方法
5. 常见问题与解决
6. 可视浏览器配置
7. 高级功能

---

概述

在 CoPaw/OpenClaw 等AI代理平台中，browser-use 技能允许AI通过 Playwright 自动化控制浏览器，实现自动化测试、数据采集、网页交互等功能。

本教程涵盖两种安装方法：自动安装（最简单）和手动安装（当网络受限时）。

---

方法一：自动安装 (推荐)

1. 检查 Playwright 状态

# 在 Copaw 工作目录中执行
playwright --version

如果显示版本信息，说明 Playwright 已安装。如果提示未找到命令或需要更新：

2. 安装 Playwright

# 安装 Playwright
playwright install
# 或指定安装 chromium
playwright install chromium

3. 安装浏览器

# 安装 Chromium（推荐，轻量）
playwright install chromium
# 或安装完整 Chrome
playwright install chrome
# 或安装 Firefox
playwright install firefox
# 或全部安装
playwright install --with-deps

4. 验证安装

# 查看已安装的浏览器
playwright install --list
# 显示类似：
# chromium (1208) <version>
# firefox (138) <version>
# webkit (2024)

---

方法二：手动安装 (本地压缩包)

当网络受限或自动安装失败时，可使用本地压缩包手动安装。

1. 准备工作

1. 获取浏览器压缩包（如 chrome-win64.zip）
2. 确定压缩包路径，如：C:\Users\Administrator\Desktop\chrome-win64.zip

2. 创建目录结构

Playwright 期望的路径结构：

• 无头模式 (Headless)：C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64\
• 可视模式 (Headed)：C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1208\chrome-win64\

3. 解压安装步骤

方案 A：使用命令解压（推荐）

# 创建目录
md "C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64" 2>nul

# 解压压缩包
powershell -Command "Expand-Archive -Path 'C:\Users\Administrator\Desktop\chrome-win64.zip' -DestinationPath 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64' -Force"

# 检查文件结构
powershell -Command "Get-ChildItem 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64' -File -Name | Where-Object {$_ -match 'chrome'}"

方案 B：手动解压

1. 使用 WinRAR/7-Zip 解压到临时目录
2. 将解压的内容移动到目标目录
3. 确保 chrome.exe 在正确位置

4. 解决文件名问题

如果是普通的 Chrome 而不是 headless 版本，需要重命名：

# 复制并重命名为 Playwright 期望的文件名
powershell -Command "Copy-Item 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64\chrome.exe' 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64\chrome-headless-shell.exe' -Force"

5. 测试安装

# 在 Copaw 中使用 browser_use 工具
browser_use(action="start", headed=False)

---

浏览器技能使用方法

基本操作流程

# 1. 启动浏览器
browser_use(action="start", headed=False)  # 无头模式
# 或
browser_use(action="start", headed=True)   # 可视模式

# 2. 打开网页
browser_use(action="open", url="https://example.com")

# 3. 页面截图
browser_use(action="snapshot")  # 获取页面结构
browser_use(action="screenshot", path="screenshot.png", full_page=True)

# 4. 页面交互
browser_use(action="type", ref="e1", text="搜索内容")
browser_use(action="click", ref="e2", wait=1000)
browser_use(action="press_key", key="Enter")

# 5. 关闭浏览器
browser_use(action="stop")

常用动作说明

动作	参数	用途
start	headed=True/False	启动浏览器
open	url="URL"	打开网页
snapshot	-	获取页面元素结构
screenshot	path="路径"	截图保存
type	ref/selector, text	输入文本
click	ref/selector, wait	点击元素
press_key	key="键名"	按键操作
wait_for	wait_time=秒数	等待
stop	-	停止浏览器

元素定位方法

# 使用 ref（来自 snapshot）
browser_use(action="click", ref="e1")

# 使用 CSS 选择器
browser_use(action="click", selector=".submit-btn")

# 使用 XPath（某些情况下）
browser_use(action="click", selector="//button[@type='submit']")

---

常见问题与解决

问题 1：Browser start failed

错误信息：

Executable doesn't exist at C:\...\chrome-headless-shell.exe

解决方法：

# 1. 检查文件是否存在
dir "C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64\*.exe"

# 2. 如果没有 chrome-headless-shell.exe，复制重命名
powershell -Command "Copy-Item 'C:\...\chrome.exe' 'C:\...\chrome-headless-shell.exe' -Force"

问题 2：版本不匹配

错误信息：

Looking for version X but found Y

解决方法：

# 查看当前版本
playwright --version

# 重新安装指定版本浏览器
playwright install chromium@1208
# 或升级 Playwright
pip install --upgrade playwright

问题 3：启动速度慢

解决方法：

# 使用已有浏览器实例
browser_use(action="start", headed=False, timeout=30000)
# 或减少超时时间
browser_use(action="start", headed=False, timeout=15000)

---

可视浏览器配置

启动可视浏览器

# 普通可视模式（能看到窗口）
browser_use(action="start", headed=True)

# 如果需要特定分辨率
browser_use(action="resize", width=1200, height=800)

可视模式需要额外文件

如果启动失败，需要同时有：

1. 无头模式文件：chromium_headless_shell-1208\chrome-headless-shell-win64\
2. 可视模式文件：chromium-1208\chrome-win64\

创建方法：

# 创建可视模式目录
md "C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1208\chrome-win64" 2>nul

# 复制文件到可视模式目录
powershell -Command "Copy-Item -Recurse -Path 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium_headless_shell-1208\chrome-headless-shell-win64\*' -Destination 'C:\Users\Administrator\AppData\Local\ms-playwright\chromium-1208\chrome-win64\' -Force"

多页面/标签管理

# 打开新标签页
browser_use(action="open", url="https://example.com", page_id="tab2")

# 切换标签页
browser_use(action="tabs", tab_action="select", index=0)

# 列出所有标签页
browser_use(action="tabs", tab_action="list")

---

高级功能

1. 表单填写

# 单字段填写
browser_use(action="type", ref="email_input", text="user@example.com")

# 完整表单填写
fields = {
    "username": "testuser",
    "password": "password123",
    "email": "user@example.com"
}
browser_use(action="fill_form", fields_json=json.dumps(fields))

2. 文件上传

# 单文件上传
browser_use(action="file_upload", paths_json='["C:/file.txt"]')

# 多文件上传
browser_use(action="file_upload", paths_json='["C:/file1.txt", "C:/file2.jpg"]')

3. JavaScript 执行

# 执行简单JS
browser_use(action="eval", code="document.title")

# 执行复杂JS并获取返回值
browser_use(action="evaluate", code="window.scrollY", ref="e1")

4. 控制台和网络监控

# 获取控制台日志
browser_use(action="console_messages", level="error")

# 获取网络请求
browser_use(action="network_requests")

5. PDF 导出

# 导出当前页面为PDF
browser_use(action="pdf", path="page.pdf")

---

📝 总结

最佳实践

1. 普通使用：推荐自动安装，维护方便
2. 特定版本：手动安装可以控制特定浏览器版本
3. 可视模式：用于调试和演示，方便查看操作过程
4. 无头模式：用于自动化任务，效率更高

故障排除清单

• Playwright 是否正确安装（playwright --version）
• 浏览器是否安装（playwright install --list）
• 目录结构是否正确
• 文件名是否正确（特别是 headless vs headed）
• 权限是否足够（可读写 AppData 目录）
• 防火墙/杀毒软件是否阻止

环境要求

• 系统：Windows/Linux/macOS
• 内存：至少 2GB 可用内存
• 磁盘：至少 500MB 可用空间
• 权限：管理员/用户有文件夹写入权限

---

🔗 相关资源

1. Playwright 官方文档：https://playwright.dev/
2. Copaw 技能文档：查看 browser-use/SKILL.md
3. 浏览器版本查询：https://omahaproxy.appspot.com/
4. 问题反馈：在 Copaw GitHub Issues 中提问

---

📄 最后更新

日期	版本	更新内容
2026-03-06	1.0	初始版本，包含自动和手动安装方法

---

提示：如果在使用中遇到问题，可以先检查本文档的「常见问题」部分。如果问题仍未解决，可在 Copaw 社区提问或联系技术支持。

祝你使用愉快！🎨

---

以上教程说明完全通过AI助手实现