10. Browser 浏览器与 Web 搜索工具

两种上网姿势：搜 vs 开

Agent 获取网页信息有两条路，先搞清楚什么时候用哪条。

轻量路线：web_search 搜关键词拿到结果列表，再用 web_extract 把感兴趣的页面正文提出来。这是 HTTP 请求级别的事，快、便宜、够用。绝大多数信息检索场景走这条。

重量路线：browser 工具集开一个真浏览器，能点击、填表、登录、等动态内容加载。启动浏览器实例更耗资源，但能干 HTTP 请求干不了的事—比如提交表单、处理验证码、操作需要登录的页面。

web_search 与 web_extract：多后端搜索

两个工具通过同一个后端配置工作。web_search 返回排名结果（标题+URL+摘要），web_extract 抓取并提取 URL 的可读内容。

支持的后端

后端	环境变量	搜索	提取	免费额度
Firecrawl（默认）	FIRECRAWL_API_KEY	有	有	500 次/月
SearXNG	SEARXNG_URL	有	无	免费（自建）
Brave Search	BRAVE_SEARCH_API_KEY	有	无	2000 次/月
DDGS（DuckDuckGo）	无需 Key	有	无	免费
Tavily	TAVILY_API_KEY	有	有	1000 次/月
Exa	EXA_API_KEY	有	有	1000 次/月
Parallel	PARALLEL_API_KEY	有	有	付费
xAI（Grok）	XAI_API_KEY 或 OAuth	有	无	付费

注意：Brave、DDGS、xAI 是纯搜索后端，不能提取页面内容。要同时用搜索和提取，得配两个后端。

搜索和提取分开配

这是个省钱的关键能力—搜索和提取可以用不同后端：

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"      # web_search 用免费的 SearXNG
  extract_backend: "firecrawl"   # web_extract 用 Firecrawl

这样组合免费搜索 + 高质量提取，成本最低。优先级是：显式分能力配置 > web.backend 共用 > 按环境变量自动检测。

长页面怎么处理

web_extract 返回的原始 markdown 可能很大。为了不撑爆上下文窗口，它按页面大小分级处理：

页面大小（字符）	处理方式
5000 以下	原样返回，不调 LLM
5000 - 50 万	单次摘要，输出上限约 5000 字符
50 万 - 200 万	分块并行摘要再综合
200 万以上	拒绝，提示用更聚焦的 URL

SearXNG：免费自建搜索

SearXNG 是隐私优先的开源元搜索引擎，聚合 70+ 搜索引擎结果，不需要 API Key。用 Docker 自建一个，零成本零限速：

# ~/searxng/docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    restart: unless-stopped

启动后记得在 settings.yml 里开启 JSON 格式输出（默认关闭），否则 Hermes 拿不到结果：

search:
  formats:
    - html
    - json

# ~/.hermes/.env
SEARXNG_URL=http://localhost:8888

x_search：搜推特专用

x_search 让 Agent 直接搜 X（推特）的帖子、账号和话题。它走的是 xAI Responses API 上 Grok 自带的 x_search 工具—Grok 在服务端执行搜索，返回带引用的合成结果。

和 web_search 的区别：web_search 搜普通网页，x_search 专门搜推特上的讨论、反应和观点。想了解”大家对某事的看法”用 x_search，想查文档和网页用 web_search。

认证方式

两种凭据任选其一，同时配了 OAuth 优先：

凭据	来源	设置
SuperGrok / X Premium+ OAuth（推荐）	浏览器登录 accounts.x.ai，自动刷新	hermes auth add xai-oauth
XAI_API_KEY	付费 xAI API Key	写进 ~/.hermes/.env

默认有 xAI 凭据就自动启用。不想用可以在 hermes tools 里关掉。

工具参数

# ~/.hermes/config.yaml
x_search:
  model: grok-4.5              # 推荐默认
  timeout_seconds: 180         # 复杂查询可能要 60-120 秒
  retries: 2                   # 5xx/超时自动重试

调用时支持的参数：query（必填）、allowed_x_handles（只看某些账号，最多 10 个）、excluded_x_handles（排除某些账号）、from_date/to_date（日期范围）、enable_image_understanding（分析帖子图片）、enable_video_understanding（分析帖子视频）。

