openclaw browser

管理 OpenClaw 的浏览器控制界面并执行浏览器操作：生命周期、配置文件、标签页、快照、屏幕截图、导航、输入、状态模拟和调试。

相关：浏览器工具

常用标志

• --url <gatewayWsUrl>：Gateway 网关 WebSocket URL（默认为配置值）。
• --token <token>：Gateway 网关令牌（如有需要）。
• --timeout <ms>：请求超时时间，以毫秒为单位（默认值：30000）。
• --expect-final：等待 Gateway 网关的最终响应。
• --browser-profile <name>：选择浏览器配置文件（默认值：openclaw 或 browser.defaultProfile）。
• --json：机器可读输出（在支持的命令中）。这是浏览器级选项，因此 请将它放在子命令之前，以确保形式明确，例如 openclaw browser --json status。如果所选子命令未定义自己的 --json，也可以将它放在末尾，例如 openclaw browser status --json。

快速开始（本地）

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

智能体可以使用 browser({ action: "doctor" }) 执行相同的就绪检查。

快速故障排查

如果 start 失败并显示 not reachable after start，请先排查 CDP 就绪问题。如果 start 和 tabs 成功，但 open 或 navigate 失败，则浏览器控制平面运行正常，故障通常是导航 SSRF 策略阻止了请求。

最简操作序列：

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

详细指南：浏览器故障排查

生命周期

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

• doctor --deep 会添加实时快照探测：当基础 CDP 就绪检查正常，但你希望确认当前标签页可被检查时，此功能很有用。
• 对于正在运行的本地托管配置文件，status 和 doctor 会报告来自 Chrome 的缓存 图形诊断信息：硬件/软件分类、渲染器、 后端、设备/驱动程序、功能和禁用状态详情，以及硬件加速 视频能力。openclaw browser --json status 返回完整的结构化载荷。 被动状态检查绝不会仅为收集这些信息而启动 Chrome。
• stop 会关闭活动控制会话并清除临时模拟覆盖，即使对于 OpenClaw 未自行启动浏览器进程的 attachOnly 和远程 CDP 配置文件也是如此。对于本地托管配置文件，stop 还会停止已启动的浏览器进程。
• start --headless 仅适用于该次启动请求，并且仅在 OpenClaw 启动本地托管浏览器时生效。它不会重写 browser.headless 或配置文件配置，对于已经运行的浏览器则不会执行任何操作。
• 在没有 DISPLAY 或 WAYLAND_DISPLAY 的 Linux 主机上，本地托管配置文件会自动以无头模式运行，除非 OPENCLAW_BROWSER_HEADLESS=0、browser.headless=false 或 browser.profiles.<name>.headless=false 明确要求显示浏览器。

如果命令缺失

如果 openclaw browser 是未知命令，请检查 ~/.openclaw/openclaw.json 中的 plugins.allow。当存在 plugins.allow 时，请显式列出内置浏览器插件，除非配置中已包含根级 browser 块：

{  plugins: {    allow: ["telegram", "browser"],  },}

显式的根级 browser 块（例如 browser.enabled=true 或 browser.profiles.<name>）也会在限制性插件允许列表下激活内置浏览器插件。

相关：浏览器工具

配置文件

配置文件是已命名的浏览器路由配置：

• openclaw（默认）：启动或连接到 OpenClaw 专用托管 Chrome 实例（隔离的用户数据目录）。
• user：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。
• 自定义 CDP 配置文件：指向本地或远程 CDP 端点。

openclaw browser profilesopenclaw browser system-profilesopenclaw browser system-profiles --browser braveopenclaw browser import-profile --browser chrome --system Default --into importedopenclaw browser import-profile --system "Profile 1" --into work --domains google.com,youtube.comopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

在任何子命令中使用 --browser-profile <name> 指定配置文件，例如 openclaw browser --browser-profile work tabs。

在 macOS 上，system-profiles 会列出主机上可用的真实 Chrome、Brave、Edge 或 Chromium 配置文件。import-profile 会在一次 macOS 钥匙串/Touch ID 同意提示后解密其中的 Cookie，并将其注入新的 OpenClaw 托管配置文件。它只导入 Cookie；本地存储和 IndexedDB 保持不变。部分 Google 会话使用设备绑定会话凭据（DBSC），导入后仍可能需要重新进行身份验证。

当 macOS 应用使用本地 Gateway 网关时，它可以提供一次此导入选项，并将隔离的已导入配置文件设为智能体浏览的默认配置文件。导入始终需要显式点击；导入成功或关闭提示后，将不再自动显示后续提示，而 Settings → General → Browser login 仍可用于重新导入。

系统配置文件导入默认启用。设置 browser.allowSystemProfileImport=false 可禁用 CLI 和智能体触发的导入。导入只能在主机本地执行，无法通过浏览器节点代理运行。

标签页

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs 首先返回 suggestedTargetId，然后返回稳定的 tabId（例如 t1）、可选标签和原始 targetId。将 suggestedTargetId 传回 focus、close、快照和操作。使用 open --label、tab new --label 或 tab label 分配标签；标签、标签页 ID、原始目标 ID 和唯一目标 ID 前缀均可接受。为了兼容，请求字段仍名为 targetId，但它接受上述任何标签页引用。

原始目标 ID 是易变的诊断句柄，不应作为持久的智能体记忆：当 Chromium 在导航或表单提交期间替换底层原始目标时，如果 OpenClaw 能确认匹配关系，就会将稳定的 tabId/标签保留在替换后的标签页上。优先使用 suggestedTargetId。

快照/屏幕截图/操作

快照：

openclaw browser snapshotopenclaw browser snapshot --urls

