🌐 浏览器自动化

使用 OpenClaw 的 browser 工具操控真实浏览器，像人一样浏览网页。

两种模式

核心操作流程

1. 打开页面

browser(action=open, targetUrl="https://example.com")

或导航当前标签页：

browser(action=navigate, targetUrl="https://example.com")

2. 读取页面内容（最常用）

browser(action=snapshot)

返回页面的 accessibility tree（结构化 DOM），包含：

• 每个元素的 ref（用于后续点击/输入）
• 文本内容、链接、按钮、输入框等

关键概念：ref snapshot 返回的每个可交互元素都有一个 ref（如 e12），后续操作用这个 ref 定位元素。

3. 点击

browser(action=act, request={kind: "click", ref: "e12"})

4. 输入文字

browser(action=act, request={kind: "type", ref: "e15", text: "要输入的内容"})

带回车提交：

browser(action=act, request={kind: "type", ref: "e15", text: "搜索词", submit: true})

5. 键盘操作

browser(action=act, request={kind: "press", key: "Enter"}) browser(action=act, request={kind: "press", key: "Escape"}) browser(action=act, request={kind: "press", key: "Tab"})

6. 截图

browser(action=screenshot) # 可视区域 browser(action=screenshot, fullPage=true) # 全页面

7. 导出 PDF

browser(action=pdf)

8. 标签页管理

browser(action=tabs) # 列出所有标签页 browser(action=open, targetUrl="...") # 新开标签页 browser(action=focus, targetId="xxx") # 切换标签页 browser(action=close, targetId="xxx") # 关闭标签页

典型工作流

流程 A：读取网页内容

1. browser(action=open, targetUrl=URL) → 打开页面 2. browser(action=snapshot) → 获取页面结构 3. 从 snapshot 提取所需信息 → 返回给用户

流程 B：搜索操作

1. browser(action=open, targetUrl="https://google.com") 2. browser(action=snapshot) → 找到搜索框 ref 3. browser(action=act, {kind:"type", ref:REF, text:"关键词", submit:true}) 4. browser(action=snapshot) → 读取搜索结果

流程 C：需要登录的页面（chrome 模式）

1. browser(action=snapshot, profile="chrome") → 读取已登录的页面 注意：需要用户先在 Chrome 中登录，并用扩展 attach 到对应标签页

流程 D：填写表单

1. browser(action=snapshot) → 识别所有表单字段 2. browser(action=act, {kind:"type", ref:NAME_REF, text:"张三"}) 3. browser(action=act, {kind:"type", ref:EMAIL_REF, text:"[email protected]"}) 4. browser(action=act, {kind:"click", ref:SUBMIT_REF}) → 提交 5. browser(action=snapshot) → 确认提交结果

进阶操作

下拉选择

browser(action=act, request={kind: "select", ref: "e20", values: ["option1"]})

悬停

browser(action=act, request={kind: "hover", ref: "e8"})

拖拽

browser(action=act, request={kind: "drag", startRef: "e5", endRef: "e10"})

执行 JS

browser(action=act, request={kind: "evaluate", fn: "document.title"})

处理弹窗

browser(action=dialog, accept=true) # 点击确定 browser(action=dialog, accept=false) # 点击取消 browser(action=dialog, accept=true, promptText="输入内容") # 输入型弹窗

最佳实践

1. 先 snapshot 再操作：每次操作前都 snapshot 确认当前页面状态和 ref
2. 保持 targetId：snapshot 返回的 targetId 传入后续操作，确保操作同一标签页
3. 等页面加载：打开新页面后，snapshot 前等页面加载完成
4. 优先 openclaw 模式：除非需要登录态，否则用隔离浏览器更安全
5. snapshot 而非 screenshot：需要内容用 snapshot（结构化文本），需要视觉用 screenshot（图片）
6. refs="aria" 更稳定：跨多次 snapshot 保持一致的引用，用 refs="aria"

常见问题

Q: 页面是 SPA（React/Vue），snapshot 拿不到内容？ A: SPA 页面需要等 JS 渲染完成。打开后稍等再 snapshot，或检查 snapshot 内容是否完整。

Q: 被网站检测为机器人怎么办？ A: 用 chrome 模式（真实浏览器环境），操作频率拟人化，避免高频自动化。

Q: 如何处理验证码？ A: 用 chrome 模式让用户手动完成验证码，再让 Agent 继续后续操作。

安全提醒

• chrome 模式 = 暴露登录态：Agent 能访问你当前标签页的所有内容
• 建议为 Agent 创建专门的 Chrome Profile
• 不要在公网暴露 relay 端口
• 敏感操作（转账、发布等）让 Agent 暂停，人工确认后继续

配置（可选）

在 ~/.openclaw/openclaw.json 中：

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    "profiles": {
      "openclaw": { "cdpPort": 18800 },
      "chrome": {}
    }
  }
}

参考文档

• Browser 工具文档
• Chrome 扩展指南
• CLI 命令参考