openclaw browser¶
管理 OpenClaw 的浏览器控制面并运行浏览器操作:生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试。
相关:浏览器工具
常用标志¶
--url <gatewayWsUrl>:网关 WebSocket URL(默认取配置值)。--token <token>:网关令牌(如需要)。--timeout <ms>:请求超时时间(毫秒)(默认:30000)。--expect-final:等待最终的 Gateway 响应。--browser-profile <name>:选择浏览器配置文件(默认:openclaw或browser.defaultProfile)。--json:机器可读输出(在支持的情况下)。这是一个浏览器级选项,因此请将其放在子命令之前,以形成无歧义的形式,例如openclaw browser --json status。将--json放在末尾(如openclaw browser status --json)在所选子命令未定义自己的--json时同样有效。
CLI 会在请求超时之外额外预留 10 秒,用于节点和 Gateway 传输,从而使浏览器超时诊断信息能够送达调用方。
快速开始(本地)¶
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 策略拦截导致的。
最小序列:
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
详细指南:浏览器故障排查
生命周期¶
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 就绪检查显示正常,但你想证明当前标签页可被检查时,此选项很有用。- 对于运行中的本地托管配置文件,
status和doctor会报告来自 Chrome 的缓存图形诊断信息:硬件/软件分类、渲染器、后端、设备/驱动、功能和禁用状态详情,以及加速视频能力。openclaw browser --json status返回完整的结构化数据。被动的状态检查绝不会仅为了收集这些信息而启动 Chrome。 stop会关闭活动控制会话并清除临时模拟覆盖。这同样适用于attachOnly和远程 CDP 配置文件——在这些配置中,OpenClaw 并未自行启动浏览器进程。对于本地托管配置文件,stop还会停止已启动的浏览器进程。start --headless仅适用于该启动请求,且仅在 OpenClaw 启动本地托管浏览器时生效。它不会改写browser.headless或配置文件配置,对于已在运行的浏览器是空操作(no-op)。- 在没有
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 块:
显式的根级 browser 块(例如 browser.enabled=true 或 browser.profiles.<name>)也会在严格的插件允许列表下激活捆绑的浏览器插件。
相关:浏览器工具
配置文件¶
配置文件是命名的浏览器路由配置:
openclaw(默认):启动或附加到专用的 OpenClaw 托管 Chrome 实例(隔离的用户数据目录)。user:通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。- 自定义 CDP 配置文件:指向本地或远程 CDP 端点。
openclaw browser profiles
openclaw browser system-profiles
openclaw browser system-profiles --browser brave
openclaw browser import-profile --browser chrome --system Default --into imported
openclaw browser import-profile --system "Profile 1" --into work --domains google.com,youtube.com
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
在任何子命令上使用 --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 和智能体触发的导入。导入仅在主机本地执行,无法通过浏览器节点代理运行。
Cookie 同步至远程网关¶
import-profile 针对同一主机上的受管配置文件。当您的 OpenClaw Gateway 与智能体浏览器运行在不同计算机上时,请改用 cookie-sync。它会在此 Mac 上解密 Cookie,并通过操作员连接将其推送到远程 Gateway 上的受管配置文件中:
openclaw browser cookie-sync --domains github.com,news.ycombinator.com --into work
openclaw browser --url wss://gateway.example.com cookie-sync --domains github.com --into work --watch
--domains为必填项。Cookie 同步仅复制实时会话 Cookie,因此绝不会发送不受限制的 Cookie 库。白名单缺失或为空时,将视为硬性错误。--into选择 Gateway 上的目标受管配置文件(默认imported)。--gateway/--url选择远程 Gateway(默认为已配置的或本地 Gateway)。--watch保持命令运行,并在源 Cookies 数据库发生变化时重新推送。macOS 钥匙串密钥在每个监视会话中仅读取一次,因此您只需批准一次同意提示,而不是每次变更都批准一次。- 解密在主机本地进行(仅限 macOS),并复用与
import-profile相同的白名单和钥匙串路径。Cookie 在此 Mac 上解密,并通过现有的 TLS 固定 Gateway 连接传输。不会打印任何 Cookie 值。 - 某些 Google 会话使用设备绑定的会话凭据(DBSC),这些凭据与此 Mac 保持绑定,同步后仍可能需要重新认证。对于这些站点,建议通过浏览器节点代理直接驱动 Mac 上的浏览器。
macOS 应用在仪表盘 → 设置 → 此 Mac → 浏览器下提供相同的功能:默认关闭的开关、可编辑的域名白名单以及目标配置文件字段。在远程模式下启用后,它会替您管理针对已连接 Gateway 的 cookie-sync --watch,并显示实时状态行。
Chrome 扩展中继¶
openclaw browser extension path
openclaw browser extension setup --action inspect --json
openclaw browser extension setup --action install --json
openclaw browser extension setup --action verify --browser-profile chrome --json
openclaw browser extension install
openclaw browser extension install --no-store
openclaw browser extension install --json --wait-ms 60000
openclaw browser extension status
openclaw browser extension status --json
openclaw browser extension uninstall-host
openclaw browser extension uninstall-store
openclaw browser extension pair
openclaw browser extension pair --gateway-url wss://gateway.example.com
openclaw browser extension cdp
openclaw browser extension cdp --json
extension setup是 CLI、TUI 和原生桌面适配器共用的主机本地控制器。inspect是只读的安装发现,install准备原生引导,verify验证所选的本地中继。其脱敏 JSON 将准备、Chrome 审批和连接三个阶段分开。有效的待处理/阻止状态以退出码 0 结束;执行失败以非零退出码结束。它绝不会将远程仪表盘或 SSH 回环 URL 视为本地浏览器主机的证据。extension install预注册了来源锁定的原生引导主机。macOS 上的 Google Chrome 可以在首次启动前进行准备;其他受支持的浏览器需要已存在的用户数据目录。在 macOS 上,设置随后会为 Google Chrome 中该目录下的所有配置文件请求官方商店安装。Chrome 会在启动时发现这一点。方便时完全退出并重新打开 Chrome,然后批准或启用 OpenClaw。该命令绝不会重启 Chrome 或绕过审批。对于其他浏览器和平台,请从 Chrome 网上应用店添加 OpenClaw。Linux 支持自动原生配对。Windows 使用来自随附 CLI 或 Windows Companion 的自包含OpenClaw.BrowserBootstrap.exe。便携版/本地安装程序可以将--native-host-executable <absolute-path>传递给extension setup --action install或extension install。设置会在通过共享的 C# 注册服务进行用户级注册表注册之前,检查拥有的上下文/ACL 以及实际的分帧子进程响应。CLI 明确选择原生 Windows 上下文;Companion 拥有其托管 WSL 模式。冲突的上下文和未知的传输结果绝不会触发另一个写入者或模式回退。没有可执行文件或没有证据意味着不会自动引导;它绝不会回退到脚本主机或绕过 Chrome 审批。extension install --no-store复制稳定的开发扩展并注册原生主机,而不会创建商店请求。现有请求保持不变。使用打印的路径进行加载已解压的扩展程序。extension status将storeInstallRequests状态(requested、missing、foreign、invalid)与storeDiscovered审批字段(enabled、awaitingApproval)、已批准的解压扩展 ID 和路径以及原生主机注册健康状态分开报告。本地安装状态并不能证明中继连接处于活动状态。JSON 输出绝不会包含配对字符串或中继密钥。extension uninstall-host仅移除经过验证的、OpenClaw 拥有的原生主机清单和启动器。它不会从 Chrome 中移除扩展。在 Windows 上,它委托给相同的注册服务;--remove-store首先移除经过验证的、OpenClaw 拥有的商店请求。--native-host-executable和--browser-profile为状态查询/移除选择相同的显式本地上下文。extension uninstall-store仅移除 OpenClaw 拥有的 macOS Chrome 商店请求(仅限 macOS)。Windows 使用uninstall-host --remove-store而不是单独的商店写入器。Chrome 可能会在下次启动时移除外部安装的扩展。原生主机注册和开发副本将保持完整。extension path是只读的。当存在稳定的已安装副本时,它会打印该路径;否则打印随附的源目录。extension pair仍然是高级手动流程。--gateway-url创建直接指向远程 Gateway 的配对 URL。非回环 URL 必须使用wss://。extension pair --local-gateway --json允许桌面原生助手通过 Gateway 的/browser/extension唤醒路由获取规范的本地配对。它需要本地 Gateway 配置,并且不能与--gateway-url组合使用。JSON 包含一个凭据:请私下使用,切勿记录。extension cdp打印非机密的 Browser Relay Authentication v2 元数据:回环浏览器/CDP 端点、协议版本、密钥 ID 以及固定的质询/完成绑定。默认情况下,它绝不会打印中继密钥或授权标头。
自动本地引导通过本地 Gateway 的确切 /browser/extension 路由进行连接,因此第一条经过身份验证的扩展连接会启动惰性浏览器控制服务。请保持 openclaw gateway run 或受管理的 Gateway 服务处于运行状态。无需单独的浏览器请求或预热。本地 OpenClaw 和 mcporter 调用在唤醒后仍使用 extension pair 或 extension cdp 报告的 profile 中继端口。浏览器节点配对继续使用浏览器节点主机上的中继,而显式的 --gateway-url 配对仍保持直接远程且仅手动。
不使用 --gateway-url 或 --local-gateway 的高级手动 extension pair 命令会保留主机本地的 /extension 中继 URL。在已安装原生主机、启用 自动本地设置,并且使用支持中继唤醒的扩展构建时,重新连接可以在已保存配对配置的端口上启动独立中继。这不会启动 Gateway 浏览器控制:经过身份验证的 CDP 客户端可以在没有 Gateway 的情况下使用独立中继,但 openclaw browser 操作仍然需要 Gateway。对于源码检出测试,请从同一个 OpenClaw 安装中加载受管理的解压副本。
extension cdp --legacy-bearer 是一个临时的迁移逃生舱。仅当 browser.extensionRelay.allowLegacyAuth=true 时,它才会打印旧的 Bearer 头并附带警告。否则,它会在不打印凭据的情况下以错误退出。对于机器可读输出,请使用 --json。警告保留在 stderr 上,因此 stdout 保持有效的 JSON。
设置、安全模型和恢复步骤:Chrome 扩展。
在托管 Chrome 的机器上运行安装。在 macOS 应用中,Dashboard → Settings → This Mac → Browser → Set up Chrome on this Mac 即使在连接到远程 Gateway 时也会调用本地 CLI。基于浏览器的 dashboard 则提供 Store 和文档链接。
如果扩展在原生主机存在之前就尝试过自动设置,Chromium 会为正在运行的浏览器进程保留该未命中记录。重启一次 Chrome,运行 extension install,然后重新打开 Store 扩展。仅靠弹窗重试无法恢复该现有进程。
标签页¶
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 前缀均可被接受。请求字段为了兼容性仍命名为 targetId,但它接受上述任意一种标签引用。
配置为 driver: "extension" 的 profile 还可以返回数字类型的 webExtensionTabId。它限定在当前浏览器运行时内,并且仅供调用 Chrome 的 WebExtensions API。它可能在浏览器或扩展重新连接后发生变化,并且在其他驱动或扩展元数据不可用时会被省略。不要将它传给 OpenClaw 浏览器命令;在这些命令中请继续使用 suggestedTargetId 或 tabId。
快照 / 截图 / 操作¶
快照:
截图:
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels
--full-page仅用于页面捕获。它不能与--ref或--element组合使用。existing-session/userprofile 支持页面截图和来自快照输出的--ref截图,但不支持 CSS--element截图。--labels会在截图上叠加当前快照引用。在基于 Playwright 的 profile 上,它可与--full-page(整页覆盖)、--ref(按 ARIA 引用进行元素裁剪覆盖)和--element(按 CSS 选择器进行元素裁剪覆盖)配合使用。在元素裁剪模式下,标签相对于元素投影。响应中还包含annotations数组,为空时省略。每个条目携带一个引用的包围盒:ref、number、role、可选的name,以及box: {x, y, width, height}。坐标使用所捕获图像的空间(视口、整页或元素相对)。existing-sessionprofile 在页面截图上渲染 chrome-mcp 覆盖层,但不使用 Playwright 投影辅助,也不包含annotations。那里不支持 CSS--element截图。没有 Playwright 或 chrome-mcp 时,带标签的截图不可用。snapshot --urls将发现的链接目标附加到 AI 快照中,以便智能体可以直接选择导航目标,而不是仅靠链接文本来猜测。
导航/点击/输入(基于引用的 UI 自动化):
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 --fn 'const title = document.title; return title;'
openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
press 接受命名按键和快捷键,例如 Escape、Control+Shift+T 和 Control++。常见的 Esc、Return、Del、Ctrl 和 Cmd 别名会被标准化。
对于托管浏览器配置文件,select 会精确保留选项值。请为空值或对空白敏感的值加引号,例如 openclaw browser select <ref> "" 或 openclaw browser select <ref> " padded "。
evaluate --fn 接受函数源代码、表达式或语句体。语句体会被包装为异步函数,因此请使用 return 返回你希望取回的值。当页面端函数可能需要超过默认 evaluate 超时的时间时,请使用 --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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1
托管 Chrome 配置文件会将常规点击触发的下载保存到 OpenClaw 下载目录(默认为 /tmp/openclaw/downloads,或已配置的临时根目录)。当代理需要等待特定文件并返回其路径时,请使用 waitfordownload 或 download。这些显式等待命令会接管下一次下载。上传接受来自 OpenClaw 临时上传根目录和 OpenClaw 管理的入站媒体的文件,包括 media://inbound/<id> 以及沙箱相对路径 media/inbound/<id> 引用。嵌套媒体引用、路径遍历和任意本地路径都会被拒绝。
对于远程浏览器节点,OpenClaw 会暂存私有副本,并为可移植性规范化文件名,包括 Windows 设备名称以及末尾的点或空格。文件字节保持不变。
如果保存下载失败,OpenClaw 会请求取消传输并报告原始保存错误。在开始新的下载之前,请修正输出路径或文件系统问题。
当操作打开模态对话框时,文本输出会报告阻塞和待处理对话框 ID。JSON 响应会返回 blockedByDialog,并带有 browserState.dialogs.pending。传递 --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.json
openclaw browser batch --actions-file - --continue
openclaw browser batch 发送带有嵌套 BrowserActRequest 操作(wait、click、type、evaluate、...)的 kind="batch" /act 请求——而不是 open/navigate/snapshot/screenshot,这些是 CLI 子命令,不是 /act 类型。--continue 设置 stopOnError=false(默认在第一个错误时停止)。--target-id 将整个批处理限定到一个标签页。失败的嵌套操作会使命令以非零状态退出。使用 --json 以保留有序的 results 响应。请参阅 浏览器批量 CLI 以了解完整契约(ref 生命周期、target id 冲突、错误摘要)。batch 不支持 profile="user" / existing-session 配置文件。
如果导航或已关闭的页面导致批处理停止,文本输出会报告操作编号和跳过数量。在继续执行依赖操作之前,请获取新的快照。
--actions-file 和 --actions-file - 的 stdin 输入上限为 1,000,000 字节。将更大的计划拆分为多个 openclaw browser batch 命令。
状态与存储¶
视口 + 仿真:
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 + 存储:
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
存储键保留周围的空白。在 shell 命令中为键加引号,
例如 openclaw browser storage local get " account "。设置该键
不会覆盖单独的 account 条目。空键或仅包含空白的键
对 set 仍然无效;在 get 中省略键会列出所有条目。
调试¶
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
responsebody 将受限的响应前缀写入 stdout,并在截断时向 stderr
发出警告。--json 会包含响应元数据和 truncated
标志,而不单独发出警告。使用 --max-chars 选择前缀长度限制。
通过 MCP 使用现有 Chrome¶
使用内置的 user 配置文件,或创建你自己的 existing-session 配置文件:
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 create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222
openclaw browser --browser-profile chrome-live tabs
默认的 existing-session 路径是仅限主机的 Chrome MCP 自动连接。如果浏览器已经带有 DevTools 端点运行,请传递 --cdp-url,以便 Chrome MCP 改为附加到该端点。对于 Docker、Browserless 或其他不需要 Chrome MCP 语义的远程设置,请改用 CDP 配置文件。
当前现有会话的限制:
- 快照驱动的操作使用 refs,而不是 CSS 选择器。
- 受支持的
act请求在调用方省略timeoutMs时使用内置的 60000 ms 默认值。接受的每次调用覆盖值会设置该操作预算。 click仅支持左键单击。type不支持slowly=true。press不支持delayMs。hover、scrollintoview、drag、select和fill拒绝每次调用的超时覆盖值。evaluate接受--timeout-ms。select仅支持一个值。wait --load networkidle不受支持(在托管以及 raw/remote CDP 配置上可用)。- 文件上传需要
--ref/--input-ref,不支持 CSS--element。当页面的文件输入接受多个文件时,请传入多个路径。 - 对话框钩子不支持
--timeout。 - 截图支持页面捕获和
--ref,但不支持 CSS--element。 responsebody、下载拦截、PDF 导出和批量操作仍需要托管浏览器或 raw CDP 配置。
现有会话的操作步骤共享一个执行预算:使用 type 进行填充和提交不会各自获得新的超时。条件 wait 允许其显式 timeMs 延迟加上操作预算(最低 250 ms)来满足条件。纯计时器等待会预留 timeMs 和操作预算中较大的值。
导航验证拥有单独的共享额度,即操作预算加上用于计划延迟的 1250 ms。resize 和 close 跳过验证。浏览器和标签页准备、执行以及最终 URL 查找共享整体请求截止时间。内部调用和导航探测不会续期该截止时间。
远程浏览器控制(node host 代理)¶
如果 Gateway 运行在与浏览器不同的机器上,请在装有 Chrome/Brave/Edge/Chromium 的机器上运行 node host。Gateway 会将浏览器操作代理到该节点。无需单独的浏览器控制服务器。
自动路由优先使用 Gateway 主机的浏览器,并且仅在本地浏览器能力不可用时才使用单个已连接的浏览器节点。使用 gateway.nodes.browser.mode 控制此回退,并使用 gateway.nodes.browser.node 显式选择节点,包括主机已有浏览器的情况。已停止的本地托管浏览器如果已安装可执行文件,仍会保持本地。
安全 + 远程设置:浏览器工具、远程访问、Tailscale、安全
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw