OpenClaw接入Chrome浏览器流程学习

FserSuN2026-03-15 9:14

OpenClaw接入浏览器

背景介绍

OpenClaw接入浏览器功能让AI助手能够直接控制和操作浏览器，实现网页自动化、信息抓取、页面分析等能力。通过浏览器接入，OpenClaw可以：

  • 网页自动化操作：自动点击、填写表单、导航页面
  • 信息提取：抓取网页内容、截图、生成PDF
  • 实时交互：与网页元素进行交互，模拟用户操作
  • 多场景应用：支持独立浏览器、现有浏览器会话、远程浏览器等多种模式

这在需要网页自动化、数据采集、测试验证等场景中非常有用。

接入配置说明

配置文件位置

所有浏览器配置都在 ~/.openclaw/openclaw.json 文件中进行设置。如果文件不存在，OpenClaw会在首次启动时自动创建。

核心配置项详解

基础配置
json 复制代码 
{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw"
  }
}
  • enabled : 布尔值，控制是否启用浏览器功能。设为false时完全禁用浏览器访问。
  • defaultProfile : 字符串，指定默认使用的浏览器配置文件名称。当不指定--browser-profile参数时使用此配置。
浏览器路径配置
json 复制代码 
{
  "browser": {
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    "headless": false,
    "noSandbox": false
  }
}

  • executablePath: 字符串，指定浏览器可执行文件的完整路径。

    • 如果不设置，OpenClaw会自动检测系统中的Chrome、Brave、Edge等浏览器
    • macOS示例："/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
    • Linux示例："/usr/bin/google-chrome"
    • Windows示例："C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"

  • headless: 布尔值，是否以无头模式运行浏览器。

    • 无头模式：浏览器在后台运行，不显示图形界面，适合服务器环境
    • true：后台运行，节省资源但无法看到浏览器界面
    • false：显示浏览器窗口，可以看到操作过程

  • noSandbox: 布尔值，是否禁用浏览器沙箱。

    • 沙箱：浏览器安全机制，隔离网页进程，防止恶意代码影响系统
    • true：禁用沙箱，在某些Linux环境下可能需要
    • false：启用沙箱，推荐用于安全环境
配置文件详解
json 复制代码 
"profiles": {
  "openclaw": { 
    "cdpPort": 18800, 
    "color": "#FF4500" 
  },
  "work": { 
    "cdpPort": 18801, 
    "color": "#0066CC" 
  },
  "user": {
    "driver": "existing-session",
    "attachOnly": true,
    "color": "#00AA00"
  }
}

  • profiles: 对象，包含多个浏览器配置文件

    • 每个键是配置文件名称，可以自由命名
    • 值是配置对象，定义该配置文件的行为

  • cdpPort: 数字，Chrome DevTools Protocol端口。

    • CDP：Chrome DevTools Protocol，浏览器远程控制协议
    • 默认范围18800-18899，每个配置文件应使用不同端口
    • 本地配置文件通常需要设置此端口

  • color: 字符串，浏览器窗口的边框颜色（十六进制颜色码）

    • 用于区分不同的浏览器配置文件
    • 例如："#FF4500"（橙色）、"#0066CC"（蓝色）、"#00AA00"（绿色）

  • driver: 字符串，指定浏览器驱动类型

    • "managed"：默认值，OpenClaw管理的独立浏览器
    • "existing-session"：连接到现有的Chrome会话
    • "extension"：通过Chrome扩展程序控制

  • attachOnly: 布尔值，是否只附加到现有浏览器

    • true：不启动新浏览器，只连接到已运行的实例
    • false：可以启动新的浏览器实例
安全策略配置
json 复制代码 
"ssrfPolicy": {
  "dangerouslyAllowPrivateNetwork": true,
  "hostnameAllowlist": ["*.example.com", "example.com"]
}

  • dangerouslyAllowPrivateNetwork: 布尔值，是否允许访问私有网络。

    • SSRF：Server-Side Request Forgery，服务器端请求伪造
    • true：允许访问内网地址（如192.168.x.x、10.x.x.x），有安全风险
    • false：只允许访问公网地址，更安全

  • hostnameAllowlist: 数组，允许访问的主机名白名单

    • 限制浏览器只能访问指定域名
    • 支持通配符，如"*.example.com"匹配所有子域名

