古法编程

Appearance

本页介绍 OpenClaw 内置的浏览器自动化能力。OpenClaw 可以运行一个与个人浏览器完全隔离的专用 Chrome/Brave/Edge 实例，通过 CDP 和 Playwright 实现标签页控制、元素点击/输入/截图等操作。还支持接入 Browserless、Browserbase 等远程无头浏览器服务，或附接到用户已登录的 Chrome 会话。

浏览器控制（OpenClaw 管理） ​

OpenClaw 可以运行一个专用的 Chrome/Brave/Edge/Chromium Profile，由 agent 控制。它与你的个人浏览器完全隔离，通过 Gateway 内部的小型本地控制服务（仅 loopback）管理。

入门理解：

  • 把它想象成一个专属于 agent 的独立浏览器。
  • openclaw Profile 不会触及你的个人浏览器配置文件。
  • agent 可以在安全的通道中打开标签页、阅读页面、点击和输入。
  • 内置的 user Profile 通过 Chrome MCP 附接到你真实的已登录 Chrome 会话。

你能获得什么 ​

  • 一个名为 openclaw 的独立浏览器 Profile（默认橙色主题）。
  • 确定性的标签页控制（列出/打开/聚焦/关闭）。
  • Agent 操作（点击/输入/拖拽/选择）、快照、截图、PDF。
  • 可选的多 Profile 支持（openclaw、work、remote 等）。

快速开始 ​

bash
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

如果提示"Browser disabled"，在配置中启用（见下文）并重启 Gateway。

如果 openclaw browser 命令完全不存在，跳至缺少 browser 命令或工具。

插件控制 ​

默认的 browser 工具是一个默认启用的内置插件。可以在不移除其他插件的情况下禁用或替换它：

json5
{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

安装另一个提供相同 browser 工具名称的插件前，先禁用内置插件。默认浏览器体验需要同时满足：

  • plugins.entries.browser.enabled 未禁用
  • browser.enabled=true

浏览器配置变更仍然需要重启 Gateway，使内置插件能用新设置重新注册其浏览器服务。

缺少 browser 命令或工具 ​

若升级后 openclaw browser 变为未知命令，或 agent 报告 browser 工具缺失，最常见原因是 plugins.allow 列表中未包含 browser：

json5
// 错误配置
{
  plugins: {
    allow: ["telegram"],
  },
}

// 正确配置
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

注意：browser.enabled=true 和 plugins.entries.browser.enabled=true 单独设置，当 plugins.allow 存在时均不够——必须在 allowlist 中明确包含 browser。

Profile：openclaw vs user ​

  • openclaw：托管的隔离浏览器（无需扩展）。
  • user：内置 Chrome MCP 附接 Profile，用于你真实的已登录 Chrome 会话。

对于 agent 浏览器工具调用：

  • 默认：使用隔离的 openclaw 浏览器。
  • 当已有登录会话很重要且用户在电脑前时，优先使用 profile="user"。

设置 browser.defaultProfile: "openclaw" 可以让托管模式成为默认。

配置 ​

浏览器设置位于 ~/.openclaw/openclaw.json：

json5
{
  browser: {
    enabled: true,
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 默认受信任网络模式
    },
    remoteCdpTimeoutMs: 1500,
    remoteCdpHandshakeTimeoutMs: 3000,
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

说明：

  • 浏览器控制服务绑定到 loopback 端口，默认 18791（即 gateway.port + 2）。
  • attachOnly: true 表示"绝不启动本地浏览器；只在已运行时附接"。
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认为 true（受信任网络模式）。设为 false 可启用严格的纯公网浏览模式。
  • driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP，该驱动不要设置 cdpUrl。

使用 Brave 或其他 Chromium 浏览器 ​

bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
json5
// macOS
{ browser: { executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" } }

// Windows
{ browser: { executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe" } }

// Linux
{ browser: { executablePath: "/usr/bin/brave-browser" } }

本地控制 vs 远端控制 ​

  • 本地控制（默认）： Gateway 启动 loopback 控制服务，可以启动本地浏览器。
  • 远端 CDP： 设置 browser.profiles.<name>.cdpUrl 附接到远端 Chromium 浏览器。
  • 节点宿主机代理： 在有浏览器的机器上运行节点宿主机；Gateway 自动路由浏览器工具调用到该节点。

远端 CDP URL 可以包含认证（查询 token 或 HTTP Basic auth）。优先使用环境变量或 secrets 管理器存储 token，不要直接写入配置文件。

Browserless（托管远端 CDP） ​

json5
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Browserbase ​

Browserbase 是内置 CAPTCHA 解决、隐身模式和住宅代理的云无头浏览器平台：

json5
{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

免费版每月一个并发会话、一小时浏览器时间。

通过 Chrome DevTools MCP 使用现有会话 ​

OpenClaw 可以通过官方 Chrome DevTools MCP 服务器附接到运行中的 Chromium Profile，复用已登录的 tabs 和会话状态。

内置 Profile：user（默认自动连接到 Google Chrome 默认 Profile）。

使用 userDataDir 指向 Brave、Edge 或非默认 Chrome Profile：

json5
{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

然后在对应浏览器中启用远程调试：

  • Chrome：chrome://inspect/#remote-debugging
  • Brave：brave://inspect/#remote-debugging
  • Edge：edge://inspect/#remote-debugging

实机附接冒烟测试：

bash
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

注意：此路径比隔离的 openclaw Profile 风险更高，因为它可以在已登录的浏览器会话内操作。仅在用户在电脑前可以批准附接提示时使用。

安全 ​

  • 浏览器控制仅限 loopback；访问通过 Gateway 认证流动。
  • 若已启用浏览器控制但未配置认证，OpenClaw 会在启动时自动生成 gateway.auth.token。
  • browser.evaluateEnabled=false 可禁用任意 JavaScript 执行（evaluate/wait --fn），防止提示注入风险。
  • 将 Gateway 和节点宿主机保持在私有网络（Tailscale）中。
  • 远端 CDP URL/token 请视为机密，优先使用环境变量或 secrets 管理器。

严格模式配置（默认阻止私有/内部目标）：

json5
{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
    },
  },
}

Playwright 依赖 ​

部分功能需要 Playwright（完整包，非 playwright-core）：

需要 Playwright： navigate、act、AI 快照/角色快照、CSS 选择器元素截图、全页 PDF 导出。

不需要 Playwright： ARIA 快照、托管浏览器的页面截图、existing-session 的页面截图和 ref 截图。

如果看到 Playwright is not available in this gateway build，安装完整 Playwright 包并重启 Gateway。

Docker 环境下安装 Playwright：

bash
docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

CLI 命令速查 ​

所有命令接受 --browser-profile <name> 定向到特定 Profile，接受 --json 输出机器可读结果。

基础操作：

bash
openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser tabs
openclaw browser tab               # 查看当前标签页
openclaw browser tab new           # 新建标签页
openclaw browser tab select 2      # 切换到第 2 个标签页
openclaw browser tab close 2       # 关闭第 2 个标签页
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234

检查操作：

bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12      # 按数字 ref 截图
openclaw browser screenshot --ref e12     # 按角色 ref 截图
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels        # 视口截图 + ref 标签叠加
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser console --level error
openclaw browser pdf
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser responsebody "**/api" --max-chars 5000

交互操作：

bash
openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double       # 数字 ref
openclaw browser click e12 --double      # 角色 ref
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop

状态管理：

bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass
openclaw browser set credentials --clear
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set geo --clear
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

upload 和 dialog 是预备调用——在触发文件选择器/对话框的点击/按键之前运行它们。下载和 trace 的输出路径受限于 OpenClaw 临时目录（/tmp/openclaw/downloads、/tmp/openclaw）；上传路径受限于 /tmp/openclaw/uploads。

快照与引用 ​

OpenClaw 支持两种"快照"风格：

  • AI 快照（数字引用）：openclaw browser snapshot（默认；--format ai）

    • 输出包含数字引用的文本快照。
    • 操作：openclaw browser click 12、openclaw browser type 23 "hello"。

  • 角色快照（角色引用如 e12）：openclaw browser snapshot --interactive

    • 输出带 [ref=e12] 的基于角色的列表/树。
    • 操作：openclaw browser click e12、openclaw browser highlight e12。
    • 添加 --labels 可在视口截图上显示 e12 标签。

引用在导航后不稳定；操作失败时，重新运行 snapshot 使用新引用。如果快照用了 --frame，角色引用的作用域限定在该 iframe 内。

可以设置 browser.snapshotDefaults.mode: "efficient" 使 efficient 快照成为工具和 CLI 的默认模式。

Wait 增强 ​

bash
# 等待 URL（Playwright 支持 glob）
openclaw browser wait --url "**/dash"

# 等待加载状态
openclaw browser wait --load networkidle

# 等待 JS 谓词
openclaw browser wait --fn "window.ready===true"

# 等待选择器可见（可以组合）
openclaw browser wait "#main" --url "**/dash" --load networkidle --timeout-ms 15000

调试工作流 ​

当操作失败（如"not visible"、"strict mode violation"）时：

  1. openclaw browser snapshot --interactive
  2. 使用 click <ref> / type <ref>
  3. 仍然失败：openclaw browser highlight <ref> 查看 Playwright 正在定向哪里
  4. 页面行为异常：openclaw browser errors --clear + openclaw browser requests --filter api --clear
  5. 深度调试：openclaw browser trace start → 复现问题 → openclaw browser trace stop

隔离保证 ​

  • 专用 User Data Dir：绝不触及个人浏览器 Profile。
  • 专用端口：避开 9222，防止与开发工作流冲突。
  • 确定性标签页控制：按 targetId 定向标签页，而非"最后一个标签页"。

故障排查 ​

Linux 特定问题（snap Chromium）参见 浏览器故障排查。

WSL2 + Windows Chrome 跨主机设置参见 WSL2 + Windows + 远端 Chrome CDP 故障排查。

常见问题 ​

Q: 我的龙虾会不会操控我已经登录的网站账号？

A: 默认使用隔离的 openclaw Profile，完全不会碰到你的个人 Chrome/Brave 配置文件或登录状态。只有当你明确使用 profile="user" 或配置了 driver: "existing-session" 的 Profile 时，才会附接到已登录的浏览器会话。

Q: Playwright 报"not available"怎么办？

A: 需要安装完整的 playwright 包（不是 playwright-core）。运行 npm install -g playwright 或 npx playwright install chromium，然后重启 Gateway。Docker 环境参见Docker Playwright 安装。

Q: 如何接入公司内网或需要 VPN 才能访问的网站？

A: 设置 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true（这是默认值，表示受信任网络模式），或在 hostnameAllowlist 中明确添加允许的内网域名。使用 browser.executablePath 指向已配置了 VPN/代理的浏览器可执行文件。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策