屏幕截图：

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

• --full-page 仅用于页面截图；不能与 --ref 或 --element 组合使用。
• existing-session/user 配置文件支持页面屏幕截图和快照输出中的 --ref 屏幕截图，但不支持 CSS --element 屏幕截图。
• --labels 会在屏幕截图上叠加当前快照引用。在基于 Playwright 的配置文件中，它可与 --full-page（全页叠加）、--ref（按 ARIA 引用进行元素裁剪叠加）和 --element（按 CSS 选择器进行元素裁剪叠加）配合使用；在元素裁剪模式下，标签会相对于元素进行投影。响应还包含一个 annotations 数组（为空时省略），其中提供每个引用的边界框：ref、number、role、可选的 name，以及所捕获图像坐标空间（视口/全页/元素相对）中的 box: {x, y, width, height}。 existing-session 配置文件会在页面屏幕截图上呈现 chrome-mcp 叠加层，但不使用 Playwright 投影辅助程序，也不包含 annotations；它不支持 CSS --element 屏幕截图。没有 Playwright 或 chrome-mcp 时，无法使用带标签的屏幕截图。
• snapshot --urls 会将发现的链接目标附加到 AI 快照，使智能体可以选择直接导航目标，而不必仅根据链接文本猜测。

导航/点击/输入（基于引用的 UI 自动化）：

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn 接受函数源代码、表达式或语句体。语句体会被包装为异步函数，因此请使用 return 返回所需的值。当页面端函数所需时间可能超过默认求值超时时间时，请使用 --timeout-ms。browser.evaluateEnabled=false（默认值：true）会同时禁用 evaluate 和 wait --fn。

当 OpenClaw 能确认操作触发的页面替换对应哪个标签页时，操作响应会返回替换后的当前原始 targetId。对于长期运行的工作流，脚本仍应存储并传递 suggestedTargetId/标签。

文件和对话框辅助命令：

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

托管 Chrome 配置文件会将普通点击触发的下载保存到 OpenClaw 下载目录（默认值为 /tmp/openclaw/downloads，或配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 waitfordownload 或 download；这些显式等待程序会接管下一次下载。上传接受来自 OpenClaw 临时上传根目录和 OpenClaw 托管入站媒体的文件，包括 media://inbound/<id> 和沙箱相对的 media/inbound/<id> 引用。嵌套媒体引用、路径遍历和任意本地路径均会被拒绝。

当操作打开模态对话框时，操作响应会返回包含 browserState.dialogs.pending 的 blockedByDialog；传递 --dialog-id 可直接回应对话框。在 OpenClaw 外部处理的对话框会显示在 browserState.dialogs.recent 下。

批量操作：

openclaw browser batch --actions '[{"kind":"wait","timeMs":500},{"kind":"click","ref":"12"},{"kind":"type","ref":"23","text":"hello"}]'openclaw browser batch --actions-file plan.jsonopenclaw browser batch --actions-file - --continue

openclaw browser batch 发送一个 kind="batch" /act 请求，其中嵌套了 BrowserActRequest 操作（wait、click、type、evaluate，……）——而不是 open/navigate/snapshot/screenshot，后者是 CLI 子命令，并非 /act 类型。--continue 设置 stopOnError=false（默认在第一个错误处停止）；--target-id 将整个批次限定在一个标签页中。嵌套操作失败会使命令以非零状态退出；使用 --json 可保留有序的 results 响应。完整契约（引用生命周期、目标 ID 冲突、错误摘要）请参阅浏览器批处理 CLI。batch 不支持 profile="user" / 现有会话配置文件。

状态和存储

视口 + 模拟：

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookie + 存储：

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

调试

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

通过 MCP 使用现有 Chrome

使用内置的 user 配置文件，或创建你自己的 existing-session 配置文件：

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

默认的现有会话路径是仅限主机的 Chrome MCP 自动连接。如果浏览器已通过 DevTools 端点运行，请传入 --cdp-url，让 Chrome MCP 改为连接该端点。对于 Docker、Browserless 或其他不需要 Chrome MCP 语义的远程设置，请改用 CDP 配置文件。

当前现有会话的限制：

• 由快照驱动的操作使用引用，而不是 CSS 选择器。
• 当调用方省略 timeoutMs 时，受支持的 act 请求使用内置的 60000 ms 默认值；每次调用指定的 timeoutMs 仍然优先。
• click 仅支持左键单击。
• type 不支持 slowly=true。
• press 不支持 delayMs。
• hover、scrollintoview、drag、select 和 fill 拒绝每次调用的超时覆盖；evaluate 接受 --timeout-ms。
• select 仅支持一个值。
• 不支持 wait --load networkidle（可用于托管配置文件和原始/远程 CDP 配置文件）。
• 文件上传需要 --ref / --input-ref，不支持 CSS --element，且一次仅支持一个文件。
• 对话框钩子不支持 --timeout。
• 屏幕截图支持页面捕获和 --ref，但不支持 CSS --element。
• responsebody、下载拦截、PDF 导出和批处理操作仍需要托管浏览器或原始 CDP 配置文件。

远程浏览器控制（节点主机代理）

如果 Gateway 网关与浏览器运行在不同的计算机上，请在装有 Chrome/Brave/Edge/Chromium 的计算机上运行一个节点主机。Gateway 网关会将浏览器操作代理到该节点；无需单独的浏览器控制服务器。

使用 gateway.nodes.browser.mode 控制自动路由；如果连接了多个节点，则使用 gateway.nodes.browser.node 固定使用特定节点。

安全 + 远程设置：浏览器工具、远程访问、Tailscale、安全

相关内容

• CLI 参考
• 浏览器