古法编程

Appearance

openclaw browser 是 OpenClaw 的浏览器 CLI 控制工具，用于管理浏览器实例、执行 UI 自动化操作和调试。它支持本地 Chrome、既有的已登录 Chrome 会话（通过 MCP）、远程 CDP 端点以及通过 Node Host 代理控制的远端浏览器。常用命令包括 start、stop、profiles、tabs、snapshot、screenshot、click、type、navigate、set 和 console。如果命令缺失，需检查 plugins.allow 是否包含 browser 插件。

openclaw browser ​

管理 OpenClaw 的浏览器控制面，执行生命周期管理（启动/停止/状态检查）、Profile 配置、标签页操作、快照截图、导航、输入、状态模拟和调试。

相关文档：

常用标志 ​

  • --url <gatewayWsUrl>：Gateway WebSocket URL（默认使用配置值）。
  • --token &lt;token&gt;：Gateway token（如需认证）。
  • --timeout &lt;ms&gt;：请求超时（毫秒）。
  • --expect-final：等待最终 Gateway 响应。
  • --browser-profile &lt;name&gt;：选择浏览器 Profile（默认来自配置）。
  • --json：机器可读输出（在支持的地方）。

快速开始（本地） ​

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

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

快速排查 ​

如果 start 失败并提示 not reachable after start，先排查 CDP 就绪性。如果 start 和 tabs 都成功但 open 或 navigate 失败，说明浏览器控制平面正常，失败通常是导航 SSRF 策略拦截。

最小验证序列：

bash
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

详细排查：Browser troubleshooting

生命周期 ​

bash
openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile

注意：

  • doctor --deep 增加实时快照探测。基础 CDP 就绪正常但想确认当前标签页可被检查时使用。
  • 对于 attachOnly 和远程 CDP Profile，openclaw browser stop 关闭活跃控制会话并清除临时模拟覆盖，即使 OpenClaw 没有自行启动浏览器进程。
  • 对于本地托管 Profile，openclaw browser stop 停止已生成的浏览器进程。
  • openclaw browser start --headless 仅对本次启动请求生效，且仅在 OpenClaw 启动本地托管浏览器时有效。它不会改写 browser.headless 或 Profile 配置，对已运行的浏览器不起作用。
  • 在 Linux 主机上若没有 DISPLAY 或 WAYLAND_DISPLAY 环境变量，本地托管 Profile 会自动以无头模式运行，除非通过 OPENCLAW_BROWSER_HEADLESS=0、browser.headless=false 或 browser.profiles.&lt;name&gt;.headless=false 显式要求可见浏览器。

命令缺失时的处理 ​

如果 openclaw browser 是未知命令，检查 ~/.openclaw/openclaw.json 中的 plugins.allow。

当 plugins.allow 存在时，显式列出内置 browser 插件；除非配置中已有根级 browser 块：

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

根级 browser 块（例如 browser.enabled=true 或 browser.profiles.&lt;name&gt;）也会在严格插件白名单下激活内置 browser 插件。

Profiles ​

Profiles 是命名的浏览器路由配置。实践中：

  • openclaw：启动或附加到 OpenClaw 管理的专用 Chrome 实例（隔离的用户数据目录）。
  • user：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。
  • 自定义 CDP Profiles：指向本地或远程 CDP 端点。
bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work

使用特定 Profile：

bash
openclaw browser --browser-profile work tabs

标签页 ​

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

tabs 依次返回 suggestedTargetId、稳定 tabId（如 t1）、可选标签和原始 targetId。智能体应传入 suggestedTargetId 给 focus、close、快照和操作。可以用 open --label、tab new --label 或 tab label 分配标签；标签、tab id、原始 target id 和唯一 target-id 前缀均可接受。当 Chromium 在导航或表单提交期间替换底层原始 target 时，OpenClaw 会将稳定 tabId/标签附加到替换标签页上（在能证明匹配时）。原始 target id 仍不稳定；优先使用 suggestedTargetId。

快照 / 截图 / 操作 ​

快照：

bash
openclaw browser snapshot
openclaw browser snapshot --urls

截图：

bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels

注意：

  • --full-page 仅用于页面截图，不能与 --ref 或 --element 组合。
  • existing-session / user Profile 支持页面截图和来自快照输出的 --ref 截图，但不支持 CSS --element 截图。
  • --labels 在当前快照 ref 上叠加标签显示。
  • snapshot --urls 会向 AI 快照附加发现的链接目标，以便智能体选择直接导航目标，而不是仅从链接文本猜测。

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

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

当页面侧函数可能比默认评估超时更长时，使用 evaluate --timeout-ms &lt;ms&gt;。

操作响应会在 OpenClaw 能证明替换标签页时返回操作触发页面替换后的当前原始 targetId。对于长生命周期工作流，脚本仍应存储并传入 suggestedTargetId/标签。

文件 + 对话框辅助命令：

bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1

托管 Chrome Profile 会将普通点击触发的下载保存到 OpenClaw 下载目录（默认 /tmp/openclaw/downloads，或已配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，使用 waitfordownload 或 download；这些显式等待器会拥有下一个下载操作。当操作打开模态对话框时，操作响应返回 blockedByDialog 并附带 browserState.dialogs.pending；传入 --dialog-id 直接应答它。在 OpenClaw 外部处理的对话框会出现在 browserState.dialogs.recent。

状态与存储 ​

视口 + 模拟：

bash
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass

Cookie + 存储：

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 token abc123
openclaw browser storage session clear

调试 ​

bash
openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

接入已有 Chrome（通过 MCP） ​

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

bash
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs

此路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请使用 CDP Profile。

当前 existing-session 限制：

  • 快照驱动的操作使用 ref，不用 CSS 选择器。
  • browser.actionTimeoutMs 默认情况下，当调用方省略 timeoutMs 时，act 请求默认超时为 60000 ms；每次调用的 timeoutMs 仍优先生效。
  • click 仅支持左键点击。
  • type 不支持 slowly=true。
  • press 不支持 delayMs。
  • hover、scrollintoview、drag、select、fill 和 evaluate 不支持每次调用的超时覆盖。
  • select 仅支持单值。
  • wait --load networkidle 不支持。
  • 文件上传需要 --ref / --input-ref，不支持 CSS --element，目前每次只支持一个文件。
  • 对话框钩子不支持 --timeout。
  • 截图支持页面截图和 --ref，但不支持 CSS --element。
  • responsebody、下载拦截、PDF 导出和批量操作仍需要托管浏览器或原始 CDP Profile。

远程浏览器控制（Node Host 代理） ​

如果 Gateway 运行在与浏览器不同的机器上，请在有 Chrome/Brave/Edge/Chromium 的机器上运行 Node Host。Gateway 会将浏览器操作代理到该节点（无需独立的浏览器控制服务器）。

使用 gateway.nodes.browser.mode 控制自动路由，使用 gateway.nodes.browser.node 在连接多个节点时固定特定节点。

安全性 + 远程设置：Browser tool、Remote access、Tailscale、Security

常见问题 ​

为什么 openclaw browser 命令提示“unknown command”？ ​

检查 ~/.openclaw/openclaw.json 中的 plugins.allow 配置。如果该字段存在，需要显式加入 "browser"，例如 plugins: { allow: ["telegram", "browser"] }。另外，如果在配置中有根级 browser 块（如 browser.enabled=true），也会自动激活 browser 插件。

如何让 AI 智能体直接操控我已登录的浏览器，跳过登录墙？ ​

使用 existing-session 驱动，即内置的 user profile。命令：openclaw browser --browser-profile user tabs。这样智能体就能访问你当前 Chrome 中的 cookies 和登录状态，无需重复登录。注意此方式仅支持宿主机，不支持 Docker 或远程 CDP。

start 失败后怎么排查？ ​

依次执行 openclaw browser doctor（检查 CDP 就绪）、start、tabs、open https://example.com。如果 start 报 not reachable after start，优先排查 CDP 端口或浏览器进程。如果 start 和 tabs 成功但 open 失败，通常是导航 SSRF 策略拦截。详见 Browser troubleshooting。

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

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策