跳转至

浏览器代理工具

智能体在浏览器自动化中只有一个工具:

  • browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act/requests/errors/text/emulate

工具映射说明:

  • browser snapshot 返回稳定的 UI 树(AI 或 ARIA)。
  • 快照 query 仅保留包含全部以空白分隔的查询词元的行,忽略大小写。匹配行保留元素引用;结果报告匹配数量并遵循 maxChars。该查询搜索的是返回的快照,因此如果来源被截断,请增大快照范围。
  • browser requests 读取已收集的网络日志。可选的 filter 在 URL 或资源类型中匹配子字符串;limit 只保留最近的条目(默认 50)。结果报告已收集请求中匹配的 total 数与 returned 条数;输出预算可能会进一步减少该数量。clear=true 在读取后清除整个已收集日志,包括因过滤或限制而省略的条目。
  • browser errors 读取已收集的页面错误。limit 只保留最近的条目(默认 50)。结果报告已收集错误数 total 与 returned 条数;输出预算可能会进一步减少该数量。clear=true 在读取后清除整个已收集日志,包括因限制而省略的条目。页面错误属于不受信任的外部内容。
  • browser text 使用第一个显式匹配的 selector 提取可见正文,否则使用第一个 article、main 或 body。maxChars 必须为正数;其默认值为 40,000 个字符,且不能超过该值。工具的输出预算可能会进一步截断。页面文本属于不受信任的外部内容。
  • browser emulate 应用以下一个或多个设置:device(Playwright 设备名称)、colorScheme(dark、light、no-preference,或 none 以清除)、timezoneId 和 locale。设置按上述顺序应用,并返回 applied 列表;它们并非原子操作。这四个操作支持本地和节点目标,但不支持 Chrome MCP 现有会话配置文件。
  • browser navigate 还会内联返回已加载页面的快照(高效的交互层级,确保载荷保持紧凑且有界),因此智能体无需再次调用快照。报告跨文档导航的批量 act 结果会包含相同的最新页面状态。若导航最终解析为下载,则会跳过该快照。
  • browser act 使用快照中的 ref ID 执行点击、输入、拖动和选择操作。当已捕获的控件消失时,其绑定的 ref 将失效。在重试操作前,请先获取新的快照。
  • browser screenshot 捕获像素(整页、元素或带标签的 ref)。
  • 如果截图在浏览器仍在捕获或恢复页面设置时超时,该标签页上后续的截图、调整大小和设备更改操作将返回恢复错误。待捕获完成后重试。如果仍然卡住,请关闭并重新打开受影响的标签页;其他标签页仍可使用。
  • browser doctor 检查 Gateway、插件、配置文件、浏览器和标签页的就绪状态。
  • browser 接受以下参数:
  • profile:选择指定的浏览器配置文件(openclaw、chrome 或 remote CDP)。
  • target(sandbox | host | node):选择浏览器的运行位置。
  • 省略 target 和 node 时,使用已配置的路由。当沙箱浏览器桥接可用时,受管配置文件会使用它。没有沙箱桥接时,启用的 gateway.nodes.browser.node 固定节点会选择该节点,包括在手动路由模式下;如果固定节点不可用,则会失败,而不会切换到主机。
  • 无固定节点时,自动路由优先选择可用的主机浏览器,并在节点路由可用时选择单个已连接的浏览器节点。手动路由(无固定节点)以及禁用节点路由时使用主机。独立运行使用主机,除非选择了 Gateway 或节点路由;参见 远程与托管浏览器。
  • 显式指定 target="host" 会选择 Gateway 主机并绕过已配置的节点路由。显式指定 target="node" 或使用 node 选择器会请求节点路由;gateway.nodes.browser.mode="off" 会拒绝该请求。
  • 在沙箱会话中,主机和节点控制均要求 agents.defaults.sandbox.browser.allowHostControl=true。现有会话配置文件无法使用沙箱浏览器。当桥接可用时,除非显式选择了节点,否则它们使用主机,并遵循相同的主机控制策略。
  • 启用节点固定、无沙箱桥接且允许主机控制时,工具描述会将已配置的节点标识为默认。其他配置保留现有工具描述;该说明不依赖节点的实时连接状态。

这能让智能体保持确定性,并避免脆弱的选择器。

示例:智能体工具参数(复用 tabs 或 open 返回的 targetId):

{ "action": "requests", "targetId": "t1", "filter": "fetch", "limit": 20, "clear": true }
{ "action": "text", "targetId": "t1", "selector": "article", "maxChars": 6000 }
{ "action": "snapshot", "targetId": "t1", "query": "sign in", "maxChars": 4000 }

对于 Browser 仪表盘,请使用其稳定的组件名称而非标签页 ID:

{ "action": "snapshot", "dashboard": "service-status", "refs": "aria" }

dashboard 选择器仅适用于当前会话。请先使用 dashboard 工具创建已保存的 browser:dashboard 组件;其 props 选择 URL 和可选的受管配置文件。browser 会将仪表盘显示的同一页面解析用于快照、点击、输入和导航。请勿将该选择器与显式指定的配置文件、节点或目标 ID 组合使用。open 会显式恢复已停止的仪表盘,close 会停止其正在运行的浏览器。其他操作会让已停止的仪表盘保持停止状态。普通的原始标签页关闭操作无法关闭仪表盘拥有的标签页。

{
  "action": "emulate",
  "targetId": "t1",
  "device": "iPhone 15",
  "colorScheme": "dark",
  "timezoneId": "America/New_York",
  "locale": "en-US"
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw