11.11 浏览器控制

OpenClaw 提供了强大的浏览器控制工具,支持两种模式:openclaw 托管模式(隔离的 Chromium 配置文件)和 chrome 模式(通过扩展中继到系统浏览器)。可以将其视为一个独立的、仅供代理使用的浏览器。

概述

浏览器工具是 loopback-only 的、经过沙箱隔离的,永远不会触及个人配置文件。所有访问都通过网关的身份验证或节点配对流动。这个浏览器不是您的日常浏览器,而是一个安全、隔离的操作界面。

启用浏览器工具

在 ~/.openclaw/openclaw.json 中设置 "browser.enabled": true:

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw"
  }
}

如果出现"Browser disabled"提示,请启用浏览器并重启网关。默认配置文件是 "chrome";使用 "openclaw" 可切换到托管模式。

浏览器操作

生命周期管理

• status - 检查浏览器状态
• start - 启动浏览器
• stop - 停止浏览器
• tabs - 列出所有标签页
• tab new/select/close - 管理标签页
• open - 打开 URL
• focus - 聚焦标签页
• close - 关闭标签页

页面检查

• screenshot - 截取全页面或特定元素的屏幕截图
• snapshot - 获取页面快照(AI/ARIA/efficient/interactive 格式)
• console - 查看控制台日志
• errors - 查看错误信息
• requests - 查看网络请求
• pdf - 导出为 PDF
• responsebody - 获取响应体内容

交互操作

• navigate - 导航到 URL
• resize - 调整窗口大小
• click - 点击元素
• type - 输入文本
• press - 按键
• hover - 鼠标悬停
• scrollintoview - 滚动到元素
• drag - 拖拽元素
• select - 选择下拉选项
• download - 下载文件
• waitfordownload - 等待下载完成
• upload - 上传文件
• fill - 填充表单
• dialog - 处理对话框
• wait - 等待
• evaluate - 执行 JavaScript
• highlight - 高亮元素
• trace start/stop - 开始/停止跟踪

状态管理

• cookies - 管理 Cookie
• storage - 管理本地存储
• set offline/headers/credentials/geo/media/timezone/locale/device - 设置浏览器状态

配置选项

基础配置

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "color": "#00ff00",
    "headless": false,
    "noSandbox": false,
    "attachOnly": false,
    "executablePath": "/usr/bin/chromium"
  }
}

配置文件管理

OpenClaw 支持多个浏览器配置文件,每个配置文件可以有不同的 CDP URL 和颜色标识:

{
  "browser": {
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#00ff00"
      },
      "work": {
        "cdpPort": 18801,
        "color": "#0000ff"
      },
      "remote": {
        "cdpUrl": "https://user:pass@remote-host:9222",
        "color": "#ff0000"
      },
      "browserless": {
        "cdpUrl": "wss://chrome.browserless.io?token=YOUR_TOKEN",
        "color": "#ffff00"
      }
    }
  }
}

端口配置

• 网关端口 + 2 → 中继端口(默认 18792)
• 本地 CDP 端口范围:18800–18899
• 可以通过 cdpPort 或 cdpUrl 自定义

浏览器自动化工作流

高层架构:

HTTP 控制服务器 ↔ Chromium (via CDP) ↔ Playwright (高级操作)

工作流程:

1. 本地控制启动浏览器
2. 远程控制代理到节点主机或 Browserless.io
3. 配置文件路由请求——通过 ?profile= 或 --browser-profile 选择

常用命令示例

基础操作

# 检查浏览器状态
openclaw browser --browser-profile openclaw status

# 打开网页
openclaw browser --browser-profile openclaw open https://example.com

# 截图
openclaw browser screenshot --full-page

# 获取页面快照
openclaw browser snapshot --format aria --limit 200

交互操作

# 点击元素(使用元素引用)
openclaw browser click e12 --double

# 输入文本
openclaw browser type "搜索内容" --input-ref e5

# 填充表单
openclaw browser fill --element "input[name='username']" "myuser"

# 等待下载
openclaw browser waitfordownload --timeout 30000

配置浏览器

# 设置自定义浏览器路径
openclaw config set browser.executablePath "/usr/bin/brave-browser"

# 启用无头模式
openclaw config set browser.headless true

主要参数说明

• --browser-profile - 指定配置文件(openclaw, chrome, browserless 等)
• --json - 机器可读的 JSON 输出
• --ref, --selector, --frame - 目标元素
• --format ai/aria/efficient - 快照格式
• --interactive - 交互模式
• --compact - 紧凑输出
• --depth - DOM 深度
• --labels - 显示标签
• --full-page - 全页面截图
• --url, --load, --fn - 导航和执行选项

高级功能

远程 CDP 支持

支持通过查询令牌或基本认证连接到远程 CDP:

// 使用基本认证
{
  "browser": {
    "profiles": {
      "remote": {
        "cdpUrl": "https://user:pass@remote-host:9222"
      }
    }
  }
}

// 使用令牌
{
  "browser": {
    "profiles": {
      "browserless": {
        "cdpUrl": "wss://chrome.browserless.io?token=YOUR_TOKEN"
      }
    }
  }
}

Playwright 集成

部分高级操作需要 Playwright 支持:

• navigate
• act
• pdf
• AI 快照

如果缺少 Playwright,会返回 501 错误。

安全与最佳实践

重要提示

• upload 和 dialog 是预备调用——在触发 UI 之前运行
• attachOnly: true 意味着"永不启动本地浏览器;仅在运行时附加"
• 沙箱会话需要设置 agents.defaults.sandbox.browser.allowHostControl: true 才能控制宿主浏览器
• 自动检测顺序:Chrome → Brave → Edge → Chromium → Canary
• 删除配置文件会将其数据目录移动到回收站