浏览器（openclaw 托管）

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

初学者视角：

  • 把它想象成一个独立的、仅代理使用的浏览器。
  • openclaw 配置文件不会触及你的个人浏览器配置文件。
  • 代理可以打开标签页、阅读页面、点击和输入，在安全的车道中。
  • 默认的 chrome 配置文件通过扩展中继使用系统默认 Chromium 浏览器；切换到 openclaw 使用隔离的托管浏览器。

你得到的

  • 一个名为 openclaw 的独立浏览器配置文件（默认橙色强调色）。
  • 确定性标签页控制（列表打开/聚焦/关闭）
  • 代理操作（点击输入/拖动/选择）、快照、截图、PDF
  • 可选的多配置文件支持（openclaw、work、remote……）

这个浏览器不是你的日常浏览器。它是代理自动化和验证的安全隔离界面。

快速开始

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

  • openclaw：托管的隔离浏览器（无需扩展）?
  • chrome：到?*系统浏览?*的扩展中继（需?OpenClaw 扩展附加到标签页）?

如果想要默认托管模式，设?browser.defaultProfile: "openclaw"?

配置

浏览器设置位?~/.openclaw/openclaw.json?

{
  browser: {
    enabled: true, // 默认: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 默认信任网络模式
      // allowPrivateNetwork: true, // 旧别?
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆?
    remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
    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" },
    },
  },
}

注意?

  • 浏览器控制服务绑定到?gateway.port 派生?loopback 端口（默认：18791，即 gateway + 2）。中继使用下一个端口（18792）?
  • 如果你覆?Gateway 端口（gateway.port ?OPENCLAW_GATEWAY_PORT），派生的浏览器端口会保持在同一”家族”?
  • cdpUrl 在未设置时默认为中继端口?
  • remoteCdpTimeoutMs 适用于远程（?loopback）CDP 可达性检查?
  • remoteCdpHandshakeTimeoutMs 适用于远?CDP WebSocket 可达性检查?
  • 浏览器导?打开标签在导航前?SSRF 保护，并在导航后对最?http(s) URL 尽力重新检查?
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认?true（信任网络模型）。设?false 以进行严格的仅公开浏览?
  • browser.ssrfPolicy.allowPrivateNetwork 仍作为兼容的旧别名受支持?
  • attachOnly: true 表示”永不启动本地浏览器；仅在已运行时附加”?
  • color + 每个配置文件?color 为浏览器 UI 着色，以便你可以看到哪个配置文件是活跃的?
  • 默认配置文件?chrome（扩展中继）。使?defaultProfile: "openclaw" 使用托管浏览器?
  • 自动检测顺序：系统默认浏览器如果是基于 Chromium 的；否则 Chrome ?Brave ?Edge ?Chromium ?Chrome Canary?
  • 本地 openclaw 配置文件自动分配 cdpPort/cdpUrl ?仅远?CDP 设置这些?

使用 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"
  }
}

本地 vs 远程控制

  • *本地控制（默认）? Gateway 启动 loopback 控制服务，可以启动本地浏览器?
  • *远程控制（节点主机）? 在有浏览器的机器上运行节点主机；Gateway 将浏览器操作代理到它?
  • *远程 CDP? 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器?

远程 CDP URL 可以包含认证?

  • 查询令牌（例?https://provider.example?token=<token>?
  • HTTP Basic 认证（例?https://user:[email protected]?

OpenClaw 在调?/json/* 端点和连?CDP WebSocket 时保留认证。优先使用环境变量或密钥管理器来管理令牌，而不是将它们提交到配置文件?

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

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

注意?

  • 节点主机通过代理命令暴露其本地浏览器控制服务?
  • 配置文件来自节点自己?browser.profiles 配置（与本地相同）?
  • 如果你不想要它，可以禁用?
    • 在节点上：nodeHost.browserProxy.enabled=false
    • ?Gateway 上：gateway.nodes.browser.mode="off"

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

注意?

  • ?<BROWSERLESS_API_KEY> 替换为你的真?Browserless 令牌?
  • 选择与你?Browserless 账户匹配的区域端点（见他们的文档）?

安全

关键点：

  • 浏览器控制仅?loopback；访问通过 Gateway 的认证或节点配对流动?
  • 如果启用了浏览器控制但未配置认证，OpenClaw 在启动时自动生成 gateway.auth.token 并持久化到配置?
  • 保持 Gateway 和任何节点主机在私有网络（Tailscale）；避免公开暴露?
  • 将远?CDP URL/令牌视为 secrets；优先使用环境变量或密钥管理器?

远程 CDP 提示?

  • 优先使用 HTTPS 端点和短期令牌?
  • 避免直接在配置文件中嵌入长期令牌?

配置文件（多浏览器）

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

  • openclaw 托管：专用基?Chromium 的浏览器实例，有自己的用户数据目?+ CDP 端口
  • 远程：显?CDP URL（在别处运行的基?Chromium 的浏览器?
  • 扩展中继：通过本地中继 + Chrome 扩展使用你现有的 Chrome 标签?

默认值：

  • 如果缺少，openclaw 配置文件会自动创建?
  • chrome 配置文件内置用于 Chrome 扩展中继（默认指?http://127.0.0.1:18792）?
  • 本地 CDP 端口默认?18800?8899 分配?
  • 删除配置文件将其本地数据目录移到垃圾箱?

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

Chrome 扩展中继（使用你现有?Chrome?

OpenClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动**你现有的 Chrome 标签?*（没有单独的 “openclaw” Chrome 实例）?

完整指南：Chrome 扩展

流程?

  • Gateway 本地运行（同一机器），或节点主机在浏览器机器上运行?
  • 本地**中继服务?*?loopback cdpUrl（默认：http://127.0.0.1:18792）上监听?
  • 你点击标签页上的 OpenClaw Browser Relay 扩展图标附加（它不会自动附加）?
  • 代理通过选择正确的配置文件，使用正常?browser 工具控制该标签页?

如果 Gateway 在别处运行，在浏览器机器上运行节点主机，以便 Gateway 可以代理浏览器操作?

沙箱化会?

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

  • 以非沙箱方式运行会话，或
  • 设置 agents.defaults.sandbox.browser.allowHostControl: true 并在调用工具时使?target="host"?

设置

  1. 加载扩展（dev/未打包）?
openclaw browser extension install
  • Chrome ?chrome://extensions ?启用”开发者模?
  • “加载未打包的” ?选择 openclaw browser extension path 打印的目?
  • 固定扩展，然后在你要控制的标签页上点击它（徽章显?ON）?
  1. 使用它：
  • CLI: openclaw browser --browser-profile chrome tabs
  • 代理工具：browser 使用 profile="chrome"

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

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

注意?

  • 此模式依?Playwright-on-CDP 进行大多数操作（截图/快照/操作）?
  • 再次点击扩展图标分离?

隔离保证

  • 专用用户数据目录：永不触及你的个人浏览器配置文件?
  • 专用端口：避?9222 以防止与开发工作流冲突?
  • 确定性标签页控制：按 targetId 定位标签页，而不?最后一个标签页”?

浏览器选择

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

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

你可以用 browser.executablePath 覆盖?

平台?

  • macOS：检?/Applications ?~/Applications?
  • Linux：查?google-chrome、brave、microsoft-edge、chromium 等?
  • Windows：检查常见安装位置?

控制 API（可选）

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

  • 状?启动/停止：GET /、POST /start、POST /stop
  • 标签页：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
  • 快照/截图：GET /snapshot、POST /screenshot
  • 操作：POST /navigate、POST /act
  • 钩子：POST /hooks/file-chooser、POST /hooks/dialog
  • 下载：POST /download、POST /wait/download
  • 调试：GET /console、POST /pdf
  • 调试：GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
  • 网络：POST /response/body
  • 状态：GET /cookies、POST /cookies/set、POST /cookies/clear
  • 状态：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
  • 设置：POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

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

如果配置?Gateway 认证，浏览器 HTTP 路由也需要认证：

  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password> 或使用该密码?HTTP Basic 认证

Playwright 要求

某些功能（导?操作/AI 快照/角色快照、元素截图、PDF）需?Playwright。如果未安装 Playwright，这些端点返回清晰的 501 错误。对?openclaw 托管?Chrome，ARIA 快照和基本截图仍然有效。对?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）并确保通过 OPENCLAW_HOME_VOLUME 或绑定挂载持久化 /home/node。见 Docker?

它是如何工作的（内部?

高级流程?

  • 一个小?*控制服务?*接受 HTTP 请求?
  • 它通过 CDP 连接到基?Chromium 的浏览器（Chrome/Brave/Edge/Chromium）?
  • 对于高级操作（点?输入/快照/PDF），它在 CDP 之上使用 Playwright?
  • ?Playwright 缺失时，仅非 Playwright 操作可用?

这个设计让代理保持稳定、确定的接口，同时让你可以切换本?远程浏览器和配置文件?

CLI 快速参?

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

基础?

  • openclaw browser status
  • openclaw browser start
  • openclaw browser stop
  • openclaw browser tabs
  • openclaw browser tab
  • openclaw browser tab new
  • openclaw browser tab select 2
  • openclaw browser tab close 2
  • openclaw browser open https://example.com
  • openclaw browser focus abcd1234
  • openclaw browser close abcd1234

检查：

  • openclaw browser screenshot
  • openclaw browser screenshot --full-page
  • openclaw browser screenshot --ref 12
  • openclaw browser screenshot --ref e12
  • 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
  • openclaw browser snapshot --selector "#main" --interactive
  • openclaw browser snapshot --frame "iframe#main" --interactive
  • openclaw browser console --level error
  • openclaw browser errors --clear
  • openclaw browser requests --filter api --clear
  • openclaw browser pdf
  • openclaw browser responsebody "**/api" --max-chars 5000

操作?

  • openclaw browser navigate https://example.com
  • openclaw browser resize 1280 720
  • openclaw browser click 12 --double
  • openclaw browser click e12 --double
  • 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

状态：

  • 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 ?*武装**调用；在触发选择?对话框的点击/按下之前运行它们?
  • 下载和跟踪输出路径受 OpenClaw temp 根目录约束：
    • 跟踪：/tmp/openclaw（回退：${os.tmpdir()}/openclaw?
    • 下载：/tmp/openclaw/downloads（回退：${os.tmpdir()}/openclaw/downloads?
  • 上传路径?OpenClaw temp 上传根目录约束：
    • 上传：/tmp/openclaw/uploads（回退：${os.tmpdir()}/openclaw/uploads?
  • upload 也可以通过 --input-ref ?--element 直接设置文件输入?
  • snapshot?
    • --format ai（安?Playwright 时的默认）：返回带有数字引用?AI 快照（aria-ref="<n>"）?
    • --format aria：返回可访问性树（无引用；仅检查）?
    • --efficient（或 --mode efficient）：紧凑角色快照预设（交互式 + 紧凑 + 深度 + 较低 maxChars）?
    • 配置默认值（工具/CLI only）：当调用者未传递模式时，设?browser.snapshotDefaults.mode: "efficient" 以使用高效快照（?Gateway 配置）?
    • 角色快照选项（--interactive、--compact、--depth、--selector）强制基于角色的快照，带有如 ref=e12 的引用?
    • --frame "<iframe 选择?" 将角色快照限定到 iframe（与 e12 等角色引用配对）?
    • --interactive 输出一个平面、易于拾取的交互式元素列表（最适合驱动操作）?
    • --labels 添加带有叠加引用标签的视口截图（打印 MEDIA:<path>）?
  • click/type/etc 需要来?snapshot ?ref（数?12 或角色引?e12）? CSS 选择器故意不支持操作?