browser 工具集：10 个核心工具

浏览器工具集的核心设计是无障碍树（Accessibility Tree）。Agent 看到的不是 HTML，也不是截图，而是一棵描述”页面上有什么可以点、可以填”的语义树。

打个比方：HTML 是建筑蓝图（全是 div 嵌套），无障碍树是导览图（“这是搜索框""这是提交按钮”）。每个可交互元素有个编号，比如 @e1、@e2，Agent 点击时说 browser_click(ref="e3") 就行，不用写 CSS 选择器。

10 个核心工具：

工具	功能
browser_navigate	导航到 URL，必须先调它初始化会话
browser_snapshot	取页面无障碍树文本快照，返回带 ref ID 的交互元素
browser_click	按 ref ID 点击元素
browser_type	往输入框打字（先清空再打）
browser_scroll	滚动页面，露出更多内容
browser_press	按键（Enter/Tab/Escape 等）
browser_back	后退到上一页
browser_vision	截图并用视觉 AI 分析
browser_console	取控制台输出和 JS 错误，也能执行 JS
browser_get_images	列出页面所有图片的 URL 和 alt 文本

一次完整的表单交互

Agent 帮你在 GitHub 搜索，流程是这样的：

1. browser_navigate("https://github.com")
   -> 返回快照：search "Search GitHub" [ref=e3] ...

2. browser_click(ref="e3")
   -> 搜索框获得焦点

3. browser_type(ref="e3", text="Hermes Agent")
   -> 填入搜索词

4. browser_press(key="Enter")
   -> 提交搜索

5. browser_snapshot()
   -> 返回结果页：link "NousResearch/hermes-agent" [ref=e5] ...

6. Agent 读快照，给你总结结果

全程没写 CSS 选择器，没解析 HTML，没定位坐标。靠 ref ID 和语义描述完成一切。

快照的大小控制

browser_snapshot 有两种模式：full=false（默认，只显示交互元素）和 full=true（完整页面内容）。

超过 15000 字符的快照会自动截断或用 LLM 摘要。完整快照会存到 ~/.hermes/cache/web/，工具输出里带文件路径和现成的 read_file 调用，Agent 能翻页看完整无障碍树。

browser_vision：什么时候用

无障碍树搞不定的场景才上 browser_vision：

• 验证码和图片内容
• 复杂可视化（图表、地图）
• 需要理解视觉布局时

截图存到 ~/.hermes/cache/screenshots/，24 小时后自动清理。在消息平台（Telegram/Discord/Slack/WhatsApp）上可以让 Agent 把截图当原生图片发给你。

2 个 CDP 网关工具

browser_cdp 和 browser_dialog 这两个工具属于 browser 工具集，但只有在会话启动时能连上 Chrome DevTools Protocol（CDP）端点才会注册。

browser_cdp：原始 CDP 逃生口

browser_cdp 是高级用户的逃生口—当其他浏览器工具覆盖不了你的需求时，直接发原始 CDP 命令。用途包括原生对话框处理、iframe 内执行 JS、cookie/网络控制。

browser_cdp(method="Target.getTargets")                              # 列出所有标签页
browser_cdp(method="Network.getAllCookies")                          # 取所有 cookie
browser_cdp(method="Runtime.evaluate",
            params={"expression": "document.title", "returnByValue": true},
            target_id="<tabId>")                                      # 在指定标签页执行 JS

浏览器级方法（Target.*、Browser.*、Storage.*）不用传 target_id；页面级方法（Page.*、Runtime.*、DOM.*）需要从 Target.getTargets 拿 target_id。

browser_dialog：处理原生 JS 对话框

alert/confirm/prompt/beforeunload 这类原生对话框会阻塞页面的 JS 线程。以前 Agent 遇到它们会卡住或报错，现在有了 browser_dialog：

1. 调 browser_snapshot，如果有对话框会显示 pending_dialogs: [{"id": "d-1", "type": "alert", ...}]
2. 调 browser_dialog(action="accept") 或 browser_dialog(action="dismiss")，prompt 类型还能传 prompt_text
3. 重新 browser_snapshot，对话框消失，页面 JS 恢复

对话框策略可在 config.yaml 配：

策略	行为
must_respond（默认）	捕获并显示，等 Agent 显式响应；300 秒安全超时自动关闭
auto_dismiss	捕获后立即关闭
auto_accept	捕获后立即接受，适合有激进 beforeunload 的页面

多种浏览器后端

Hermes 支持六种浏览器后端，决定浏览器在哪跑、用什么方式跑。

云端后端

Browserbase：托管云浏览器，带反检测能力（随机指纹、验证码解决、住宅代理）。配 BROWSERBASE_API_KEY 和 BROWSERBASE_PROJECT_ID 即可。

Browser Use：替代云浏览器提供商，配 BROWSER_USE_API_KEY。和 Browserbase 同时配了的话，Browserbase 优先。

Firecrawl：带内置抓取的云浏览器，配 FIRECRAWL_API_KEY，通过 hermes setup tools -> Browser Automation -> Firecrawl 选择。

本地后端

Camofox：自建的 Firefox 反检测浏览器（C++ 级指纹伪装）。clone 仓库后 make up 启动 Docker 容器，配 CAMOFOX_URL=http://localhost:9377。支持持久化会话和 VNC 实时查看。

本地 CDP 连接：通过 /browser connect 把工具接到你自己跑的 Chrome/Brave/Chromium/Edge 实例。适合想实时看 Agent 操作、用自己 cookie、省云浏览器费用的场景。

/browser connect                 # 自动启动/连接本地 Chromium 系浏览器
/browser connect ws://host:port  # 连接指定 CDP 端点
/browser status                  # 查看当前连接
/browser disconnect              # 断开，回到云/本地模式

本地 agent-browser 模式：不配任何云凭据也不用 /browser connect 时，Hermes 通过 agent-browser CLI 驱动本地 Chromium 安装。

混合路由：云端公共，本地内网

配了云后端时，Hermes 会自动给私有/本地地址（localhost、127.0.0.1、192.168.x.x、10.x.x.x 等）起一个本地 Chromium 边车，公共 URL 继续走云端。

这解决了一个常见痛点：你在本地开发但用 Browserbase，Agent 既能截 http://localhost:3000 的仪表盘，又能抓 https://github.com，不用切换后端。云端后端永远看不到你的私有 URL。

# ~/.hermes/config.yaml
browser:
  cloud_provider: browserbase
  auto_local_for_private_urls: false   # 关掉后所有 URL 都走云端

会话管理与录制

会话隔离与清理

• 每个任务有独立的浏览器会话
• 不活跃的会话自动清理（默认 2 分钟无活动）
• 每 30 秒检查一次过期会话
• 进程退出时紧急清理，防止孤儿会话

会话录制

开启后自动把浏览器会话录成 WebM 视频：

browser:
  record_sessions: true    # 默认 false

录制在首次 browser_navigate 时开始，会话关闭时存到 ~/.hermes/browser_recordings/，72 小时后自动清理。本地和云端模式都支持。

有头模式

默认本地浏览器无头跑。开启有头模式能拿到一个可见的 Chromium 窗口，你可以实时看 Agent 操作、手动介入（登录挑战、验证码）：

browser:
  headed: true    # 默认 false

有头模式会跳过每轮清理，窗口跨对话保持打开。空闲会话仍按 browser.inactivity_timeout（默认 120 秒）回收。

浏览器工具的边界

几个限制心里有数：

• 基于文本交互：靠无障碍树，不是像素坐标
• 快照大小：大页面可能被截断或摘要（15000 字符阈值）
• 会话超时：云会话按提供商套餐过期
• 成本：云会话消耗提供商额度，对话结束或不活跃时自动清理
• 不能下载文件：浏览器工具不支持文件下载

三个常见坑

每次操作都截图走视觉模型。截图+视觉分析要 2-5 秒还烧 token。修：默认 browser_snapshot，只在需要视觉理解时才 browser_vision。

用旧的 ref 操作已变化的页面。点了链接页面跳转后，旧 ref 编号失效。修：页面变化后必须重新 browser_snapshot 拿新编号。

不等页面加载完就操作。browser_navigate 返回后可能还在加载 JS。修：agent-browser 会等页面稳定再返回；如果内容靠 AJAX 延迟加载，先 browser_snapshot 检查完整性，不完整就等一下再取。