openclaw browser
管理 OpenClaw 的浏览器控制界面并运行浏览器操作：生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试。
相关：浏览器工具
常用标志
--url <gatewayWsUrl>：Gateway 网关 WebSocket URL（默认使用配置）。--token <token>：Gateway 网关 token（如需要）。--timeout <ms>：请求超时时间，单位为 ms（默认：30000）。--expect-final：等待最终 Gateway 网关响应。--browser-profile <name>：选择浏览器配置文件（默认：openclaw，或browser.defaultProfile）。--json：机器可读输出（在支持的位置）。
快速开始（本地）
browser({ action: "doctor" }) 运行相同的就绪检查。
快速故障排查
如果start 失败并显示 not reachable after start，请先排查 CDP 就绪状态。如果 start 和 tabs 成功，但 open 或 navigate 失败，则浏览器控制平面是健康的，失败通常是导航 SSRF 策略阻止导致的。
最小序列：
生命周期
doctor --deep会添加实时快照探测：当基础 CDP 就绪状态为绿色，但你需要证明当前标签页可以被检查时很有用。stop会关闭活动控制会话，并清除临时模拟覆盖；即使是 OpenClaw 未自行启动浏览器进程的attachOnly和远程 CDP 配置文件也是如此。对于本地托管配置文件，stop还会停止已启动的浏览器进程。start --headless仅应用于该次启动请求，并且仅在 OpenClaw 启动本地托管浏览器时生效。它不会重写browser.headless或配置文件配置，对于已经运行的浏览器则不会产生效果。- 在没有
DISPLAY或WAYLAND_DISPLAY的 Linux 主机上，本地托管配置文件会自动以 headless 方式运行，除非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>）也会在限制性插件 allowlist 下激活内置浏览器插件。
相关：浏览器工具
配置文件
配置文件是具名浏览器路由配置：openclaw（默认）：启动或附加到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。user：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。- 自定义 CDP 配置文件：指向本地或远程 CDP 端点。
--browser-profile <name> 指定配置文件，例如 openclaw browser --browser-profile work tabs。
标签页
tabs 会先返回 suggestedTargetId，然后返回稳定的 tabId（例如 t1）、可选标签以及原始 targetId。将 suggestedTargetId 传回 focus、close、快照和操作。使用 open --label、tab new --label 或 tab label 分配标签；标签、标签页 ID、原始目标 ID 以及唯一的目标 ID 前缀都可以接受。为兼容性，请求字段仍命名为 targetId，但它接受这些标签页引用中的任意一种。
原始目标 ID 是易变的诊断句柄，不是持久智能体记忆：当 Chromium 在导航或表单提交期间替换底层原始目标时，如果 OpenClaw 能证明匹配，就会将稳定的 tabId/标签附加到替换后的标签页。优先使用 suggestedTargetId。
快照 / 截图 / 操作
快照：--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 快照中，以便智能体可以选择直接导航目标，而不是仅根据链接文本猜测。
evaluate --fn 接受函数源码、表达式或语句体。语句体会被包装为 async 函数，因此请使用 return 返回你想要的值。当页面侧函数可能需要比默认 evaluate 超时时间更长时，请使用 --timeout-ms。browser.evaluateEnabled=false（默认：true）会同时禁用 evaluate 和 wait --fn。
当 OpenClaw 能证明替换标签页时，操作响应会在操作触发页面替换后返回当前原始 targetId。脚本仍应存储并传递 suggestedTargetId/标签，用于长期工作流。
文件 + 对话框辅助：
/tmp/openclaw/downloads，或配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 waitfordownload 或 download；这些显式等待器拥有下一次下载。上传接受来自 OpenClaw 临时上传根目录和 OpenClaw 托管入站媒体的文件，包括 media://inbound/<id> 和沙箱相对的 media/inbound/<id> 引用。嵌套媒体引用、路径遍历和任意本地路径都会被拒绝。
当某个操作打开模态对话框时，操作响应会返回包含 browserState.dialogs.pending 的 blockedByDialog；传入 --dialog-id 可直接响应该对话框。在 OpenClaw 外部处理的对话框会出现在 browserState.dialogs.recent 下。
状态和存储
视口 + 模拟：调试
通过 MCP 使用现有 Chrome
使用内置的user 配置文件，或创建你自己的 existing-session 配置文件：
--cdp-url，让 Chrome MCP 改为附加到该端点。对于 Docker、Browserless 或其他不需要 Chrome MCP 语义的远程设置，请改用 CDP 配置文件。
当前 existing-session 限制：
- 快照驱动的操作使用引用，而不是 CSS 选择器。
- 当调用方省略
timeoutMs时，browser.actionTimeoutMs会将受支持的act请求默认设为 60000 ms；每次调用的timeoutMs仍然优先。 click仅支持左键点击。type不支持slowly=true。press不支持delayMs。hover、scrollintoview、drag、select、fill和evaluate会拒绝每次调用的超时覆盖。select仅支持一个值。- 不支持
wait --load networkidle（在托管和原始/远程 CDP 配置文件上可用）。 - 文件上传需要
--ref/--input-ref，不支持 CSS--element，并且一次只支持一个文件。 - 对话框钩子不支持
--timeout。 - 截图支持页面捕获和
--ref，但不支持 CSS--element。 responsebody、下载拦截、PDF 导出和批量操作仍需要托管浏览器或原始 CDP 配置文件。
远程浏览器控制（node 主机代理）
如果 Gateway 网关运行在与浏览器不同的机器上，请在装有 Chrome/Brave/Edge/Chromium 的机器上运行一个 node 主机。Gateway 网关会将浏览器操作代理到该节点；不需要单独的浏览器控制服务器。 使用gateway.nodes.browser.mode 控制自动路由，并在连接了多个节点时使用 gateway.nodes.browser.node 固定到特定节点。
安全 + 远程设置：浏览器工具、远程访问、Tailscale、安全