hermes教程-浏览器自动化

浏览器自动化

Hermes Agent 包含一套完整的浏览器自动化工具集，支持多种后端选项：

Browserbase 云模式：通过 Browserbase 使用托管云浏览器和反机器人工具
Browser Use 云模式：通过 Browser Use 作为替代云浏览器提供商
Firecrawl 云模式：通过 Firecrawl 使用内置抓取功能的云浏览器
Camofox 本地模式：通过 Camofox 进行本地反检测浏览（基于 Firefox 的指纹伪装）
本地 Chromium 系列 CDP：使用 /browser connect 将浏览器工具连接到您自己的 Chrome、Brave、Chromium 或 Edge 实例
本地浏览器模式：通过 agent-browser CLI 和本地 Chromium 安装

在所有模式下，代理都可以浏览网站、与页面元素交互、填写表单和提取信息。

概述

页面以无障碍树（基于文本的快照）的形式呈现，非常适合 LLM 代理。交互式元素会获得引用 ID（如 @e1、@e2），代理使用这些 ID 进行点击和输入。

关键能力：

多提供商云执行 — Browserbase、Browser Use 或 Firecrawl，无需本地浏览器
本地 Chromium 系列集成 — 通过 CDP 连接到您正在运行的 Chrome、Brave、Chromium 或 Edge 浏览器，进行实操浏览
内置隐身 — 随机指纹、验证码解决、住宅代理（Browserbase）
会话隔离 — 每个任务拥有独立的浏览器会话
自动清理 — 非活动会话超时后自动关闭
视觉分析 — 截图 + AI 分析，用于视觉理解

设置

提示 — Nous 订阅用户

如果您拥有付费的 Nous Portal 订阅，则可以通过 工具网关 使用浏览器自动化，无需单独的 API 密钥。新安装可运行 hermes setup --portal 登录并一次性开启所有网关工具；现有安装可通过 hermes model 或 hermes tools 选择 Nous Subscription 作为浏览器提供商。

Browserbase 云模式

要使用 Browserbase 管理的云浏览器，请添加：

bash

## 添加到 ~/.hermes/.env
BROWSERBASE_API_KEY=***
BROWSERBASE_PROJECT_ID=your-project-id-here

在 browserbase.com 获取您的凭据。

Browser Use 云模式

要使用 Browser Use 作为云浏览器提供商，请添加：

bash

## 添加到 ~/.hermes/.env
BROWSER_USE_API_KEY=***

在 browser-use.com 获取您的 API 密钥。Browser Use 通过其 REST API 提供云浏览器。如果同时设置了 Browserbase 和 Browser Use 的凭据，则 Browserbase 优先。

Firecrawl 云模式

要使用 Firecrawl 作为云浏览器提供商，请添加：

bash

## 添加到 ~/.hermes/.env
FIRECRAWL_API_KEY=fc-***

在 firecrawl.dev 获取您的 API 密钥。然后选择 Firecrawl 作为浏览器提供商：

bash

hermes setup tools
## → Browser Automation → Firecrawl

可选设置：

bash

## 自托管 Firecrawl 实例（默认：https://api.firecrawl.dev）
FIRECRAWL_API_URL=http://localhost:3002
## 会话 TTL（秒，默认：300）
FIRECRAWL_BROWSER_TTL=600

混合路由：公共 URL 使用云，本地/LAN 使用本地

当配置了云提供商时，Hermes 会自动为解析为私有/回环/LAN 地址（localhost、127.0.0.1、192.168.x.x、10.x.x.x、172.16-31.x.x、*.local、*.lan、*.internal、IPv6 回环 ::1、链路本地 169.254.x.x）的 URL 启动一个本地 Chromium 边车。公共 URL 在同一个对话中继续使用云提供商。

这解决了常见的“我在本地开发但使用 Browserbase”的工作流问题——代理可以截取 http://localhost:3000 上的仪表盘，同时抓取 https://github.com，而无需切换提供商或禁用 SSRF 防护。云提供商永远不会看到私有 URL。

该功能默认开启。要禁用它（所有 URL 都像以前一样发送到配置的云提供商）：

yaml

## ~/.hermes/config.yaml
browser:
  cloud_provider: browserbase
  auto_local_for_private_urls: false

禁用自动路由后，私有 URL 将被拒绝，并显示 "Blocked: URL targets a private or internal address"，除非您同时设置 browser.allow_private_urls: true（这会让云提供商尝试访问它们——通常不起作用，因为 Browserbase 等无法访问您的 LAN）。

要求：本地边车使用与纯本地模式相同的 agent-browser CLI，因此您需要安装它（hermes setup tools → Browser Automation 会自动安装）。从公共 URL 重定向到私有地址的导航后重定向仍会被阻止（您无法通过重定向到内部地址的技巧通过公共路径访问您的 LAN）。

Camofox 本地模式

Camofox 是一个自托管的 Node.js 服务器，封装了 Camoufox（一个带有 C++ 指纹伪装的 Firefox 分支）。它提供无需云依赖的本地反检测浏览。

bash

## 首先克隆 Camofox 浏览器服务器
git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
## 使用默认容器设置构建并启动 Docker
#（自动检测架构：M1/M2 上为 aarch64，Intel 上为 x86_64）
make up
## 停止并移除默认容器
make down
## 强制干净重建（例如，升级 VERSION/RELEASE 后）
make reset
## 仅下载二进制文件，不构建
make fetch
## 显式覆盖架构或版本
make up ARCH=x86_64
make up VERSION=135.0.1 RELEASE=beta.24

make up 会立即启动默认容器。如果您想要自定义运行时设置，例如更大的 Node 堆、VNC 或持久化配置文件目录，请先构建镜像，然后自行运行：

bash

## 构建镜像，不启动默认容器
make build
## 启动持久化、VNC 实时查看和更大的 Node 堆
mkdir -p ~/.camofox-docker
docker run -d \
  --name camofox-browser \
  --restart unless-stopped \
  -p 9377:9377 \
  -p 6080:6080 \
  -p 5901:5900 \
  -e CAMOFOX_PORT=9377 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  -e VNC_RESOLUTION=1920x1080 \
  -e MAX_OLD_SPACE_SIZE=2048 \
  -v ~/.camofox-docker:/root/.camofox \
  camofox-browser:135.0.1-aarch64

启用 VNC 后，浏览器以有头模式运行，可以在浏览器中通过 http://localhost:6080（noVNC）实时查看。您也可以使用原生 VNC 客户端连接到 localhost:5901。

如果您已经运行了 make up，请在启动自定义容器之前停止并移除该默认容器：

bash

make down
## 然后运行上面的自定义 docker run 命令

然后在 ~/.hermes/.env 中设置：

bash

CAMOFOX_URL=http://localhost:9377

如果 Camofox 在 Docker 中运行，并且您希望它打开主机上提供的 Web 应用程序，请启用回环重写。CAMOFOX_URL 仍应指向主机发布的控制 API，但页面 URL（例如 http://127.0.0.1:3000）必须从容器内部以 http://host.docker.internal:3000 的形式打开：

yaml

## ~/.hermes/config.yaml
browser:
  camofox:
    rewrite_loopback_urls: true
    loopback_host_alias: host.docker.internal  # 默认；如果需要，可以使用 LAN IP

等效的环境变量：

bash

CAMOFOX_REWRITE_LOOPBACK_URLS=true
CAMOFOX_LOOPBACK_HOST_ALIAS=host.docker.internal

重写仅适用于具有回环主机（localhost、127.0.0.1、::1）的页面导航 URL。它不会更改 CAMOFOX_URL。对于非 Docker 的 Camofox 安装，请保持禁用状态，因为浏览器已经在主机上运行，回环 URL 是正确的。

或者通过 hermes tools → Browser Automation → Camofox 进行配置。

当设置了 CAMOFOX_URL 时，所有浏览器工具将自动通过 Camofox 路由，而不是 Browserbase 或 agent-browser。

持久化浏览器会话

默认情况下，每个 Camofox 会话都会获得一个随机身份——Cookie 和登录状态在代理重启后不会保留。要启用持久化浏览器会话，请将以下内容添加到 ~/.hermes/config.yaml：

yaml

browser:
  camofox:
    managed_persistence: true

然后完全重启 Hermes，以便加载新配置。

警告 — 嵌套路径很重要

Hermes 读取 browser.camofox.managed_persistence，而不是顶层的 managed_persistence。一个常见的错误是写成：
yaml
# ❌ 错误 — Hermes 会忽略此项
managed_persistence: true
如果标志放在错误的路径下，Hermes 会静默回退到随机的临时 userId，您的登录状态将在每次会话中丢失。

Hermes 会做什么

向 Camofox 发送一个确定性的、配置文件范围的 userId，以便服务器可以在会话之间重用相同的 Firefox 配置文件。
在清理时跳过服务器端上下文销毁，因此 Cookie 和登录状态可以在代理任务之间保留。
将 userId 限定在活动的 Hermes 配置文件范围内，因此不同的 Hermes 配置文件会获得不同的浏览器配置文件（配置文件隔离）。

Hermes 不会做什么

它不会强制 Camofox 服务器进行持久化。Hermes 仅发送一个稳定的 userId；服务器必须通过将该 userId 映射到持久的 Firefox 配置文件目录来遵守它。
如果您的 Camofox 服务器构建将每个请求视为临时（例如，总是调用 browser.newContext() 而不加载存储的配置文件），Hermes 无法使这些会话持久化。请确保您运行的是实现了基于 userId 的配置文件持久化的 Camofox 构建。

验证是否正常工作

启动 Hermes 和您的 Camofox 服务器。
在浏览器任务中打开 Google（或任何登录网站）并手动登录。
正常结束浏览器任务。
启动一个新的浏览器任务。
再次打开同一个网站——您应该仍然处于登录状态。

如果第 5 步将您登出，则 Camofox 服务器没有遵守稳定的 userId。请仔细检查您的配置路径，确认在编辑 config.yaml 后完全重启了 Hermes，并验证您的 Camofox 服务器版本支持持久化的每用户配置文件。

状态存储位置

Hermes 从配置文件范围的目录 ~/.hermes/browser_auth/camofox/（或非默认配置文件下的 $HERMES_HOME 对应目录）派生稳定的 userId。实际的浏览器配置文件数据存储在 Camofox 服务器端，以该 userId 为键。要完全重置持久化配置文件，请在 Camofox 服务器上清除它，并删除相应的 Hermes 配置文件状态目录。

外部管理的 Camofox 会话

当另一个应用程序驱动可见的 Camofox 浏览器（桌面助手、自定义集成、另一个代理）时，配置 Hermes 在该相同身份内操作，而不是生成其自己的隔离配置文件。

有三个控制项：

设置	环境变量	效果
`browser.camofox.user_id`	`CAMOFOX_USER_ID`	Hermes 在创建标签页时使用的 Camofox `userId`。设置此项会使会话进入“外部管理”模式。
`browser.camofox.session_key`	`CAMOFOX_SESSION_KEY`	在创建标签页时发送的 `sessionKey`（也称为 `listItemId`）。用于在采用现有标签页时进行匹配。如果未设置，则默认为每个任务的值。
`browser.camofox.adopt_existing_tab`	`CAMOFOX_ADOPT_EXISTING_TAB`	如果为 true，Hermes 在首次使用时调用 `GET /tabs?userId=<user_id>`，并在创建新标签页之前重用现有标签页。

环境变量优先于 config.yaml。两种形式均可：

yaml

browser:
  camofox:
    user_id: shared-camofox
    session_key: visible-tab
    adopt_existing_tab: true

bash

CAMOFOX_USER_ID=shared-camofox
CAMOFOX_SESSION_KEY=visible-tab
CAMOFOX_ADOPT_EXISTING_TAB=true

当设置了 user_id 时会发生什么：

Hermes 在任务结束时跳过破坏性清理（与 managed_persistence: true 相同）。其他应用程序的标签页/Cookie/配置文件得以保留。
Hermes 不会调用 DELETE /sessions/<user_id>——该端点会清除所有用户数据，因此如果触发，会破坏外部应用程序的会话。

标签页采用如何工作（当 adopt_existing_tab: true 时）：

在进程启动后的第一次浏览器工具调用时，Hermes 发出 GET /tabs?userId=<user_id>（5 秒超时）。
如果响应中的任何标签页具有 listItemId == session_key，则 Hermes 采用该组中最近创建的标签页。
否则，Hermes 采用该用户最近创建的标签页（任意 listItemId）。
如果没有标签页存在或请求失败，Hermes 回退到在下一次操作时创建新标签页。

采用仅在会话的 tab_id 被填充之前触发。如果外部应用程序在运行过程中关闭了被采用的标签页，下一次浏览器工具调用将显示 Camofox 错误——Hermes 不会在每次调用时重新轮询新标签页。

选择 session_key： 如果您希望 Hermes 可靠地附加到特定现有标签页，请将 session_key 设置为外部应用程序在创建该标签页时使用的 listItemId。如果您不设置 session_key 而只设置 user_id，Hermes 会生成一个每个任务的 session_key（task_<id>）——Hermes 将与外部应用程序共享 Cookie 和配置文件，但会打开自己的标签页，而不是重用现有标签页。

并发注意事项： 外部应用程序和 Hermes 可以同时驱动同一个 Camofox userId，但 Camofox 不会在客户端之间协调每个标签页的焦点。请在应用程序层协调所有权（例如，在 Hermes 运行时外部应用程序暂停）。

VNC 实时查看

当 Camofox 以有头模式运行（带有可见的浏览器窗口）时，它会在健康检查响应中暴露一个 VNC 端口。Hermes 会自动发现该端口，并将 VNC URL 包含在导航响应中，以便代理可以共享一个链接供您实时观看浏览器。

通过 CDP 连接本地 Chromium 系列浏览器（`/browser connect`）

除了云提供商，您还可以通过 Chrome DevTools 协议（CDP）将 Hermes 浏览器工具附加到您自己正在运行的 Chrome、Brave、Chromium 或 Edge 实例。当您想实时查看代理的操作、与需要您自己的 Cookie/会话的页面交互，或避免云浏览器成本时，这非常有用。

注意

/browser connect 是一个交互式 CLI 斜杠命令——它不会通过网关调度。如果您尝试在 WebUI、Telegram、Discord 或其他网关聊天中运行它，该消息将作为纯文本发送给代理，命令不会执行。请从终端启动 Hermes（hermes 或 hermes chat），然后在那里发出 /browser connect。

在 CLI 中，使用：

text

/browser connect                 # 自动启动/连接到 http://127.0.0.1:9222 上的本地 Chromium 系列浏览器
/browser connect ws://host:port  # 连接到特定的 CDP 端点
/browser status                  # 检查当前连接
/browser disconnect              # 断开连接，返回云/本地模式

如果浏览器尚未以远程调试模式运行，Hermes 将尝试使用 --remote-debugging-port=9222 自动启动一个受支持的 Chromium 系列浏览器。检测包括 Brave、Google Chrome、Chromium 和 Microsoft Edge，以及常见的 Linux 安装路径，如 /opt/brave-bin/brave 和 /snap/bin/brave。

提示

要手动启动一个启用了 CDP 的 Chromium 系列浏览器，请使用专用的用户数据目录，这样即使浏览器已经以您的正常配置文件运行，调试端口也能正常启动：
bash
# Linux — Brave
brave-browser \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.hermes/chrome-debug \
  --no-first-run \
  --no-default-browser-check &

# Linux — Google Chrome
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.hermes/chrome-debug \
  --no-first-run \
  --no-default-browser-check &

# macOS — Brave
"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --no-first-run \
  --no-default-browser-check &

# macOS — Google Chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --no-first-run \
  --no-default-browser-check &
然后启动 Hermes CLI 并运行 /browser connect。

为什么使用 --user-data-dir？ 如果不使用它，在常规实例已经运行的情况下启动 Chromium 系列浏览器，通常会在现有进程上打开一个新窗口——而该现有进程启动时没有 --remote-debugging-port，因此端口 9222 永远不会打开。专用的用户数据目录会强制启动一个新的浏览器进程，使调试端口真正监听。--no-first-run --no-default-browser-check 会跳过新配置文件的首次启动向导。

通过 CDP 连接后，所有浏览器工具（browser_navigate、browser_click 等）将在您的实时浏览器实例上操作，而不是启动云会话。

WSL2 + Windows Chrome：优先使用 MCP 而非 `/browser connect`

如果 Hermes 在 WSL2 内运行，但您想要控制的 Chrome 窗口在 Windows 主机上运行，则 /browser connect 通常不是最佳路径。

原因：

/browser connect 期望 Hermes 本身能够访问一个可用的 CDP 端点
现代 Chrome 的实时调试会话通常暴露一个主机本地端点，该端点无法像经典的 9222 端口那样从 WSL 直接访问
即使 Windows Chrome 是可调试的，最干净的集成方式通常是让 Windows 端的浏览器 MCP 服务器附加到 Chrome，然后让 Hermes 与该 MCP 服务器通信

对于这种设置，请优先通过 Hermes MCP 支持使用 chrome-devtools-mcp。

请参阅 MCP 指南以获取实际设置：

在 Hermes 中使用 MCP

本地浏览器模式

如果您没有设置任何云凭据，并且不使用 /browser connect，Hermes 仍然可以通过由 agent-browser 驱动的本地 Chromium 安装来使用浏览器工具。

可选环境变量

bash

## 用于更好验证码解决的住宅代理（默认："true"）
BROWSERBASE_PROXIES=true
## 使用自定义 Chromium 的高级隐身——需要 Scale 计划（默认："false"）
BROWSERBASE_ADVANCED_STEALTH=false
## 断开连接后的会话重连——需要付费计划（默认："true"）
BROWSERBASE_KEEP_ALIVE=true
## 自定义会话超时（秒，最大 21600 = 6 小时）（默认：项目默认值）
## 示例：600（10 分钟）、1800（30 分钟）、21600（6 小时最大）
BROWSERBASE_SESSION_TIMEOUT=1800
## 自动清理前的非活动超时（秒，默认：120）
BROWSER_INACTIVITY_TIMEOUT=120
## 额外的 Chromium 启动标志（逗号或换行分隔）。当 Hermes 检测到 root 或 AppArmor 限制的非特权用户命名空间（Ubuntu 23.10+、DGX Spark、许多容器镜像）时，会自动注入
## `--no-sandbox,--disable-dev-shm-usage`，因此大多数用户无需设置此项。仅当您需要 Hermes 不会自动添加的标志时才手动设置；设置此项会禁用自动注入。
AGENT_BROWSER_ARGS=--no-sandbox

安装 agent-browser CLI

bash

npm install -g agent-browser
## 或在仓库中本地安装：
npm install

信息

browser 工具集必须包含在您配置的 toolsets 列表中，或者通过 hermes config set toolsets '["hermes-cli", "browser"]' 启用。

可用工具

`browser_navigate`

导航到 URL。必须在任何其他浏览器工具之前调用。初始化 Browserbase 会话。

Navigate to https://github.com/NousResearch

提示