快照和引?

OpenClaw 支持两种”快照”样式?

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

    • 输出：包含数字引用的文本快照?
    • 操作：openclaw browser click 12、openclaw browser type 23 "hello"?
    • 内部，引用通过 Playwright ?aria-ref 解析?

  • **角色快照（角色引用如 e12?*：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame?

    • 输出：带?[ref=e12]（和可?[nth=1]）的角色列表/树?
    • 操作：openclaw browser click e12、openclaw browser highlight e12?
    • 内部，引用通过 getByRole(...) 解析（加?nth() 用于重复）?

  • 添加 --labels 包含带有叠加 e12 标签的视口截图?

引用行为?

  • 引用在导航之?不稳?；如果某事失败，重新运行 snapshot 并使用新的引用?
  • 如果角色快照是用 --frame 获取的，角色引用限定在该 iframe 直到下一个角色快照?

等待增强

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

  • 等待 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"

这些可以组合?

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

调试工作?

当操作失败时（例?不可??严格模式违规”?被覆?）：

  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（打?TRACE:<path>?

JSON 输出

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

示例?

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

JSON 中的角色快照包含 refs 以及一小块 stats（行/字符/引用/交互式），以便工具可以推断负载大小和密度?

状态和环境旋钮

这些?让网站表现得?X”工作流很有用?

  • Cookie：cookies、cookies set、cookies clear
  • 存储：storage local|session get|set|clear
  • 离线：set offline on|off
  • 头：set headers --headers-json '{"X-Debug":"1"}'（旧?set headers --json '{"X-Debug":"1"}' 仍受支持?
  • HTTP basic 认证：set credentials user pass（或 --clear?
  • 地理位置：set geo <lat> <lon> --origin "https://example.com"（或 --clear?
  • 媒体：set media dark|light|no-preference|none
  • 时区/语言环境：set timezone ...、set locale ...
  • 设备/视口?
    • set device "iPhone 14"（Playwright 设备预设?
    • set viewport 1280 720

安全和隐?

  • openclaw 浏览器配置文件中可能包含登录会话；将其视为敏感?
  • browser act kind=evaluate / openclaw browser evaluate ?wait --fn 在页面上下文中执行任?JavaScript。提示注入可以引导它? 如果你不需要它，使?browser.evaluateEnabled=false 禁用它?
  • 登录和反机器人注意事项（X/Twitter 等），见浏览器登?+ X/Twitter 发帖?
  • 保持 Gateway/节点主机私有（仅 loopback ?tailnet）?
  • 远程 CDP 端点很强大；隧道和保护它们?

严格模式示例（默认阻止私?内部目标）：

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // 可选精确允?
    },
  },
}

故障排除

对于特定?Linux 的问题（特别?snap Chromium），? 浏览器故障排除?

代理工具 + 控制如何工作

代理获得**一?*用于浏览器自动化的工具：

  • browser ?状?启动/停止/标签?打开/聚焦/关闭/快照/截图/导航/操作

它如何映射：

  • browser snapshot 返回稳定?UI 树（AI ?ARIA）?
  • browser act 使用快照 ref ID 来点?输入/拖动/选择?
  • browser screenshot 捕获像素（整页或元素）?
  • browser 接受?
    • profile 选择命名浏览器配置文件（openclaw、chrome ?remote CDP）?
    • target（sandbox | host | node）选择浏览器所在位置?
    • 在沙箱化会话中，target: "host" 需?agents.defaults.sandbox.browser.allowHostControl=true?
    • 如果省略 target：沙箱化会话默认?sandbox，非沙箱化会话默认为 host?
    • 如果连接了支持浏览器的节点，工具可能会自动路由到它，除非你固?target="host" ?target="node"?

这保持代理确定性并避免脆弱的选择器?