浏览器自动化

wesclaw 通过集成 Playwright 提供浏览器自动化能力，让 AI 能够帮你操作网页、填写表单、抓取信息等。

概述

wesclaw 提供三种浏览器能力，按使用场景分层：

能力	说明	典型场景
Headless Browser	无头浏览器（服务端 chromedp）	匿名网页抓取、截图
Playwright	用户浏览器自动化	需要登录态的操作、表单填写
Desktop Agent	桌面自动化	系统级操作、剪贴板、截屏

本文重点介绍 Playwright 集成，这是最常用的浏览器自动化方式。

Playwright 集成说明

什么是 Playwright

Playwright 是 Microsoft 开源的浏览器自动化工具。wesclaw 通过 Playwright MCP 协议与用户浏览器交互，让 AI 能够：

打开和导航网页
点击按钮、链接
填写输入框和表单
选择下拉选项
截取网页截图
提取页面内容
等待页面加载和元素出现

工作原理

wesclaw AI → Playwright MCP 子进程 → 用户浏览器

wesclaw 启动一个 Playwright MCP 子进程
子进程通过 MCP 协议接收 AI 的操作指令
子进程控制用户的浏览器执行具体操作
操作结果通过 MCP 协议返回给 AI

启用 Playwright

在设置 → 浏览器自动化 中启用 Playwright 集成。

启用后，AI 在对话中可以调用浏览器相关工具：

用户：帮我打开 GitHub 看一下我的通知

AI：好的，我来为你打开 GitHub 通知页面。
  [调用 browser_navigate: https://github.com/notifications]
  [等待页面加载...]
  [调用 browser_snapshot: 获取页面内容]
  
  你有 3 条未读通知：
  1. PR #123 被合并了
  2. Issue #456 有新评论
  3. 你被 @提及 了

用户浏览器模式

两种浏览器模式

模式	说明	适用场景
Headless	无界面浏览器，在后台运行	简单的网页抓取、无需登录
User	连接你的真实浏览器	需要登录态、Cookie、认证

User 模式的优势

用户浏览器模式（User Mode）是 wesclaw 的推荐方式：

保留登录态 — 你已经登录的网站，AI 可以直接操作
保留 Cookie — 不需要重复登录
保留扩展 — 浏览器已安装的扩展正常工作
所见即所得 — 你可以实时看到 AI 的操作

User 模式工作流程

AI 发起浏览器操作
你的浏览器中打开一个新标签页
AI 在该标签页中执行操作
你可以实时观看操作过程
如需你介入（如登录），AI 会暂停等待（HITL）
操作完成后，标签页保留供你查看

常用浏览器操作

表单填写

AI 可以自动填写表单：

用户：帮我在 Jira 创建一个 Bug 工单

AI：好的，我来帮你创建。
  [browser_navigate: https://jira.example.com/create]
  [browser_fill: 标题输入框 → "登录页面500错误"]
  [browser_fill: 描述输入框 → "用户在..."]
  [browser_select: 优先级 → "高"]
  [browser_click: 创建按钮]
  
  Bug 工单已创建：PROJ-789

信息提取

AI 可以从网页提取结构化信息：

用户：帮我看看 Amazon 上这个产品的评价

AI：[browser_navigate: https://amazon.com/dp/XXXXX]
  [browser_snapshot: 获取页面内容]
  
  商品评价摘要：
  - 评分：4.5/5 (2,345 条评价)
  - 好评焦点：质量好、发货快
  - 差评焦点：包装简陋

截图

AI 可以对网页截图：

用户：帮我截图保存这个设计稿

AI：[browser_navigate: https://figma.com/file/xxx]
  [browser_screenshot]
  
  已截取页面截图并保存。

需要人工介入的场景

某些操作需要你亲自完成，AI 会通过 HITL 机制暂停等待：

登录操作

AI：我需要你在浏览器中登录 GitHub。
  
  🔒 请在浏览器中完成登录
  完成后点击"继续"
  
  [继续] [取消]

CAPTCHA 验证

AI：页面出现了人机验证，需要你来完成。
  
  🔒 请在浏览器中完成验证码
  完成后点击"继续"
  
  [继续] [取消]

支付确认

AI 不会自动执行支付操作。遇到支付页面时会暂停等待你确认。

安全限制

治理策略限制

wesclaw 的治理系统（Governance）会对浏览器操作施加限制：

治理模式	浏览器操作限制
`open`（开放）	允许大部分操作，审计记录
`locked`（锁定）	严格限制，敏感操作需审批

DenyPaths 限制

可以在 Cell 配置中设置 DenyPaths，限制 AI 不能访问特定路径或 URL 模式。

NetworkPolicy 限制

通过 NetworkPolicy 控制浏览器的网络访问：

策略	说明
`allow`	允许所有网络请求
`internal_only`	仅允许内网请求
`deny`	禁止所有网络请求

浏览器操作的安全原则

AI 不会自动输入密码 — 涉及密码的操作需要你手动完成
AI 不会自动支付 — 支付操作需要你明确确认
AI 不会访问敏感页面 — 如银行网站、管理后台等需要配置允许
所有操作可追溯 — 浏览器操作记录在 Run 追踪中可查看

Headless Browser（无头浏览器）

适用场景

批量网页抓取
定时截图监控
不需要登录态的自动化任务

与 Playwright 的区别

特性	Headless Browser	Playwright
运行位置	服务端（chromedp）	用户浏览器
登录态	无	有（使用你的 Cookie）
可见性	不可见	用户可观看操作过程
性能	较快	取决于用户浏览器
适用场景	匿名抓取	需要认证的操作

故障排查

Playwright 连接失败

确认已安装 Playwright 浏览器扩展（如需要）
确认浏览器版本兼容
检查是否有防火墙阻止 WebSocket 连接

操作超时

网络慢的页面可能导致操作超时
可以在配置中调整超时时间
复杂页面建议分步操作

页面内容无法识别

某些动态加载的内容可能需要等待
iframe 内的内容可能无法直接访问
高度定制化的组件可能需要特殊处理

SaaS 版差异

在 SaaS 云端版本中：

浏览器操作在服务端执行
不使用用户浏览器，而是使用服务端 Headless Browser
无法访问需要登录态的网站（除非提供凭证）
浏览器操作受 RegulatedPreset 治理策略限制

下一步

人机交互审批 — 了解浏览器操作中的 HITL 等待机制
对话运行周期 — 了解浏览器操作在 Run 中的位置
可观测性 — 查看浏览器操作的追踪记录