← 返回目录

浏览器（openclaw 托管）

OpenClaw 可以运行一个由智能体控制的专用 Chrome/Brave/Edge/Chromium 配置文件。 它与你的个人浏览器隔离，通过 Gateway 网关内部的小型本地控制服务进行管理（仅限 loopback）。

新手视角：

功能概览

此浏览器不是你的日常浏览器。它是一个安全、隔离的界面，用于智能体自动化和验证。

快速开始

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 与 chrome

如果你希望默认使用托管模式，请设置 browser.defaultProfile: "openclaw"。

配置

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

{
  browser: {
    enabled: true, // default: true
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "chrome",
    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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意事项：

使用 Brave（或其他基于 Chromium 的浏览器）

如果你的系统默认浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 browser.executablePath 可覆盖自动检测：

CLI 示例：

openclaw config set browser.executablePath "/usr/bin/google-chrome"

// 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"
  }
}

本地控制与远程控制

远程 CDP URL 可以包含认证信息：

OpenClaw 在调用 /json/* 端点和连接 CDP WebSocket 时会保留认证信息。建议使用环境变量或密钥管理器存储令牌，而不是将其提交到配置文件中。

节点浏览器代理（零配置默认）

如果你在有浏览器的机器上运行节点主机，OpenClaw 可以自动将浏览器工具调用路由到该节点，无需任何额外的浏览器配置。这是远程 Gateway 网关的默认路径。

注意事项：

Browserless（托管远程 CDP）

Browserless 是一个托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。你可以将 OpenClaw 浏览器配置文件指向 Browserless 区域端点，并使用你的 API 密钥进行认证。

示例：

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

注意事项：

安全性

核心理念：

远程 CDP 提示：

配置文件（多浏览器）

OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：

默认值：

所有控制端点接受 ?profile=<name>；CLI 使用 --browser-profile。

Chrome 扩展中继（使用你现有的 Chrome）

OpenClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动你现有的 Chrome 标签页（无需单独的"openclaw"Chrome 实例）。

完整指南：Chrome 扩展

流程：

如果 Gateway 网关在其他地方运行，请在浏览器所在机器上运行节点主机，以便 Gateway 网关可以代理浏览器操作。

沙箱会话

如果智能体会话是沙箱隔离的，browser 工具可能默认为 target="sandbox"（沙箱浏览器）。 Chrome 扩展中继接管需要主机浏览器控制，因此要么：

设置

  1. 加载扩展（开发/未打包）：
openclaw browser extension install
  1. 使用它：

可选：如果你想要不同的名称或中继端口，创建你自己的配置文件：

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

注意事项：

隔离保证

浏览器选择

本地启动时，OpenClaw 选择第一个可用的：

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

你可以使用 browser.executablePath 覆盖。

平台：

控制 API（可选）

仅用于本地集成，Gateway 网关暴露一个小型的 loopback HTTP API：

所有端点接受 ?profile=<name>。

Playwright 要求

某些功能（navigate/act/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。ARIA 快照和基本截图对于 openclaw 托管的 Chrome 仍然有效。对于 Chrome 扩展中继驱动程序，ARIA 快照和截图需要 Playwright。

如果你看到 Playwright is not available in this gateway build，请安装完整的 Playwright 包（不是 playwright-core）并重启 Gateway 网关，或者重新安装带浏览器支持的 OpenClaw。

Docker Playwright 安装

如果你的 Gateway 网关在 Docker 中运行，避免使用 npx playwright（npm 覆盖冲突）。改用捆绑的 CLI：

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

要持久化浏览器下载，设置 PLAYWRIGHT_BROWSERS_PATH（例如 /home/node/.cache/ms-playwright）并确保 /home/node 通过 OPENCLAW_HOME_VOLUME 或绑定挂载持久化。参见 Docker。

工作原理（内部）

高层流程：

这种设计使智能体保持在稳定、确定性的接口上，同时让你可以切换本地/远程浏览器和配置文件。

CLI 快速参考

所有命令接受 --browser-profile <name> 以定位特定配置文件。 所有命令也接受 --json 以获得机器可读的输出（稳定的负载）。

基础操作：

检查：

操作：

状态：

注意事项：

快照和 ref

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

ref 行为：

等待增强功能

你可以等待的不仅仅是时间/文本：

这些可以组合使用：

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

调试工作流

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

  1. openclaw browser snapshot --interactive
  2. 使用 click <ref> / type <ref>（在交互模式下优先使用角色 ref）
  3. 如果仍然失败：openclaw browser highlight <ref> 查看 Playwright 定位的目标
  4. 如果页面行为异常：
  5. 深度调试：录制 trace：

JSON 输出

--json 用于脚本和结构化工具。

示例：

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON 格式的角色快照包含 refs 加上一个小的 stats 块（lines/chars/refs/interactive），以便工具可以推断负载大小和密度。

状态和环境开关

这些对于"让网站表现得像 X"的工作流很有用：

安全与隐私

故障排除

有关 Linux 特定问题（特别是 snap Chromium），请参阅浏览器故障排除。

智能体工具 + 控制工作原理

智能体获得一个工具用于浏览器自动化：

映射方式：

这使智能体保持确定性并避免脆弱的选择器。