OpenClaw Browser Automation 技能实战多步网页操作、标签管理、批量动作与故障恢复完全指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读本文围绕 OpenClaw 内置的browser-automation技能SKILL.md展开系统讲解如何通过browser工具完成多步网页流程从浏览器状态检查、稳定标签句柄管理、快照驱动的精确点击到批量动作batch、Code Mode 下的执行循环、陈旧引用恢复以及既有用户浏览器的接入。读完本文你将掌握一套可复现的浏览器自动化操作规范能够在登录校验、标签复用、超时重试与跨页流程中稳定工作并理解其背后browser扩展的源码实现依据。适用场景任何超出单次页面检查的浏览器任务——多步表单、登录态判断、标签页管理、需要从陈旧引用/超时中恢复的复杂流程。一、技能定位何时使用 browser-automationbrowser-automation是一个user-invocable: false的技能即它不是由用户手动触发而是由 Agent 在需要时自动采用。其 frontmatter 声明如下SKILL.mdname: browser-automation description: Use when controlling web pages with the OpenClaw browser tool, especially multi-step flows, login checks, tab management, or recovery from stale refs/timeouts. user-invocable: false判断是否启用该技能的信号凡是使用browser工具且任务超出看一眼页面的范围——例如多步操作、登录校验、标签页管理、或需要从陈旧 ref/超时中恢复——都应遵循本技能的 Operating Loop。从源码看browser工具的动作面非常宽。动作枚举定义在 browser-tool.schema.tsconst BROWSER_TOOL_ACTIONS [ doctor, status, start, stop, profiles, importprofile, tabs, open, focus, close, snapshot, screenshot, navigate, console, requests, errors, text, emulate, pdf, download, waitfordownload, upload, dialog, act, ] as const;而act动作的内部kind闭包同文件 L19-L34为const BROWSER_ACT_KINDS [ batch, click, clickCoords, type, press, hover, scrollIntoView, drag, select, fill, resize, wait, evaluate, close, ] as const;这组枚举就是本技能全部操作词汇表的底层支撑顶层动作负责浏览器/标签生命周期act负责页面内的交互原语。二、Operating Loop先查状态、再稳定句柄、后窄幅行动技能给出的操作循环共五步是任何复杂浏览器任务的基本纪律。2.1 行动前先检查浏览器状态当浏览器/插件本身可能损坏时运行openclaw browser doctor或actionstatus用actionstatus确认可用性当登录态或 profile 选择会影响任务时用actionprofiles在打开新标签页前若担心重试/超时留下了残留窗口用actiontabs先列出标签。这对应了 schema 中独立存在的doctor、status、profiles、tabs等顶层动作它们与页面内交互act是分开的两层能力。2.2 优先使用稳定的标签句柄多步流程中最大的失败源是抓错了标签页。技能给出的规则打开重要标签页时带上label例如labelmeet在actiontabs或actionopen之后保存返回的suggestedTargetId并在后续调用中作为targetId传入suggestedTargetId在有 label 时就是该 label否则是稳定的tabId如t1避免依赖原始 DevToolstargetId——它在 Chromium target 替换机制下可能变化只适合即时诊断。schema 对targetId字段的注释也印证了这一点browser-tool.schema.tsconst TAB_REFERENCE_DESCRIPTION Prefer suggestedTargetId/tabId/label; raw CDP targetId.;源码中suggestedTargetId贯穿标签选择逻辑见 target-id.ts、browser-tool-session-tabs.ts并有专门的契约测试验证标签引用的一致性server-context.tab-reference-parity.contract.test.ts。2.3 先读再点快照驱动的读取策略对于读取页面并回答 X这类任务使用actiontext可配合selector与maxChars限制可见文本量取第一个 selector 匹配否则回退到article/main/body。在既有会话existing-sessionprofile 上改用snapshot——高效快照会省略大部分散文内容。虚拟滚动列表分段滚动每段只捕获相关行最后合并结果。用actionsnapshot作用于目标targetId。给 snapshot 加query按包含全部 token忽略大小写过滤行匹配行保留其 ref。后续动作使用同一个targetId保证 ref 始终落在同一标签页。需要持久 Playwright ref 时请求refsaria。若收到snapshotFormataria的axNref只能在同一快照调用之后使用陈旧或未绑定的axNref 会快速失败需要重新快照。链接文本有歧义、或直接导航可避免脆弱的点击时使用urlstrue。视觉位置重要时在 snapshot 或 screenshot 上使用labelstrue。关于labelstrue的细节技能原文中的重要能力边界在 Playwright 驱动的 profile 上响应会带annotations数组{ref, number, role, name?, box}给出每个 ref 在截图坐标空间中的包围盒无需重新快照即可推理位置截图标签可与fullPagetrue组合CLI 为--full-page标注整个文档或用ref/element裁剪到单个元素profileuser及其它既有会话chrome-mcpprofile 会把标注叠加渲染进页面截图但不附带annotations数组、也不支持 Playwright 的全页/ref/element 投影辅助需要直接从标注后的图片本身读取位置无 Playwright 的 raw-CDP 回退完全不支持标注截图会返回 501——只在 Playwright 可用时才请求labels。schema 中对这些读取参数有直接定义browser-tool.schema.tsmaxChars: optionalNonNegativeIntegerSchema(), snapshotFormat: optionalStringEnum(BROWSER_SNAPSHOT_FORMATS), // aria | ai refs: optionalStringEnum(BROWSER_SNAPSHOT_REFS), // role | aria interactive: Type.Optional(Type.Boolean()), labels: ..., urls: Type.Optional(Type.Boolean()), query: Type.Optional(Type.String()),快照格式与 ref 类型同为闭集枚举同文件 L65-L67const BROWSER_SNAPSHOT_FORMATS [aria, ai] as const; const BROWSER_SNAPSHOT_MODES [efficient] as const; const BROWSER_SNAPSHOT_REFS [role, aria] as const;2.4 窄幅行动用最新快照的 ref 执行优先actionact并使用最近一次快照的 ref。navigate会内联返回加载后页面的紧凑快照批量act结果若报告了跨文档导航会携带最新页面状态——直接用这些 ref不必再补一次快照调用。单个触发导航的 act 之后、模态框变化或表单提交之后下一次动作前务必重新快照。避免盲等尽量等待可见的 UI 状态。测试设备/外观/时区/语言时用actionemulate参数包括device、colorScheme、timezoneId、locale之后重新快照既有会话 profile 不支持 emulateschema 中的supportsEmulation能力位会过滤掉该动作。2.5 报告真实阻塞不谎报登录失败网络故障用actionrequests调试可加 URL/类型filter和limit默认最近 50 条cleartrue读取后清空日志仅受管 profile 支持既有会话 profile 不支持。页面错误用actionerrors和limit默认最近 50 条cleartrue读取后清空同样仅受管 profile 支持。若页面需要登录、权限、验证码、2FA、摄像头/麦克风批准或其它人工步骤停下并准确告知用户所需操作。不能因为当前页面显示权限/引导对话框就声称浏览器未登录——先检查可见 UI。这些顶层动作requests、errors、emulate、text在 schema 的能力决议函数中被逐一按 profile 能力过滤browser-tool.schema.ts说明哪些动作可用是随 profile 动态变化的技能文档正是把这些运行时差异翻译成了操作纪律。三、Browser batch CLI一次调用编排多步动作openclaw browser batch在一个/act调用中执行一数组嵌套/act动作与 Agent 工具内部到达的kindbatch运行时是同一套因此 CLI 用户和脚本可以把wait、click、type、evaluate等动作组合成单一可重放的计划免去逐动作的往返开销。关键约束actions[]中的每一项都必须是BrowserActRequest——即/act路由接受的闭包联合类型不是任意openclaw browser子命令。batch在profileuser及其它既有会话chrome-mcpprofile 上不受支持需逐个单独发送动作。这与 schema 中supportsBatchActions能力位一致browser-tool.schema.ts。3.1 调用形式与参数openclaw browser batch --actions json——内联 JSON--actions-file plan.json——从文件读取--actions-file -——从 stdin 读取--actions-file与 stdin 输入上限1,000,000 字节更大的计划需拆成多次 batch 命令--continue设置stopOnErrorfalse默认在首个错误处停止。CLI 注册测试完整覆盖了这些参数register.batch.test.ts例如--continue映射到stopOnError: false、--actions-file与 stdin 的读取、以及--actions与--actions-file互斥校验Specify only one of --actions or --actions-file。3.2 ref 生命周期与状态变更顺序ref 来自 batch 之前的snapshotsnapshot 不是嵌套动作。嵌套动作若改变页面状态——例如触发导航的click、或修改 DOM 的evaluate——会使 batch 剩余部分的早期 ref 失效把改状态的动作为先或在重新快照后拆分为后续 batch。open、navigate、snapshot不是/act种类因此导航与重新快照发生在 batch 之外。3.3 目标一致性校验嵌套动作共享请求的标签页显式的嵌套targetId若解析到不同标签页会被拒绝并返回ACT_TARGET_ID_MISMATCH。路由层在归一化 batch 时会递归校验每个子动作agent.act.normalize.ts并对 batch 总量设上限countBatchActions递归计数超过ACT_MAX_BATCH_ACTIONS直接报错。3.4 响应结构与脚本化{ results: [{ ok: true } | { ok: false, error: ... }, ...] }结果按动作顺序排列默认stopOnError下数组在首个失败处截断任一失败项都会让进程以非零码退出脚本中请用--json保留完整响应测试验证了 JSON 模式下失败结果会完整保留后再非零退出见 register.batch.test.ts。四、Code Mode Loop在 exec/wait 中驱动浏览器当tools.codeMode启用时Browser 工具没有常规的 turn——它被归类到exec/wait之后。此时需在 exec cell 中以异步全局变量形式调用它使用 exec 快速索引为 Browser 工具公布的 callable 名称通常为browser同名冲突时会被加后缀客户端工具可能赢得相同名称。用精确的catalog.search(browser)拿到已绑定到有效 callable 名称的句柄每个 cell 都重新解析句柄再调用不要硬编码字面量全局名空结果表示本次运行未目录化 Browser 工具。整个循环保持同一个带 label 的标签页读与动作交替进行。4.1 跨 cell 携带状态每个execcell 都启动全新的 VM——已完成 cell 的绑定在下一个 cell 中不复存在只有waiting中的运行保持状态直至wait恢复它们。因此必须把比较状态如url/newElements作为返回值带出再在下一个 cell 中重新嵌入// previous the url/newElements returned by the last completed cell (a fresh // VM runs this cell, so prior bindings do not exist here). const previous { url: https://example.com/inbox, newElements: 0 }; const [browser] await catalog.search(browser, { limit: 1 }); const details await browser({ action: snapshot, snapshotFormat: ai, targetId: task, refs: aria, interactive: true, }); const changed details?.url ! previous.url || (details?.newElements ?? 0) 0 || details?.blockedByDialog true; return { targetId: details?.targetId, url: details?.url, newElements: details?.newElements, stats: details?.stats, changed, };Code-mode 调用直接返回工具的结构化detailstargetId、url、newElements、stats、blockedByDialog渲染后的页面文本不会进入代码 cell。4.2 在 Code Mode 中读取文本需要读取页面文本时用受限的actevaluate要求具备 evaluate 能力browser.evaluateEnabled可禁用并保持返回值有界——页面脚本输出不可信const [browser] await catalog.search(browser, { limit: 1 }); const read await browser({ action: act, kind: evaluate, fn: () document.body.innerText.slice(0, 2000), targetId: task, }); return { url: read?.url, text: read?.result };当 evaluate 不可用时仅依赖结构化状态推进循环。关于 evaluate 的能力开关源码在 config.ts 中读取cfg?.evaluateEnabled ?? DEFAULT_BROWSER_EVALUATE_ENABLED运行时执行层在 evaluate 被禁用时会明确报错pw-tools-core.interactions.execution.tsact:evaluate is disabled by config (browser.evaluateEnabledfalse)。4.3 Code Mode 循环纪律只返回下一步需要的字段绝不返回整个 details 对象完成的 cell 不共享状态在下一 cell 重新嵌入上一 cell 返回的url/newElements或将比较放在同一 cell 内只有waiting运行持续存在由wait恢复每个依赖性的 act 之间穿插一次 URL 或标签检查batch 返回aborted时先重新快照再继续newElements为正时先检查这些元素再更新重新嵌入的状态步骤间预计有导航时使用独立的 act 调用。五、Tab Hygiene标签页卫生与复用为具名任务创建标签页之前先列出标签能复用就复用已有匹配 label 或 URL 且仍可用的标签。示例列出标签页{ action: tabs }若无合适标签页则打开并命名{ action: open, url: https://example.com, label: task }之后按 label 定位{ action: snapshot, targetId: task, refs: aria }若重试产生了重复标签按tabId关闭多余项{ action: close, targetId: t3 }不要把裸数字如2作为targetId传入——数字标签位置只服务于 CLI 辅助命令openclaw browser tab select 2浏览器工具调用需要suggestedTargetId、label、tabId或原始 target id。六、Stale Ref Recovery陈旧引用恢复动作因缺失或陈旧 ref 失败时对同一个targetId重新快照找到当前可见控件用新 ref重试一次若 UI 已进入阻塞状态报告阻塞而非循环重试。这与技能开头陈旧或未绑定的axNref 快速失败的机制互为表里失败本身就是信号正确反应是一次重快照 一次重试 必要时报阻塞而不是盲循环。七、Existing User Browser接入既有用户浏览器仅在既有 cookie/登录态确实重要时使用profileuser——它会挂接用户正在运行的 Chromium 系浏览器。在 macOS 上另一种方案是actionimportprofile让 Agent 使用隔离的受管浏览器并从一个真实的 Chrome 系 profile 复制 cookie。步骤先用actionprofiles检查systemProfiles再导入到一个新的受管 profile 名称下导入会请求一次 Keychain/Touch ID 授权提示。边界说明技能原文明确导入复制 cookie不复制 local storage 或 IndexedDB由于设备绑定会话凭据DBSC部分 Google 会话仍可能要求重新认证。对profileuser及其它既有会话 profile还有一条操作性约束在act:type、hover、scrollIntoView、drag、select、fill上省略timeoutMs——该驱动会拒绝这些动作的按调用超时覆盖act:evaluate则接受timeoutMs。八、Google Meet 专项注意创建或加入 Meet 时该技能文档专门给出此场景的注意点把摄像头/麦克风权限屏视为进展而非登录失败被询问是否有人能听到你时需要语音就点击麦克风选项Google 要求登录、2FA、账号选择器确认或需用户批准的权限时报告确切的人工操作每个会议流程使用一个带 label 的标签页例如labelmeet重试期间复用该标签。这条专项条款与技能 2.2 的labelmeet示例以及 2.5报真实阻塞原则完全呼应是登录态/权限对话框 ≠ 登录失败判断在具体产品上的落地。九、能力边界速查源码可验证下表汇总了本文涉及的能力随 profile / 配置的变化情况依据来自 browser-tool.schema.ts 的能力决议函数resolveBrowserToolCapabilities与技能原文能力受管 Playwright profile既有会话profileuser/ chrome-mcpraw-CDP 回退batch批量动作支持不支持逐条发送不支持labelstrue标注截图支持带annotations数组支持叠加渲染无 annotations无全页/ref/element 投影不支持返回 501requests/errors日志支持cleartrue可清空不支持不支持emulate设备模拟支持不支持不支持act:evaluate默认开启browser.evaluateEnabledfalse可禁用接受timeoutMs—act:type/hover等timeoutMs支持拒绝按调用覆盖需省略—importprofilemacOS 可用复制 cookie不含 local storage/IndexedDBDBSC 影响部分 Google 会话——结语browser-automation技能把browser扩展的完整能力schema 中 24 个顶层动作与 14 种 act kind浓缩为一套可执行的操作纪律先查状态、用稳定句柄、快照驱动读取、窄幅行动、报真实阻塞。配合 batch CLI 的可重放计划与 Code Mode 的结构化状态循环无论是登录校验、标签复用、跨页多步流程还是超时恢复都能以最少往返、最小脆弱性完成。理解能力边界batch/labels/requests/emulate 随 profile 动态过滤是避免动作不可用类失败的关键——这一点在技能文档与 schema 能力决议中保持完全一致。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考