Browser (OpenClaw-managed)

Browser (openclaw-managed)

OpenClaw 可以运行一个专用的 Chrome/Brave/Edge/Chromium profile，由 agent 控制。 它独立于你的个人 browser，通过 Gateway 内部的一个小型本地 control service（仅 loopback）进行管理。

初学者视角：

• 把它想象成一个独立的、仅供 agent 使用的 browser。
• openclaw profile 不会触碰你的个人 browser profile。
• Agent 可以在安全的环境中打开 tabs、阅读 pages、click 和 type。
• 默认的 chrome profile 通过 extension relay 使用system default Chromium browser；切换到 openclaw 使用 isolated managed browser。

你得到什么

• 一个名为 openclaw 的独立 browser profile（默认橙色 accent）。
• Deterministic tab control（list/open/focus/close）。
• Agent actions（click/type/drag/select）、snapshots、screenshots、PDFs。
• 可选的 multi-profile support（openclaw、work、remote、...）。

这个 browser 不是你的日常 driver。它是一个安全的、isolated surface，用于 agent automation 和 verification。

Quick start

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"，在 config 中启用它（见下文）并重启 Gateway。

Profiles：openclaw vs chrome

• openclaw：managed、isolated browser（不需要 extension）。
• chrome：extension relay 到你的system browser（需要 OpenClaw extension 附加到 tab）。

如果你想要默认 managed mode，设置 browser.defaultProfile: "openclaw"。

Configuration

Browser settings 位于 ~/.openclaw/openclaw.json。

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // 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" },
    },
  },
}

注意：

• Browser control service 绑定到 loopback 端口，从 gateway.port 推导（默认：18791，即 gateway + 2）。Relay 使用下一个端口（18792）。
• 如果你 override Gateway 端口（gateway.port 或 OPENCLAW_GATEWAY_PORT），推导的 browser 端口会 shifting 保持在同一个"family"。
• cdpUrl 在未设置时默认为 relay port。
• remoteCdpTimeoutMs 应用于 remote（non-loopback）CDP reachability checks。
• remoteCdpHandshakeTimeoutMs 应用于 remote CDP WebSocket reachability checks。
• Browser navigation/open-tab 在 navigation 之前进行 SSRF-guarded，并在 navigation 之后的最终 http(s) URL 上进行 best-effort re-checked。
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认为 true（trusted-network model）。设置为 false 进行 strict public-only browsing。
• browser.ssrfPolicy.allowPrivateNetwork 作为 legacy alias 保持支持以兼容。
• attachOnly: true 表示"永不启动本地 browser；仅在已经运行时附加"。
• color + per-profile color tint browser UI 以便你可以看到哪个 profile 是 active。
• Default profile 是 openclaw（OpenClaw-managed standalone browser）。使用 defaultProfile: "chrome" opt into Chrome extension relay。
• Auto-detect order：system default browser 如果是 Chromium-based；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
• Local openclaw profiles 自动分配 cdpPort/cdpUrl——仅为 remote CDP 设置这些。

使用 Brave（或其他 Chromium-based browser）

如果你的system default browser 是 Chromium-based（Chrome/Brave/Edge 等），OpenClaw 自动使用它。设置 browser.executablePath 来 override auto-detection：

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

Local vs remote control

• Local control（默认）： Gateway 启动 loopback control service 并可以启动本地 browser。
• Remote control（node host）： 在有 browser 的机器上运行 node host；Gateway proxies browser actions 到它。
• Remote CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）附加到 remote Chromium-based browser。在这种情况下，OpenClaw 不会启动本地 browser。

Remote CDP URLs 可以包含 auth：

• Query tokens（例如 https://provider.example?token=<token>）
• HTTP Basic auth（例如 https://user:pass@provider.example）

OpenClaw 在调用 /json/* endpoints 和连接 CDP WebSocket 时保留 auth。优先使用 environment variables 或 secrets managers 获取 tokens，而不是将它们提交到 config files。

Node browser proxy（zero-config default）

如果你在拥有 browser 的机器上运行node host，OpenClaw 可以自动路由 browser tool calls 到该 node 而不需要额外的 browser config。这是 remote gateways 的默认路径。

注意：

• Node host 通过proxy command暴露其本地 browser control server。
• Profiles 来自 node 自己的 browser.profiles config（与本地相同）。
• 如果你不想要它则禁用：
  • 在 node 上：nodeHost.browserProxy.enabled=false
  • 在 gateway 上：gateway.nodes.browser.mode="off"

Browserless（hosted remote CDP）

Browserless 是一个 hosted Chromium service，通过 HTTPS 暴露 CDP endpoints。你可以将 OpenClaw browser profile 指向 Browserless region endpoint 并使用 API key 进行认证。

示例：

{
  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 token。
• 选择与你的 Browserless 账户匹配的 region endpoint（见他们的文档）。

Security

关键概念：

• Browser control 是 loopback-only；access flows 通过 Gateway 的 auth 或 node pairing。
• 如果 browser control 启用且没有配置 auth，OpenClaw 在 startup 时自动生成 gateway.auth.token 并持久化到 config。
• 保持 Gateway 和任何 node hosts 在 private network（Tailscale）上；避免 public exposure。
• 将 remote CDP URLs/tokens 视为 secrets；优先使用 env vars 或 secrets manager。

Remote CDP tips：

• 在可能时优先使用 HTTPS endpoints 和 short-lived tokens。
• 避免将 long-lived tokens 直接嵌入 config files。

Profiles（multi-browser）

OpenClaw 支持多个 named profiles（routing configs）。Profiles 可以是：

• openclaw-managed：专用的 Chromium-based browser instance，有自己的 user data directory + CDP port
• remote：显式的 CDP URL（在其他地方运行的 Chromium-based browser）
• extension relay：通过本地 relay + Chrome extension 的现有 Chrome tab(s)

Defaults：

• 如果缺失，openclaw profile 自动创建。
• chrome profile 为 Chrome extension relay 内置（默认指向 http://127.0.0.1:18792）。
• Local CDP ports 默认从 18800–18899 分配。
• 删除 profile 会将其本地 data directory 移动到 Trash。

所有 control endpoints 接受 ?profile=<name>；CLI 使用 --browser-profile。

Chrome extension relay（使用你的现有 Chrome）

OpenClaw 还可以通过本地 CDP relay + Chrome extension 驱动你的现有 Chrome tabs（不需要独立的"openclaw"Chrome instance）。

完整指南：Chrome extension

流程：

• Gateway 在本地运行（同一台机器）或 node host 在 browser machine 上运行。
• 本地relay server在 loopback cdpUrl 监听（默认：http://127.0.0.1:18792）。
• 你点击 tab 上的OpenClaw Browser Relay extension icon 来附加（它不会 auto-attach）。
• Agent 通过正常的 browser tool 控制该 tab，选择正确的 profile。

如果 Gateway 在其他地方运行，在 browser machine 上运行 node host 以便 Gateway 可以 proxy browser actions。

Sandboxed sessions

如果 agent session 是 sandboxed，browser tool 可能默认为 target="sandbox"（sandbox browser）。 Chrome extension relay takeover 需要 host browser control，所以要么：

• unsandboxed 运行 session，或
• 设置 agents.defaults.sandbox.browser.allowHostControl: true 并在调用 tool 时使用 target="host"。

Setup

1. 加载 extension（dev/unpacked）：

openclaw browser extension install

• Chrome → chrome://extensions → 启用"Developer mode"
• "Load unpacked" → 选择 openclaw browser extension path 打印的目录
• Pin extension，然后在想要控制的 tab 上点击它（badge 显示 ON）。

2. 使用它：

• CLI：openclaw browser --browser-profile chrome tabs
• Agent tool：browser with profile="chrome"

可选：如果你想要不同的名称或 relay port，创建你自己的 profile：

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

注意：

• 此模式依赖于 Playwright-on-CDP 进行大多数操作（screenshots/snapshots/actions）。
• 再次点击 extension icon 来 detach。

Isolation guarantees

• Dedicated user data dir：从不触碰你的个人 browser profile。
• Dedicated ports：避免 9222 以防止与 dev workflows 冲突。
• Deterministic tab control：通过 targetId targeting tabs，而不是"last tab"。

Browser selection

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

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

你可以用 browser.executablePath override。

Platforms：

• macOS：检查 /Applications 和 ~/Applications。
• Linux：查找 google-chrome、brave、microsoft-edge、chromium 等。
• Windows：检查常见的 install locations。

Control API（可选）

仅供本地集成，Gateway 暴露一个小型 loopback HTTP API：

• Status/start/stop：GET /、POST /start、POST /stop
• Tabs：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
• Snapshot/screenshot：GET /snapshot、POST /screenshot
• Actions：POST /navigate、POST /act
• Hooks：POST /hooks/file-chooser、POST /hooks/dialog
• Downloads：POST /download、POST /wait/download
• Debugging：GET /console、POST /pdf
• Debugging：GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
• Network：POST /response/body
• State：GET /cookies、POST /cookies/set、POST /cookies/clear
• State：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
• Settings：POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

所有 endpoints 接受 ?profile=<name>。

如果配置了 gateway auth，browser HTTP routes 也需要 auth：

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> 或 HTTP Basic auth with that password

Playwright requirement

一些 features（navigate/act/AI snapshot/role snapshot、element screenshots、PDF）需要 Playwright。如果没有安装 Playwright，这些 endpoints 返回清晰的 501 error。ARIA snapshots 和 basic screenshots 仍然适用于 openclaw-managed Chrome。对于 Chrome extension relay driver，ARIA snapshots 和 screenshots 需要 Playwright。

如果你看到 Playwright is not available in this gateway build，安装完整的 Playwright package（不是 playwright-core）并重启 gateway，或重新安装带有 browser support 的 OpenClaw。

Docker Playwright install

如果你的 Gateway 在 Docker 中运行，避免 npx playwright（npm override conflicts）。使用 bundled CLI：

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

要持久化 browser downloads，设置 PLAYWRIGHT_BROWSERS_PATH（例如 /home/node/.cache/ms-playwright）并确保 /home/node 通过 OPENCLAW_HOME_VOLUME 或 bind mount 持久化。见 Docker。

工作原理（internal）

High-level flow：

• 一个小型control server接受 HTTP requests。
• 它通过CDP连接到 Chromium-based browsers（Chrome/Brave/Edge/Chromium）。
• 对于 advanced actions（click/type/snapshot/PDF），它在 CDP 之上使用Playwright。
• 当 Playwright 缺失时，只有 non-Playwright operations 可用。

这个设计保持 agent 在稳定、deterministic interface 上，同时让你可以 swap local/remote browsers 和 profiles。

CLI quick reference

所有 commands 接受 --browser-profile <name> targeting 特定 profile。所有 commands 也接受 --json 用于 machine-readable output（stable payloads）。

Basics：

• 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

Inspection：

• 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

Actions：

• 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

State：

• 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 是arming calls；在触发 chooser/dialog 的 click/press 之前运行它们。
• Download 和 trace output paths 限制在 OpenClaw temp roots：
  • traces：/tmp/openclaw（fallback：${os.tmpdir()}/openclaw）
  • downloads：/tmp/openclaw/downloads（fallback：${os.tmpdir()}/openclaw/downloads）
• Upload paths 限制在 OpenClaw temp uploads root：
  • uploads：/tmp/openclaw/uploads（fallback：${os.tmpdir()}/openclaw/uploads）
• upload 也可以通过 --input-ref 或 --element 直接设置 file inputs。
• snapshot：
  • --format ai（默认，安装 Playwright 时）：返回带有 numeric refs 的 AI snapshot（aria-ref="<n>"）。
  • --format aria：返回 accessibility tree（无 refs；仅 inspection）。
  • --efficient（或 --mode efficient）：compact role snapshot preset（interactive + compact + depth + lower maxChars）。
  • Config default（仅 tool/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 在 caller 未传递 mode 时使用 efficient snapshots（见 Gateway configuration）。
  • Role snapshot options（--interactive、--compact、--depth、--selector）强制 role-based snapshot with refs like ref=e12。
  • --frame "<iframe selector>" scopes role snapshots to an iframe（pairs with role refs like e12）。
  • --interactive 输出 flat、easy-to-pick list of interactive elements（最适合 driving actions）。
  • --labels 添加 viewport-only screenshot with overlayed ref labels（打印 MEDIA:<path>）。
• click/type/etc 需要来自 snapshot 的 ref（numeric 12 或 role ref e12）。CSS selectors 故意不支持 actions。

Snapshots and refs

OpenClaw 支持两种"snapshot" styles：

• AI snapshot（numeric refs）：openclaw browser snapshot（默认；--format ai）

  • Output：包含 numeric refs 的 text snapshot。
  • Actions：openclaw browser click 12，openclaw browser type 23 "hello"。
  • Internally，ref 通过 Playwright 的 aria-ref 解析。

• Role snapshot（role refs like e12）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）

  • Output：role-based list/tree with [ref=e12]（和可选的 [nth=1]）。
  • Actions：openclaw browser click e12，openclaw browser highlight e12。
  • Internally，ref 通过 getByRole(...) 解析（plus nth() for duplicates）。
  • 添加 --labels 包含 viewport screenshot with overlayed e12 labels。

Ref behavior：

• Refs 在navigations 之间不稳定；如果某些东西失败，重新运行 snapshot 并使用 fresh ref。
• 如果 role snapshot 使用 --frame 拍摄，role refs scoped to that iframe 直到下一个 role snapshot。

Wait power-ups

你可以 wait 不仅仅是 time/text：

• Wait for URL（globs supported by Playwright）：
  • openclaw browser wait --url "**/dash"