主要浏览器模式详解

  1. openclaw模式（默认）：

    • 创建独立的浏览器实例，完全隔离用户数据
    • 适合自动化测试、数据采集等场景
    • 不会影响用户的正常浏览器使用

  2. user模式：

    • 连接到现有的已登录Chrome会话
    • 可以访问用户的登录状态、书签、扩展等
    • 需要用户手动批准连接请求

  3. chrome-relay模式：

    • 通过Chrome扩展程序控制现有标签页
    • 需要安装OpenClaw浏览器扩展
    • 用户点击扩展图标来选择要控制的标签页

  4. 远程模式：

    • 连接远程CDP服务，如Browserless、Browserbase等
    • 适合云端自动化、大规模数据采集
    • 需要配置cdpUrl指向远程服务地址

完整配置示例

基础配置

这是最基本且安全的配置，适合大多数用户：

配置文件位置 ：~/.openclaw/openclaw.json

json 复制代码 
{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "noSandbox": false,
    "executablePath": "",
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    },
    "ssrfPolicy": {
      "dangerouslyAllowPrivateNetwork": false,
      "hostnameAllowlist": []
    }
  }
}

使用说明：

  1. 将上述配置复制到 ~/.openclaw/openclaw.json 文件中
  2. 如果文件不存在，会自动创建
  3. 重启OpenClaw Gateway使配置生效
  4. 使用默认命令：openclaw browser status 验证配置

高级配置

适合需要多种浏览器环境的进阶用户：

json 复制代码 
{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "noSandbox": false,
    "executablePath": "",
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      },
      "work": {
        "cdpPort": 18801,
        "color": "#0066CC"
      },
      "user": {
        "driver": "existing-session",
        "attachOnly": true,
        "color": "#00AA00"
      },
      "chrome-relay": {
        "driver": "extension",
        "cdpUrl": "http://127.0.0.1:18792",
        "color": "#00AA00"
      }
    },
    "ssrfPolicy": {
      "dangerouslyAllowPrivateNetwork": false,
      "hostnameAllowlist": ["*.baidu.com", "*.google.com", "*.github.com"]
    }
  }
}

配置说明：

  • openclaw：默认的独立浏览器，橙色边框
  • work：工作环境浏览器，蓝色边框，端口18801
  • user：连接到现有Chrome会话，绿色边框
  • chrome-relay：通过扩展控制现有标签页
  • 白名单限制了只能访问常用网站，提高安全性

远程浏览器配置

连接云端浏览器服务（需要API密钥）：

json 复制代码 
{
  "browser": {
    "enabled": true,
    "defaultProfile": "browserless",
    "remoteCdpTimeoutMs": 2000,
    "remoteCdpHandshakeTimeoutMs": 4000,
    "profiles": {
      "browserless": {
        "cdpUrl": "https://production-sfo.browserless.io?token=YOUR_API_KEY",
        "color": "#00AA00"
      },
      "browserbase": {
        "cdpUrl": "wss://connect.browserbase.com?apiKey=YOUR_API_KEY",
        "color": "#F97316"
      }
    },
    "ssrfPolicy": {
      "dangerouslyAllowPrivateNetwork": false
    }
  }
}

使用前准备：

  1. 注册Browserless或Browserbase账户
  2. 获取API密钥
  3. 替换配置中的YOUR_API_KEY为实际密钥
  4. 建议将密钥存储在环境变量中，避免硬编码

平台特定配置

macOS专用配置
json 复制代码 
{
  "browser": {
    "enabled": true,
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    }
  }
}
Linux专用配置
json 复制代码 
{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome",
    "noSandbox": true,
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    }
  }
}
Windows专用配置
json 复制代码 
{
  "browser": {
    "enabled": true,
    "executablePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    }
  }
}

配置验证命令

配置完成后，使用以下命令验证：

bash 复制代码 
# 检查浏览器状态
openclaw browser status

# 启动浏览器
openclaw browser start

# 列出所有标签页
openclaw browser tabs

# 打开测试网页
openclaw browser open https://example.com

# 获取截图验证
openclaw browser screenshot

效果演示

案例：AI助手自动打开网页并截图

以下演示展示AI助手如何使用OpenClaw浏览器工具自动操作网页：

场景：AI助手需要打开百度首页，搜索"OpenClaw"，然后截图保存结果。

AI助手的操作流程：

  1. 打开百度首页：

    复制代码 
    使用浏览器工具打开 https://www.baidu.com

  2. 获取页面快照以了解结构：

    复制代码 
    获取页面快照，了解搜索框位置

  3. 在搜索框中输入关键词：

    复制代码 
    在搜索框中输入"OpenClaw"

  4. 点击搜索按钮：

    复制代码 
    点击搜索按钮执行搜索

  5. 等待搜索结果加载：

    复制代码 
    等待页面加载完成

  6. 截图保存搜索结果：

    复制代码 
    对搜索结果页面进行截图

操作结果截图 ：

上图展示了AI助手成功完成整个自动化流程：打开百度首页、在搜索框中输入"OpenClaw"关键词、点击搜索按钮执行搜索，并成功获取搜索结果页面的完整过程。页面显示了与OpenClaw相关的搜索结果，证明了浏览器自动化功能的有效性。

技术实现细节：

  • 浏览器配置 ：使用独立的openclaw配置文件运行，端口18800，橙色标识
  • 自动化流程 ：
    1. 打开百度首页（https://www.baidu.com）
    2. 通过页面快照分析DOM结构，定位搜索框（ref=e36）
    3. 使用type动作在搜索框中输入"OpenClaw"
    4. 设置submit=true自动提交搜索表单
    5. 等待页面跳转并加载搜索结果
    6. 截取完整的搜索结果页面
  • 环境隔离：所有操作都在OpenClaw管理的独立浏览器实例中进行，与用户日常浏览器完全隔离
  • 结果验证：截图清晰显示了搜索成功执行，页面包含多个OpenClaw相关的搜索结果，证明了浏览器控制功能的完整性和可靠性

注意事项

常见错误及解决方案

  1. 浏览器未启动：

    • 错误："Browser disabled"
    • 原因 ：配置文件中的browser.enabled设置为false
    • 解决 ：编辑~/.openclaw/openclaw.json，将enabled改为true，然后重启Gateway

  2. 端口冲突：

    • 错误："Port already in use"或连接失败
    • 原因 ：cdpPort被其他程序占用
    • 解决 ：修改配置文件中的cdpPort为其他值（如18801、18802等）

  3. Playwright缺失：

    • 错误："Playwright is not available in this gateway build"
    • 原因：未安装完整版Playwright，只安装了playwright-core
    • 解决 ：运行npm install playwright安装完整版本，然后重启Gateway

  4. Chrome版本不兼容：

    • 错误：连接超时或协议错误
    • 原因：Chrome版本过低或远程调试未启用
    • 解决 ：
      • 升级Chrome到144+版本
      • 在Chrome中访问chrome://inspect/#remote-debugging启用远程调试
      • 确保用户手动批准连接请求

  5. 权限问题：

    • 错误："Unauthorized"或"Access denied"
    • 原因：Gateway认证配置阻止了浏览器访问
    • 解决：检查Gateway的认证设置，确保有正确的访问令牌或密码

安全注意事项

  1. 网络隔离：将Gateway和节点主机保持在私有网络内，避免公网暴露
  2. 令牌管理：远程CDP URL和API令牌视为机密，使用环境变量或密钥管理器
  3. 配置文件保护 ：避免在openclaw.json中直接存储敏感信息
  4. 最小权限原则 ：只授予必要的网络访问权限，使用hostnameAllowlist限制域名

参考资料

  1. OpenClaw浏览器工具官方文档
  2. Chrome DevTools MCP官方指南
  3. Browserless云端浏览器服务
  4. Browserbase云端浏览器平台
  5. OpenClaw安装与配置指南
相关推荐
大傻^3 小时前
【OpenClaw -15】OpenClaw Plugins 开发：Extensions、RPC 注册与自定义工具
ai agent·plugins·openclaw
工业甲酰苯胺3 小时前
Docker 容器化 OpenClaw
人工智能·docker·openclaw
熊猫钓鱼>_>3 小时前
使用阿里云轻量应用服务器OpenClaw丝滑接入飞书打造智能群聊总结助手
人工智能·阿里云·云计算·飞书·agent·skill·openclaw
kishu_iOS&AI11 小时前
OpenClaw 图片解析问题复盘
openclaw
leaf_csdn12 小时前
wsl2中安装openclaw并接入飞书
飞书·openclaw
无心水15 小时前
【OpenClaw：应用与协同】23、OpenClaw生产环境安全指南——Token管理/沙箱隔离/权限最小化
大数据·人工智能·安全·ai·性能优化·openclaw
江湖一码农15 小时前
小龙虾OpenClaw教程2-windows如何干净卸载小龙虾
openclaw
飞飞的AI实验室16 小时前
深度解析：Claude Code 和 OpenClaw 底层架构的设计取舍
架构·ai编程·ai agent·claude code·openclaw
kishu_iOS&AI17 小时前
OpenClaw 管理 API Key / Token 的常见安全方案
安全·ai·策略模式·openclaw
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南04本地部署 OpenClaw + DeepSeek-R1 完全指南05OpenClaw macOS 完整安装与本地模型配置教程（实战版）06OpenClaw 飞书机器人不回复消息？3 小时踩坑总结07UV安装并设置国内源08得物前端部门，没了09“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）10OpenClaw 接入 QQ Bot 完整实践指南