浏览器代理工具

智能体进行浏览器自动化时只获得一个工具：

• 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 列表；它们不是原子操作。这四个操作支持本地（local）和节点（node）目标，但不支持 Chrome MCP 的现有会话配置文件。
• browser navigate 还会内联返回已加载页面的快照（高效的交互层级，因此有效负载保持紧凑且有界），因此智能体无需再调用快照。报告跨文档导航的批量 act 结果也会包含相同的全新页面状态。解析为下载的导航会跳过该快照。
• browser act 使用快照的 ref ID 来执行点击/输入/拖拽/选择。 当捕获的控件消失时，其绑定的 ref 会失效。在重试操作前，请先获取新快照。
• browser screenshot 捕获像素（整页、元素或带标签的 refs）。
• 如果截图超时，而浏览器仍在捕获或恢复页面设置，那么在该标签页上继续截图、调整大小或更改设备将返回恢复错误。请在捕获完成后重试。如果仍然卡住，请关闭并重新打开受影响的标签页；其他标签页仍然可用。
• browser doctor 检查 Gateway、插件、配置文件、浏览器和标签页的就绪状态。
• browser 接受以下参数：
• profile：用于选择指定的浏览器配置文件（openclaw、chrome 或远程 CDP）。
• target（sandbox | host | node）：用于选择浏览器所在位置。
• 在沙箱会话中，target: "host" 要求设置 agents.defaults.sandbox.browser.allowHostControl=true。
• 如果省略 target：沙箱会话默认使用 sandbox，非沙箱会话默认使用 host。
• 自动路由优先使用主机浏览器。如果本地浏览器能力不可用，则可以使用单个已连接的浏览器节点。显式指定 target="node"、使用 node 选择器或已配置的节点固定会覆盖该偏好；target="host" 则保持本地。

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

智能体工具参数示例（可复用来自 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 }

对于浏览器仪表盘，请使用其稳定的组件名称，而不是标签页 ID：

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

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

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