• Wait for load state：
  • openclaw browser wait --load networkidle
• Wait for a JS predicate：
  • openclaw browser wait --fn "window.ready===true"
• Wait for a selector to become visible：
  • openclaw browser wait "#main"

这些可以组合：

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

Debug workflows

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

1. openclaw browser snapshot --interactive
2. 使用 click <ref> / type <ref>（在 interactive mode 中优先使用 role refs）
3. 如果仍然失败：openclaw browser highlight <ref> 查看 Playwright targeting 什么
4. 如果 page behavior 奇怪：
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. 对于 deep debugging：record a trace：
   • openclaw browser trace start
   • reproduce the issue
   • openclaw browser trace stop（打印 TRACE:<path>）

JSON output

--json 用于 scripting 和 structured tooling。

示例：

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

JSON 中的 Role snapshots 包含 refs 加上小型 stats block（lines/chars/refs/interactive）以便 tools 可以 reason about payload size and density。

State and environment knobs

这些对于"make the site behave like X" workflows 很有用：

• Cookies：cookies、cookies set、cookies clear
• Storage：storage local|session get|set|clear
• Offline：set offline on|off
• Headers：set headers --headers-json '{"X-Debug":"1"}'（legacy set headers --json '{"X-Debug":"1"}' 仍然支持）
• HTTP basic auth：set credentials user pass（或 --clear）
• Geolocation：set geo <lat> <lon> --origin "https://example.com"（或 --clear）
• Media：set media dark|light|no-preference|none
• Timezone / locale：set timezone ...、set locale ...
• Device / viewport：
  • set device "iPhone 14"（Playwright device presets）
  • set viewport 1280 720

Security & privacy

• Openclaw browser profile 可能包含 logged-in sessions；将其视为 sensitive。
• browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 在 page context 中执行 arbitrary JavaScript。Prompt injection 可以 steer 这个。如果不需要则用 browser.evaluateEnabled=false 禁用它。
• 对于 logins 和 anti-bot notes（X/Twitter 等），见 Browser login + X/Twitter posting。
• 保持 Gateway/node host private（loopback 或 tailnet-only）。
• Remote CDP endpoints 功能强大；tunnel and protect them。

Strict-mode example（默认 block private/internal destinations）：

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

Troubleshooting

对于 Linux-specific issues（特别是 snap Chromium），见 Browser troubleshooting。

Agent tools + how control works

Agent 获得一个 tool用于 browser automation：

• browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

映射方式：

• browser snapshot 返回 stable UI tree（AI 或 ARIA）。
• browser act 使用 snapshot ref IDs 来 click/type/drag/select。
• browser screenshot 捕获 pixels（full page 或 element）。
• browser 接受：
  • profile 选择 named browser profile（openclaw、chrome 或 remote CDP）。
  • target（sandbox | host | node）选择 browser 所在位置。
  • 在 sandboxed sessions 中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：sandboxed sessions 默认 sandbox，non-sandbox sessions 默认 host。
  • 如果连接了 browser-capable node，tool 可能自动路由到它，除非你 pin target="host" 或 target="node"。

这保持 agent deterministic 并避免 brittle selectors。