浏览器工具

OpenClaw 内置一个专属浏览器工具，由 OpenClaw 直接管理 Chromium 浏览器进程，支持多 Profile、多实例，可用于网页自动化、登录态持久化等场景。

基础配置

{
  browser: {
    enabled: true,          // 默认开启
    defaultProfile: "chrome", // 默认使用 "chrome" profile
  },
}

核心操作

基础控制

操作	说明
status	查看浏览器状态
start	启动浏览器
stop	停止浏览器
tabs	列出所有标签页
open	打开新标签
focus	聚焦标签
close	关闭标签

内容获取

操作	说明
snapshot	获取页面快照（ai 模式或 aria 无障碍树）
screenshot	截图（返回图片块 + MEDIA:<path>）
navigate	跳转到 URL
console	读取控制台输出

页面交互

操作	说明
act	UI 操作：click/type/press/hover/drag/select/fill/resize/wait/evaluate
upload	上传文件
dialog	处理浏览器弹窗
pdf	将页面保存为 PDF

Profile 管理

操作	说明
profiles	列出所有 profile 及状态
create-profile	创建新 profile（自动分配端口或指定 cdpUrl）
delete-profile	停止浏览器，删除用户数据和配置（仅本地）
reset-profile	清除 profile 端口上的孤立进程

标准使用流程

1. browser → status（确认浏览器状态）或 start（启动）
2. navigate → 跳转到目标页面
3. snapshot（ai 模式）→ 获取可交互元素引用
4. act → 执行操作（需要 snapshot 返回的 ref）
5. screenshot → 如需视觉确认

Snapshot 模式说明

• ai（默认，需安装 Playwright）：返回 AI 优化的页面快照，元素引用为数字（如 12）
• aria：返回无障碍树结构，元素引用为 e12 格式

act 操作需要 snapshot 返回的 ref 值：

{ "action": "act", "acts": [{ "action": "click", "ref": 12 }] }

提示：避免在 act 中频繁使用 wait，除非确实没有可靠的 UI 状态可以等待。

多 Profile 使用

每个 Profile 是一个独立的浏览器实例，拥有独立的登录态和 Cookie。端口范围 18800-18899（最多约 100 个 Profile）。

{
  browser: {
    defaultProfile: "work",  // 默认使用 work profile
  },
}

在工具调用时指定 Profile：

{ "action": "start", "profile": "personal" }

Profile 命名规则：只能用小写字母、数字和连字符，最多 64 个字符。

执行目标（target）

• sandbox：在沙箱中运行（若已配置）
• host：在 Gateway 宿主机上运行
• node：在配对的 macOS/iOS 节点上运行

若已连接一个能运行浏览器的 Node，工具会自动路由过去（除非用 target 参数固定）。

远程浏览器

通过 cdpUrl 连接外部浏览器（如远程 Chromium 实例）。远程 Profile 只能附加（attach），不能 start/stop/reset。

安全提醒

• 网页抓取场景建议使用 web_fetch 工具（轻量），JS 密集页面再用 browser
• 对于不需要持久登录态的场景，用 web_fetch 代替 browser 更省资源
• 第三方网站的 cookie/session 数据都存储在 Profile 中，注意 Profile 隔离