浏览器代理工具
智能体在浏览器自动化中只有一个工具:
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使用快照中的refID 执行点击、输入、拖动和选择操作。当已捕获的控件消失时,其绑定的 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):
对于 Browser 仪表盘,请使用其稳定的组件名称而非标签页 ID:
dashboard 选择器仅适用于当前会话。请先使用 dashboard 工具创建已保存的 browser:dashboard 组件;其 props 选择 URL 和可选的受管配置文件。browser 会将仪表盘显示的同一页面解析用于快照、点击、输入和导航。请勿将该选择器与显式指定的配置文件、节点或目标 ID 组合使用。open 会显式恢复已停止的仪表盘,close 会停止其正在运行的浏览器。其他操作会让已停止的仪表盘保持停止状态。普通的原始标签页关闭操作无法关闭仪表盘拥有的标签页。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw