---

Chrome 浏览器自动化配置指南（OpenClaw Browser 插件）

本文档基于 OpenClaw 中 browser 插件的真实配置参数整理，详细讲解 Chrome 浏览器自动化的完整配置方法、核心参数说明及最佳实践。

---

一、插件启用配置

要使浏览器自动化正常工作，必须同时开启两处配置：

1.1 插件开关（plugins.entries）

{
  "plugins": {
    "entries": {
      "browser": {
        "enabled": true
      }
    }
  }
}

重要：若此项为 false，OpenClaw 将不会加载 browser 插件，所有浏览器相关操作均不可用。

1.2 浏览器核心配置（browser）

{
  "browser": {
    "enabled": true,
    "defaultProfile": "user",
    "attachOnly": true,
    "profiles": {
      "user": {
        "driver": "existing-session",
        "color": "#4A90D9"
      }
    }
  }
}

---

二、完整配置示例

{
  "browser": {
    "enabled": true,
    "defaultProfile": "user",
    "attachOnly": true,
    "profiles": {
      "user": {
        "driver": "existing-session",
        "color": "#4A90D9"
      }
    }
  }
}

配置要点：plugins.entries.browser.enabled 和 browser.enabled 两者必须同时为 true。

---

三、配置参数详解

3.1 顶层参数

参数	类型	说明
enabled	boolean	是否启用浏览器自动化功能
defaultProfile	string	默认使用的 profile 名称
attachOnly	boolean	是否仅附加已有会话（true 为不启动新浏览器）
profiles	object	浏览器配置集合

3.2 Profile 配置参数

参数	类型	说明
driver	string	驱动类型（existing-session 表示附加已有会话）
color	string	界面标识颜色（十六进制颜色值）

---

四、Chrome 远程调试端口配置

Windows 系统

修改 Chrome 快捷方式目标，在最后添加：

--remote-debugging-port=9222

或直接运行命令：

chrome --remote-debugging-port=9222

macOS 系统

open -a "Google Chrome" --args --remote-debugging-port=9222

Linux 系统

google-chrome --remote-debugging-port=9222

验证方法：启动后浏览器访问 http://localhost:9222/json，看到 JSON 信息即配置成功。

推荐：将带调试参数的 Chrome 快捷方式固定到任务栏 / Dock。

---

五、OpenClaw Browser 支持的操作

主要功能分类

• 状态与控制：status、start、stop
• 导航操作：open、navigate
• 截图与快照：screenshot、snapshot
• 元素交互：click、type、hover、select、fill

常用调用示例

// 打开网页
browser(action="open", url="https://example.com")

// 截图
browser(action="screenshot")

// 点击元素
browser(action="act", kind="click", ref="button.submit")

// 输入文本
browser(action="act", kind="type", ref="input.username", text="myuser")

// 获取页面快照
browser(action="snapshot")

---

六、多 Profile 配置示例

{
  "browser": {
    "enabled": true,
    "defaultProfile": "user",
    "profiles": {
      "user": { "driver": "existing-session", "color": "#4A90D9" },
      "work": { "driver": "existing-session", "color": "#E74C3C" },
      "dev":  { "driver": "existing-session", "color": "#2ECC71" }
    }
  }
}

---

七、常见问题排查

问题现象	可能原因	解决方案
连接失败	未开启远程调试端口	使用带 --remote-debugging-port=9222 参数启动 Chrome
无法附加	attachOnly=true 但无可用会话	先启动 Chrome 或将 attachOnly 设为 false
元素找不到	页面未加载完成	操作前先执行 snapshot 确认元素存在
截图空白	页面渲染未完成	先 open 页面并适当等待

---

八、最佳实践建议

1. 将带调试端口的 Chrome 快捷方式固定到任务栏，方便一键启动；
2. 不同项目建议使用独立的 Chrome 用户数据目录 + 不同调试端口；
3. 启动顺序：先启动 Chrome，再启动 OpenClaw；
4. 自动化脚本中注意添加页面等待逻辑；
5. 仅在可信环境下使用 Remote Debugging，避免安全风险。

---

安全提醒：开启 Remote Debugging Port 后，本地任何程序均可控制该 Chrome 实例，请谨慎使用。

---

文章标签：
Chrome 浏览器自动化 OpenClaw Selenium Web自动化 远程调试 Puppeteer

---