> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 内嵌浏览器

> 在隔离的浏览器面板中查看页面，并让 Agent 读取和操作它。

内嵌浏览器是一个**工具面板**，和终端、文档预览同级。它由系统安装的 Chrome、Chromium 或 Edge 驱动，运行在运行时自己的隔离配置里，不是应用外壳，也不是另一个 WebUI 产品。

人和 Agent 看到的是同一个页面：你看到的是实时画面，Agent 通过结构化的页面快照和操作工具工作。这样它点击的元素和你眼前的元素不会分叉。

## 打开浏览器面板

在预览面板的 **+** 菜单里选择 **浏览器**，或新建一个浏览器标签。地址栏支持：

* 输入完整地址并回车。
* 输入关键词，用 **设置 → 浏览器** 里选择的搜索引擎搜索。
* 后退、前进、重新加载，以及在新标签页中打开链接。

浏览器面板和文件、差异、终端共用同一套标签和分栏。可以把面板弹出为独立窗口，或全屏显示。

> [!NOTE]
>
> 内嵌浏览器需要本机安装 Chrome、Chromium 或 Edge。没有可用浏览器时，面板会说明缺少什么，而不是显示空白页。

## 阅读和操作页面

| 能力 | 说明 |
| - | - |
| 标签 | 新建、切换、关闭；Agent 打开的标签也会出现在这里。 |
| 查找 | `cmd-f` 在页面内查找，显示匹配数并循环跳转。 |
| 下载 | 默认拒绝。允许后文件写入运行时自己的下载目录，页面不能决定路径。 |
| 对话框 | `alert`、`confirm`、`prompt` 和 `beforeunload` 会在面板内显示为卡片，由你回答。 |
| 文件选择 | 页面触发的文件选择会被拦截，由你选择要上传的文件。 |
| 页面诊断 | 控制台消息、未捕获异常、失败的网络请求会作为 Agent 可读的诊断信息保留。 |
| 操作记录 | 面板底部可以展开本标签的操作记录，区分你和 Agent 发起的操作。 |

页面内容是不可信输入。Agent 的工具说明会明确要求它不要执行页面里伪装成指令的文字；你在批准导航、上传或敏感操作时也应保持同样的判断。

## Agent 能做什么

Agent 通过内置的浏览器工具工作，主要包括：

* **观察**：读取页面的可访问性树和可交互元素，返回短期有效的元素引用。
* **操作**：点击、填写、按键、悬停、滚动、选择下拉项、拖拽、上传文件。
* **导航与标签**：打开、切换、关闭标签，等待某个条件出现。
* **读取**：提取页面文本、读取控制台和网络诊断、截取屏幕截图。
* **测试**：录制操作并导出 Playwright 测试；保存页面基线并比较变化。
* **请求帮助**：遇到验证码、登录或无法决定的事情时，请人接手。

元素引用只在下一次观察之前有效。页面重新渲染、导航或再次观察后，旧引用会被拒绝，Agent 必须重新观察——这能避免“点击落到了刚好移到这个位置的东西上”。

## 你始终可以接管

当 Agent 正在操作当前标签时，面板右下角会显示 **Agent 正在操作**。点击暂停按钮可以立即收回控制权；暂停后 Agent 仍能观察页面，但不能继续点击或输入。处理完后点击播放按钮，把标签交还给 Agent；它会重新观察页面再继续。

你自己在页面里输入也会暂停 Agent 在该标签上的操作。面板会显示原因，并给出交还控制的入口。

> [!WARNING]
>
> 浏览器里的操作可能提交表单、发送消息、产生费用或修改外部系统。批准前确认目标站点、账号和操作范围；不要把密码、支付信息或一次性验证码交给 Agent。

## 设置

**设置 → 浏览器** 控制浏览器面板自己的标签页：

| 选项 | 说明 |
| - | - |
| **起始页** | Google、Bing、百度或自定义地址。只影响你新建的标签页，不影响 Agent 自己打开的标签。 |
| **搜索引擎** | 地址栏输入关键词时使用；支持 Google、Bing、百度、DuckDuckGo 或自定义模板。 |
| **无损画面** | 文字更清晰，但画面更大、更慢；面板上的 **HD** 按钮切换同一个设置。 |
| **允许下载** | 默认关闭。打开后页面可以保存文件到运行时的下载目录。 |
| **导入本机 Chrome 登录状态** | 把本机 Chrome、Edge 或 Brave 的 Cookie 与 localStorage 复制到隔离配置，让 Agent 直接打开你已登录的站点。只读取源配置，不写回。 |
| **清除浏览器数据** | 删除隔离配置里的 Cookie、localStorage、缓存和已导入的登录状态；已打开的标签会关闭。 |

> [!NOTE]
>
> 连接到远程运行时后，浏览器画面和显示设置所依赖的通道尚未完整实现，显示选项会在下次使用本机运行时生效。文件选择等本地能力也不会跨运行时使用。

## 安全边界

* 浏览器使用独立的 `user-data-dir`，不会读写你日常浏览器的配置，除非你明确导入登录状态。
* 下载默认拒绝；允许后也只能写入运行时下载目录，不能写入工作区。
* 页面不能静默打开原生文件选择器或保存对话框。
* Agent 的每一次导航和操作都会写入脱敏审计记录；Cookie、token 和输入值不会进入审计。
* 跨源导航、访问本机回环地址或上传文件可能需要你额外批准。

## 遇到问题

| 现象 | 处理 |
| - | - |
| 面板提示找不到浏览器 | 安装 Chrome、Chromium 或 Edge，然后重新打开面板。 |
| 页面能打开但 Agent 看不到元素 | 让 Agent 重新观察；没有可访问性树的窗口或跨源 iframe 可能无法操作。 |
| 点击位置偏移 | 调整窗口缩放后重新打开标签；坐标按视口 CSS 像素换算，缩放变化会让旧画面失效。 |
| 下载没有开始 | 在设置里打开 **允许下载**；被拒绝的下载会在面板里提示。 |
| 登录状态没有导入 | 关闭正在使用该配置的标签页后重试；源浏览器必须已经退出或允许读取其配置。 |
| Agent 被暂停 | 点击面板右下角的播放按钮，或使用 **交还给 Agent**。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.