古法编程

Appearance

openclaw browser 提供了从命令行直接操控无头 Chrome 和管理其会话生命周期的能力。除了用于查看当前网页截图（screenshot）和元素（snapshot），你甚至可以用它连接（Attach）到当前运行在系统上、带有完整登录状态的 Chrome 浏览器实例中，协助执行日常的 Web 自动化操作。

openclaw browser ​

管理 OpenClaw 的浏览器控制界面，执行浏览器操作（生命周期、Profile、标签页、动作、状态、调试）。

相关文档：

常用标志 ​

  • --url <gatewayWsUrl>：Gateway WebSocket URL（默认使用配置值）。
  • --token <token>：Gateway token（如需认证）。
  • --timeout <ms>：请求超时（毫秒）。
  • --expect-final：等待最终 Gateway 响应。
  • --browser-profile <name>：选择浏览器 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

生命周期 ​

bash
openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile

注意：

  • 对于 attachOnly 和远程 CDP profile，openclaw browser stop 会关闭活跃的控制会话并清除临时模拟覆盖，即使 OpenClaw 没有自己启动浏览器进程。
  • 对于本地托管 profile，openclaw browser stop 停止已生成的浏览器进程。

命令缺失时的处理 ​

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

当 plugins.allow 存在时，内置 browser 插件必须明确列出：

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

browser.enabled=true 在插件白名单排除 browser 时不会恢复 CLI 子命令。

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
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>

快照 / 截图 / 操作 ​

快照：

bash
openclaw browser snapshot

截图：

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

注意：

  • --full-page 仅用于页面截图，不能与 --ref 或 --element 组合。
  • existing-session / user profile 支持页面截图和来自快照输出的 --ref 截图，但不支持 CSS --element 截图。

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

bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
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>

文件 + 对话框辅助命令：

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

状态与存储 ​

视口 + 模拟：

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

让龙虾直接操控你已登录的浏览器——Cookie、登录状态全都带着，省去二次登录的麻烦。

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

existing-session 当前限制：

  • 快照驱动的操作使用 ref，不用 CSS 选择器
  • 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、Security

常见问题 ​

Q: --ref 和 CSS --element 有什么区别？

A: ref 是由 snapshot 操作生成的一套专用于无障碍辅助（A11y/ARIA）标记的动态 ID 系统，能精准识别屏幕上可交互的按钮或输入框，对由于前端框架（如 React/Vue）导致 DOM 混淆的网站有极高的适应性；而 --element 则是传统的开发者用的 CSS 选择器。

Q: 想要 Agent 能够跳过登录墙，我该用哪个模式？

A: 使用 existing-session 驱动或者默认的 user profile 接入当前打开的系统浏览器。浏览器里包含着你所有正常的 session 和 cookies 数据，只要你已经在浏览器中完成了登录，Agent 看到的内容就是登录状态后的页面，可以大大节约构建验证流程的工作量。

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

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