OpenClaw无头浏览器集成使用指南

前言

AI Agent 经常需要与网页交互——抓取页面内容、填写表单、截取屏幕截图，甚至执行复杂的浏览器自动化任务。OpenClaw 内置了无头浏览器（Headless Browser）集成能力，基于 Chromium 内核，通过 Pi Agent SDK 的 browser 工具提供完整的网页交互功能。

本文将介绍如何配置和使用 OpenClaw 的无头浏览器功能，以及 Bridge URL 的工作原理。

启用 Browser 工具

基本配置

{
  agents: {
    "my-agent": {
      tools: {
        browser: {
          enabled: true,
          // 浏览器引擎
          engine: "chromium",
          // 无头模式
          headless: true,
          // 浏览器启动参数
          launchArgs: [
            "--no-sandbox",
            "--disable-gpu",
            "--disable-dev-shm-usage"
          ],
          // 默认视口大小
          viewport: {
            width: 1280,
            height: 720
          },
          // 页面加载超时（毫秒）
          timeout: 30000
        }
      }
    }
  }
}

Docker 环境特殊配置

在 Docker 中运行时，需要确保 Chromium 依赖已安装：

FROM openclaw/gateway:latest

# 安装Chromium依赖
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-noto-cjk \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

或者使用预构建的带浏览器支持的镜像：

services:
  openclaw:
    image: openclaw/gateway:latest-browser
    environment:
      - OPENCLAW_BROWSER_ENABLED=true

Browser 工具功能

AI Agent 可以通过 browser 工具执行以下操作：

1. 页面导航与内容提取

用户：帮我看看 Hacker News 今天的热门文章

AI 内部执行：
→ browser.navigate("https://news.ycombinator.com")
→ browser.extract({ selector: ".titleline > a", fields: ["text", "href"] })
→ 返回提取结果给用户

2. 页面截图

用户：截一张 GitHub trending 页面的图

AI 内部执行：
→ browser.navigate("https://github.com/trending")
→ browser.screenshot({ fullPage: false })
→ 以图片形式发送给用户

3. 表单交互

用户：帮我在那个网站上搜索 "OpenClaw"

AI 内部执行：
→ browser.navigate("https://example.com")
→ browser.fill({ selector: "#search-input", value: "OpenClaw" })
→ browser.click({ selector: "#search-button" })
→ browser.waitForNavigation()
→ browser.extract({ selector: ".results" })

4. JavaScript 执行

AI 内部执行：
→ browser.evaluate("document.title")
→ browser.evaluate("document.querySelectorAll('a').length")

Bridge URL 机制

Bridge URL 是 OpenClaw 的一项独特功能，它允许 AI Agent 将浏览器会话"桥接"给用户，让用户直接在浏览器中与网页交互。

工作原理

1. AI Agent 在无头浏览器中打开页面
2. OpenClaw 生成一个 Bridge URL
3. 用户点击 Bridge URL 在自己的浏览器中打开
4. 用户看到的是 Agent 浏览器会话的实时镜像
5. 用户可以操作页面，操作会同步到 Agent 的浏览器

配置 Bridge URL

{
  agents: {
    "my-agent": {
      tools: {
        browser: {
          bridge: {
            enabled: true,
            // Bridge会话的基础URL
            baseUrl: "https://openclaw.example.com/bridge",
            // 会话过期时间（秒）
            sessionTTL: 600,  // 10分钟
            // 访问认证
            auth: {
              required: true,
              // 一次性Token认证
              method: "token"
            }
          }
        }
      }
    }
  }
}

使用场景

场景一：需要用户登录的网站

用户：帮我查看我的银行账户余额

AI：这需要您登录银行网站。我已经打开了登录页面，
    请点击以下链接完成登录：
    🔗 https://openclaw.example.com/bridge/abc123

    登录后请告诉我，我会继续操作。

用户：[点击链接，完成登录] 好了

AI：[检测到登录成功]
→ browser.extract({ selector: ".balance" })
→ 您的账户余额为 ¥12,345.67