对于简单的信息检索，请优先使用 web_search 或 web_extract——它们更快且更便宜。当您需要与页面交互（点击按钮、填写表单、处理动态内容）时，请使用浏览器工具。

`browser_snapshot`

获取当前页面无障碍树的基于文本的快照。返回带有引用 ID（如 @e1、@e2）的交互式元素，供 browser_click 和 browser_type 使用。

full=false（默认）：紧凑视图，仅显示交互式元素
full=true：完整页面内容

超过 8000 个字符的快照会自动由 LLM 进行摘要。

`browser_click`

点击由快照中的引用 ID 标识的元素。

Click @e5 to press the "Sign In" button

`browser_type`

在输入字段中键入文本。先清除字段，然后键入新文本。

Type "hermes agent" into the search field @e3

`browser_scroll`

向上或向下滚动页面以显示更多内容。

Scroll down to see more results

`browser_press`

按下键盘键。对于提交表单或导航很有用。

Press Enter to submit the form

支持的键：Enter、Tab、Escape、ArrowDown、ArrowUp 等。

`browser_back`

导航回浏览器历史记录中的上一页。

`browser_get_images`

列出当前页面上的所有图像及其 URL 和替代文本。对于查找要分析的图像很有用。

`browser_vision`

截取屏幕截图并使用视觉 AI 进行分析。当文本快照无法捕获重要的视觉信息时使用此工具——对于验证码、复杂布局或视觉验证挑战特别有用。

屏幕截图会持久保存，文件路径会与 AI 分析一起返回。在消息平台（Telegram、Discord、Slack、WhatsApp）上，您可以要求代理共享屏幕截图——它将通过 MEDIA: 机制作为原生照片附件发送。

What does the chart on this page show?

屏幕截图存储在 ~/.hermes/cache/screenshots/ 中，并在 24 小时后自动清理。

`browser_console`

获取当前页面的浏览器控制台输出（日志/警告/错误消息）和未捕获的 JavaScript 异常。对于检测无障碍树中未显示的静默 JS 错误至关重要。

Check the browser console for any JavaScript errors

使用 clear=True 在读取后清除控制台，以便后续调用仅显示新消息。

browser_console 在调用时带有 expression 参数时也会评估 JavaScript——与 DevTools 控制台相同，结果会解析返回（JSON 序列化的对象变为字典；原始值保持原始）。

text

browser_console(expression="document.querySelector('h1').textContent")
browser_console(expression="JSON.stringify(performance.timing)")

当当前会话有活动的 CDP 监督器时（对于任何针对支持 CDP 的后端运行过 browser_navigate 的会话都是典型的），评估通过监督器的持久 WebSocket 运行——没有子进程启动成本。否则回退到标准的 agent-browser CLI 路径。行为完全相同，只有延迟不同。

`browser_cdp`

原始 Chrome DevTools 协议直通——用于其他工具未涵盖的浏览器操作的逃生舱。用于原生对话框处理、iframe 范围评估、Cookie/网络控制或代理需要的任何 CDP 动词。

仅当会话启动时可访问 CDP 端点时才可用——意味着 /browser connect 已附加到正在运行的 Chrome、Brave、Chromium 或 Edge 浏览器，或者在 config.yaml 中设置了 browser.cdp_url。默认的本地 agent-browser 模式、Camofox 和云提供商（Browserbase、Browser Use、Firecrawl）目前不向此工具暴露 CDP——云提供商有每会话的 CDP URL，但实时会话路由是后续功能。

CDP 方法参考： https://chromedevtools.github.io/devtools-protocol/——代理可以使用 web_extract 提取特定方法的页面以查找参数和返回形状。

常见模式：

text

## 列出标签页（浏览器级别，无 target_id）
browser_cdp(method="Target.getTargets")
## 处理标签页上的原生 JS 对话框
browser_cdp(method="Page.handleJavaScriptDialog",
            params={"accept": true, "promptText": ""},
            target_id="<tabId>")
## 在特定标签页中评估 JS
browser_cdp(method="Runtime.evaluate",
            params={"expression": "document.title", "returnByValue": true},
            target_id="<tabId>")
## 获取所有 Cookie
browser_cdp(method="Network.getAllCookies")

浏览器级别的方法（Target.*、Browser.*、Storage.*）省略 target_id。页面级别的方法（Page.*、Runtime.*、DOM.*、Emulation.*）需要来自 Target.getTargets 的 target_id。每个无状态调用都是独立的——会话不会在调用之间持久化。

跨源 iframe： 传递 frame_id（来自 browser_snapshot.frame_tree.children[]，其中 is_oopif=true）以将 CDP 调用路由到该 iframe 的监督器实时会话。这是在 Browserbase 上跨源 iframe 内 Runtime.evaluate 的工作方式，因为无状态 CDP 连接会遇到签名 URL 过期。示例：

text

browser_cdp(
  method="Runtime.evaluate",
  params={"expression": "document.title", "returnByValue": True},
  frame_id="<frame_id from browser_snapshot>",
)

同源 iframe 不需要 frame_id——请改用来自顶层 Runtime.evaluate 的 document.querySelector('iframe').contentDocument。

`browser_dialog`

响应原生 JS 对话框（alert / confirm / prompt / beforeunload）。在此工具出现之前，对话框会静默阻塞页面的 JavaScript 线程，后续的 browser_* 调用会挂起或抛出；现在代理可以在 browser_snapshot 输出中看到待处理的对话框，并显式响应。

工作流程：

调用 browser_snapshot。如果对话框正在阻塞页面，它会显示为 pending_dialogs: [{"id": "d-1", "type": "alert", "message": "..."}]。
调用 browser_dialog(action="accept") 或 browser_dialog(action="dismiss")。对于 prompt() 对话框，传递 prompt_text="..." 以提供响应。
重新快照——pending_dialogs 为空；页面的 JS 线程已恢复。

检测自动进行，通过持久的 CDP 监督器——每个任务一个 WebSocket，订阅 Page/Runtime/Target 事件。监督器还会在快照中填充一个 frame_tree 字段，以便代理可以看到当前页面的 iframe 结构，包括跨源（OOPIF）iframe。

可用性矩阵：

后端	通过 `pending_dialogs` 检测	响应（`browser_dialog` 工具）
通过 `/browser connect` 或 `browser.cdp_url` 的本地 Chrome	✓	✓ 完整工作流程
Browserbase	✓	✓ 完整工作流程（通过注入的 XHR 桥接）
Camofox / 默认本地 agent-browser	✗	✗（无 CDP 端点）

在 Browserbase 上的工作原理。 Browserbase 的 CDP 代理会在服务器端约 10ms 内自动关闭真正的原生对话框，因此我们无法使用 Page.handleJavaScriptDialog。监督器通过 Page.addScriptToEvaluateOnNewDocument 注入一个小脚本，覆盖 window.alert/confirm/prompt 为同步 XHR。我们通过 Fetch.enable 拦截这些 XHR——页面的 JS 线程会一直阻塞在 XHR 上，直到我们调用 Fetch.fulfillRequest 并附上代理的响应。prompt() 的返回值会原样往返回页面 JS。

对话框策略 在 config.yaml 的 browser.dialog_policy 下配置：

策略	行为
`must_respond`（默认）	捕获，在快照中显示，等待显式的 `browser_dialog()` 调用。在 `browser.dialog_timeout_s`（默认 300 秒）后自动安全关闭，以防止有缺陷的代理无限期阻塞。
`auto_dismiss`	捕获，立即关闭。代理仍然会在 `browser_state` 历史中看到对话框，但无需操作。
`auto_accept`	捕获，立即接受。在导航具有激进的 `beforeunload` 提示的页面时很有用。

快照中的帧树 browser_snapshot.frame_tree 限制为 30 帧和 OOPIF 深度 2，以在广告繁重的页面上保持负载可控。当达到限制时，会显示 truncated: true 标志；需要完整树的代理可以使用 browser_cdp 和 Page.getFrameTree。

实际示例

填写 Web 表单

text

User: 在 example.com 上使用我的邮箱 john@example.com 注册一个账户

Agent workflow:
1. browser_navigate("https://example.com/signup")
2. browser_snapshot()  → 看到带有引用的表单字段
3. browser_type(ref="@e3", text="john@example.com")
4. browser_type(ref="@e5", text="SecurePass123")
5. browser_click(ref="@e8")  → 点击 "Create Account"
6. browser_snapshot()  → 确认成功

研究动态内容

text

User: GitHub 上目前最热门的仓库是什么？

Agent workflow:
1. browser_navigate("https://github.com/trending")
2. browser_snapshot(full=true)  → 读取热门仓库列表
3. 返回格式化结果

会话录制

自动将浏览器会话录制为 WebM 视频文件：

yaml

browser:
  record_sessions: true  # 默认：false

启用后，录制会在第一次 browser_navigate 时自动开始，并在会话关闭时保存到 ~/.hermes/browser_recordings/。在本地和云（Browserbase）模式下均有效。超过 72 小时的录制文件会自动清理。

隐身功能

Browserbase 提供自动隐身能力：

功能	默认	说明
基本隐身	始终开启	随机指纹、视口随机化、验证码解决
住宅代理	开启	通过住宅 IP 路由以获得更好的访问
高级隐身	关闭	自定义 Chromium 构建，需要 Scale 计划
保持连接	开启	网络故障后的会话重连

注意

如果您的计划中不包含付费功能，Hermes 会自动回退——首先禁用 keepAlive，然后是代理——因此浏览在免费计划上仍然有效。

会话管理

每个任务通过 Browserbase 获得一个隔离的浏览器会话
会话在非活动后自动清理（默认：2 分钟）
后台线程每 30 秒检查一次过期会话
进程退出时执行紧急清理，以防止孤立会话
会话通过 Browserbase API（REQUEST_RELEASE 状态）释放

限制

基于文本的交互 — 依赖无障碍树，而非像素坐标
快照大小 — 大页面可能被截断或由 LLM 在 8000 字符处摘要
会话超时 — 云会话根据您的提供商计划设置过期
成本 — 云会话消耗提供商积分；会话在对话结束或非活动后自动清理。使用 /browser connect 进行免费的本地浏览。
无文件下载 — 无法从浏览器下载文件

字节笔记本

hermes教程-浏览器自动化

浏览器自动化

概述

设置

Browserbase 云模式

Browser Use 云模式

Firecrawl 云模式

混合路由：公共 URL 使用云，本地/LAN 使用本地

Camofox 本地模式

持久化浏览器会话

Hermes 会做什么

Hermes 不会做什么

验证是否正常工作

状态存储位置

外部管理的 Camofox 会话

VNC 实时查看

通过 CDP 连接本地 Chromium 系列浏览器（/browser connect）

WSL2 + Windows Chrome：优先使用 MCP 而非 /browser connect

本地浏览器模式

可选环境变量

安装 agent-browser CLI

可用工具

browser_navigate

browser_snapshot

browser_click

browser_type

browser_scroll

browser_press

browser_back

browser_get_images

browser_vision

browser_console

browser_cdp

browser_dialog

实际示例

填写 Web 表单

研究动态内容

会话录制

隐身功能

会话管理

限制

通过 CDP 连接本地 Chromium 系列浏览器（`/browser connect`）

WSL2 + Windows Chrome：优先使用 MCP 而非 `/browser connect`

`browser_navigate`

`browser_snapshot`

`browser_click`

`browser_type`

`browser_scroll`

`browser_press`

`browser_back`

`browser_get_images`

`browser_vision`

`browser_console`

`browser_cdp`

`browser_dialog`