luovicter-collab/openclaw-docs/browser-task

用浏览器完成任务（Browser as Task-Solving Method）

无需用户明确说「用浏览器」。当没有专用技能（如小红书用 xiaohongshu-mcp、下论文用 paper-fetcher）且任务客观上涉及或适合在网页上完成时，应主动用本技能：自己打开页面、识别内容、点击/输入、再看、再操作，直到完成或触发失败出口。

何时用本 skill（主动判断，不等用户说）

• 用户说「帮我查一下 XX 网站」「在知乎/百度搜一下」「登录某站」「填个表」「点开某链接看看」等——即使用户没说「用浏览器」，且无专用技能可覆盖时，用本流程。
• 任务需要根据页面当前内容决定下一步（例如：看到登录框就填，看到结果列表就点第一条）。
• 无现成 API、MCP 或专用技能，在网页上操作是合理手段时，默认选用本技能。
• 何时不用：小红书发帖/搜帖 → xiaohongshu-mcp；按 DOI 下论文 → paper-fetcher。

标准流程（必须遵循）

1. 确保浏览器可用

如需先启动或打开页面：用 browser 的 status / start / open（或 navigate）到目标 URL。若 browser 不可用（status 失败或工具被策略拒绝），告知用户「当前环境无法使用浏览器自动化」，若任务仅是查资料可改用融合搜索（python3 ~/.openclaw/workspace/scripts/hybrid_search.py "查询"），否则请用户检查配置或稍后重试。 Chrome/Edge profile：若使用 OpenClaw 的 Chrome 或 Edge 扩展模式，需在目标标签页先点击 OpenClaw 扩展图标完成连接；否则会报「no tab is connected」或「Click the OpenClaw Chrome extension icon on a tab to attach it」。连接后再执行 navigate/snapshot/act。

1. 获取当前页面结构

调用 browser 的 snapshot（默认 AI snapshot 带数字 ref）。 输出里会包含可交互元素的 ref（如 12、e12），用于后续点击/输入。

1. 根据 snapshot 决定动作

根据任务目标和 snapshot 中的按钮、链接、输入框、文字等，选一个 ref：

• 要点某处 → 记下该元素的 ref
• 要输入 → 记下输入框的 ref
• 要先去某页 → 用 navigate 或点链接的 ref

1. 执行动作

用 browser 的 act（或等价的 click/type/navigate）：

• 点击：act 或 click + 该 ref
• 输入：act 或 type + 输入框 ref + 文本
• 跳转：navigate 或点击链接 ref

1. 再看、再动

动作执行后，再次调用 snapshot 获取新页面状态，根据新内容决定下一步，重复 3→4→5，直到任务完成或触发失败出口/步数上限（见下）。

重要规则

• 动作的 ref 必须来自「当前一次」snapshot。页面跳转或 DOM 变化后 ref 会失效，必须重新 snapshot 再取新 ref。
• 不要猜 ref：没有 snapshot 就没有可靠 ref；若某次 click/type 报错，先重新 snapshot 再试。
• 一次一步：建议一次只做一个主要动作（一次点击或一次输入），然后 snapshot 再看，避免连续多步导致页面状态和 ref 对不上。
• 需要上传文件时：先 browser upload 指定本地路径并（可选）指定触发上传的 ref，再执行会打开文件选择器的点击；下载用 browser download 等。
• SPA/加载未完成：若某次 snapshot 返回内容极少或几乎没有可交互 ref，先用 browser wait（选择器或 load 状态）或短暂等待后再 snapshot，避免在未加载完的页面上操作。
• 登录与凭据：若页面需要账号密码且用户未提供，先向用户确认是否代填或请用户提供后再继续；set credentials 仅用于用户已确认的凭据。
• 安全：仅打开用户指定或任务明确相关的 URL；勿用 evaluate 执行用户提供的未校验字符串。

流程边界与失败出口

• 最大步数：同一任务下 snapshot→act 循环最多 15 步。若超过仍未完成，总结当前页面/状态并告知用户，不要无限循环。
• 明确失败（停止并回复用户）：（1）browser 工具不可用或连续报错 → 告知「当前环境无法使用浏览器」，若仅需查资料可改用融合搜索（python3 ~/.openclaw/workspace/scripts/hybrid_search.py "查询"）；（2）连续 2 次「找不到 ref / 元素不可见」→ 说明当前页面情况并建议用户检查或手动操作；（3）网络/导航错误且重试一次后仍失败；（4）需要登录且用户未提供凭据或未确认代填。

工具速查

• browser 工具子命令/参数：status / start / tabs / open / navigate / snapshot / act（click、type、fill、hover、drag、select 等）/ screenshot / wait / cookies 等。
• snapshot 返回的 ref：本技能为 OpenClaw browser 工具的 ref，数字如 12（AI snapshot）或 e12（role snapshot）；act 时用同一 ref。勿与 agent-browser 的 @e1、clawbrowser 的 e1 混用（那是不同 CLI 的输出）。
• 详细说明见 OpenClaw 文档：Browser (openclaw-managed) / browser 工具。

示例（抽象）

• 用户：「在知乎搜一下 OpenClaw」

→ navigate 到知乎搜索页或首页 → snapshot → 找到搜索框 ref → type 搜索框 ref "OpenClaw" → snapshot → 如需点「搜索」再点对应 ref。

• 用户：「打开 example.com 点第一个链接」

→ open/navigate 到 example.com → snapshot → 找到第一个链接的 ref → click 该 ref → snapshot 确认新页面。

按上述流程，浏览器就成为你完成任务的一种稳定方式：自己看、自己点、自己填，直到达成目标。