浏览器工具 attachOnly 模式详解

本文是当时部署环境的行为记录，具体版本未保留。当前版本的配置与行为可能不同，请以 OpenClaw Browser、OpenClaw Chrome Extension 和实际环境验证为准。

1. 核心定义

attachOnly: true 表示 OpenClaw 不启动本地浏览器，只附加到已运行的浏览器。

existing-session 与扩展驱动不是同一种模式：

{
  browser: {
    profiles: {
      user: { driver: "existing-session", attachOnly: true },
      chrome: { driver: "extension", color: "#FF4500" },
    },
  },
}

安装、配对并诊断扩展 profile：

openclaw browser extension path
openclaw browser extension pair
openclaw config set browser.defaultProfile chrome
openclaw browser status --browser-profile chrome
openclaw browser doctor --browser-profile chrome

2. 主要作用

安全管控：防止 Agent 在后台静默运行浏览器，执行未经用户授权或监视的操作，确保所有行为透明。
人工监视：扩展驱动只控制加入 OpenClaw 标签页组的标签页，并可在组内新建标签页。
环境适配：在部分未预装 Chromium 环境的轻量级沙箱或 Node 环境中，通过此模式直接调用宿主机的浏览器能力。

3. 操作前提

插件连接：用户必须在浏览器中点击 OpenClaw 插件图标。
Badge 状态：需确认插件图标上的 Badge 状态显示为 ON。
权限授予：Agent 通过 profile="chrome" 参数来识别并附加到这些已授权的标签页。

记录时间：2026-03-06 11:01