场景二：验证码处理

当遇到验证码时，AI 无法自行处理，可以通过 Bridge URL 让用户手动完成：

AI：页面出现了验证码，请点击链接完成验证：
    🔗 https://openclaw.example.com/bridge/def456
    完成后我将继续操作。

场景三：复杂交互确认

在执行敏感操作前，让用户通过 Bridge URL 确认：

AI：我已经填写好了表单内容，请通过以下链接确认并提交：
    🔗 https://openclaw.example.com/bridge/ghi789

高级配置

代理设置

如果需要通过代理访问网站：

{
  tools: {
    browser: {
      proxy: {
        server: "http://proxy.example.com:8080",
        username: "user",
        password: "pass",
        // 不走代理的域名
        bypass: ["localhost", "*.internal.com"]
      }
    }
  }
}

Cookie 和会话管理

{
  tools: {
    browser: {
      // 持久化Cookie存储
      persistCookies: true,
      cookieDir: "./data/browser-cookies",
      // 默认Cookie
      defaultCookies: [
        {
          name: "lang",
          value: "zh-CN",
          domain: ".example.com"
        }
      ]
    }
  }
}

User-Agent 和请求头

{
  tools: {
    browser: {
      userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      extraHeaders: {
        "Accept-Language": "zh-CN,zh;q=0.9"
      }
    }
  }
}

资源拦截

为了提高性能和减少带宽消耗，可以拦截不需要的资源：

{
  tools: {
    browser: {
      resourceBlocking: {
        // 屏蔽图片（纯内容提取时）
        blockImages: false,
        // 屏蔽字体
        blockFonts: true,
        // 屏蔽广告和追踪脚本
        blockPatterns: [
          "*google-analytics*",
          "*doubleclick*",
          "*facebook.com/tr*"
        ]
      }
    }
  }
}

安全考虑

沙箱隔离

OpenClaw 的浏览器工具运行在沙箱环境中：

{
  tools: {
    browser: {
      sandbox: {
        // 网络访问白名单
        allowedDomains: [
          "*.github.com",
          "*.stackoverflow.com",
          "news.ycombinator.com"
        ],
        // 禁止下载文件
        blockDownloads: true,
        // 禁止访问本地文件
        blockFileUrls: true,
        // 最大同时打开页面数
        maxPages: 5,
        // 单页面最大运行时间
        maxPageTime: 60000
      }
    }
  }
}

内容过滤

{
  tools: {
    browser: {
      contentFilter: {
        // 过滤敏感信息（如提取的页面中包含密码字段）
        redactPatterns: [
          "password",
          "credit.?card",
          "ssn"
        ],
        // 限制提取内容的最大长度
        maxExtractLength: 10000
      }
    }
  }
}

性能优化

浏览器池

对于高并发场景，OpenClaw 支持浏览器实例池：

{
  tools: {
    browser: {
      pool: {
        // 最小浏览器实例数
        min: 2,
        // 最大浏览器实例数
        max: 10,
        // 空闲实例的最大存活时间
        idleTimeout: 300000
      }
    }
  }
}

页面缓存

{
  tools: {
    browser: {
      pageCache: {
        enabled: true,
        // 缓存过期时间
        ttl: 300,  // 5分钟
        // 最大缓存页面数
        maxPages: 50
      }
    }
  }
}

调试

# 以非无头模式启动（用于本地调试）
OPENCLAW_BROWSER_HEADLESS=false openclaw start

# 查看浏览器工具调用日志
openclaw logs --filter "browser"

# 保存截图到本地
openclaw browser screenshot https://example.com --output ./screenshot.png

小结

OpenClaw 的无头浏览器集成让 AI Agent 获得了"看见和操作网页"的能力。通过 browser 工具，Agent 可以导航网页、提取内容、填写表单、截取屏幕截图；通过 Bridge URL 机制，需要用户参与的操作（如登录、验证码）可以无缝衔接。结合沙箱隔离、资源拦截和浏览器池等高级配置，这套方案能够安全、高效地运行在生产环境中。