网页搜索与提取（Web Search & Extract）

Hermes Agent 包含由多个提供商支持的三种网络工具：

web_search — 搜索网络并返回排名结果
web_extract — 从一个或多个 URL 获取并提取可读内容
web_crawl — 递归爬取站点并返回结构化内容

三种工具均通过单一后端选择配置。提供商通过 hermes tools 选择或直接在 config.yaml 中设置。

后端

提供商	环境变量	搜索	提取	爬取	免费层
Firecrawl（默认）	`FIRECRAWL_API_KEY`	✔	✔	✔	500 额度/月
SearXNG	`SEARXNG_URL`	✔	—	—	✔ 免费（自托管）
Tavily	`TAVILY_API_KEY`	✔	✔	✔	1,000 次搜索/月
Exa	`EXA_API_KEY`	✔	✔	—	1,000 次搜索/月
Parallel	`PARALLEL_API_KEY`	✔	✔	—	付费

按能力分配： 你可以为搜索和提取独立使用不同的提供商——例如用 SearXNG（免费）搜索，用 Firecrawl 提取。参见下方按能力配置。

Nous 订阅者

如果你有付费 Nous Portal 订阅，网页搜索和提取可通过**工具网关（Tool Gateway）**使用托管的 Firecrawl——无需 API 密钥。运行 hermes tools 启用。

`web_extract` 如何处理长页面

后端返回原始页面 Markdown，这可能非常大（论坛帖子、文档站点、带有嵌入式评论的新闻文章）。为了保持你的上下文窗口可用并降低成本，web_extract 在将内容交给 Agent 之前，会通过 web_extract 辅助模型运行返回的内容。行为完全由大小驱动：

页面大小（字符数）	发生什么
5,000 以下	按原样返回 —— 无 LLM 调用，完整 Markdown 到达 Agent
5,000 – 500,000	通过 `web_extract` 辅助模型进行单次摘要，输出上限约 5,000 字符
500,000 – 2,000,000	分块：拆分为 100k 字符的块，并行摘要每个块，然后合成最终摘要（约 5,000 字符）
超过 2,000,000	拒绝并提示使用带有聚焦提取指令的 `web_crawl` 或更具体的来源

摘要保留引用、代码块和关键事实的原始格式 —— 它是一个内容压缩器，而不是改写器。如果摘要失败或超时，Hermes 会回退到原始内容的前约 5,000 个字符，而不是无用的错误。

哪个模型做摘要？

web_extract 辅助任务。默认情况下（auxiliary.web_extract.provider: "auto"），这是你的主聊天模型 —— 相同的提供商，相同的 hermes model 模型。这对大多数设置来说没问题，但在昂贵的推理模型（Opus、MiniMax M2.7 等）上，每个长页面提取都会增加可观的成本。

要将提取摘要路由到便宜、快速的模型（无论你的主模型是什么）：

# ~/.hermes/config.yaml
auxiliary:
  web_extract:
    provider: openrouter
    model: google/gemini-3-flash-review
    timeout: 360       # 秒；如果你遇到摘要超时，请提高

或交互式选择：hermes model → 配置辅助模型 → web_extract。

有关完整参考和每任务覆盖模式，请参见辅助模型。

当摘要成为障碍时

如果你特别需要原始、未摘要的页面内容 —— 例如，你正在抓取一个结构化页面，LLM 摘要会丢弃重要字段 —— 请改用 browser_navigate + browser_snapshot。浏览器工具返回实时可访问性树，无需辅助模型重写（在超大页面上受其自身的 8,000 字符快照限制）。

设置

通过 `hermes tools` 快速设置

运行 hermes tools，导航到 Web Search & Extract，选择提供商。向导会提示输入所需的 URL 或 API 密钥，并写入配置。

hermes tools

Firecrawl（默认）

功能完整的搜索、提取和爬取。推荐大多数用户使用。

# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-your-key-here

在 firecrawl.dev 获取密钥。免费层每月包含 500 额度。

自托管 Firecrawl： 指向你自己的实例而非云端 API：

# ~/.hermes/.env
FIRECRAWL_API_URL=http://localhost:3002

设置 FIRECRAWL_API_URL 后，API 密钥为可选（用 USE_DB_AUTHENTICATION=false 禁用服务器认证）。

SearXNG（免费，自托管）

SearXNG 是一个隐私友好的开源元搜索引擎，聚合来自 70+ 搜索引擎的结果。无需 API 密钥——只需将 Hermes 指向运行中的 SearXNG 实例即可。

SearXNG 仅支持搜索——web_extract 和 web_crawl 需要单独的提取提供商。

选项 A — 使用 Docker 自托管（推荐）

这为你提供没有速率限制的私有实例。

1. 创建工作目录：

mkdir -p ~/searxng/searxng
cd ~/searxng

2. 编写 docker-compose.yml：

# ~/searxng/docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888/
    restart: unless-stopped

3. 启动容器：

docker compose up -d

4. 启用 JSON API 格式：

SearXNG 默认禁用 JSON 输出。从容器中复制生成的配置并启用它：

# Copy the auto-generated config out of the container
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml

打开 ~/searxng/searxng/settings.yml 并找到 formats 块（约第 84 行）：

# Before (default — JSON disabled):
formats:
  - html

# After (enable JSON for Hermes):
formats:
  - html
  - json

5. 重启以应用：

docker cp ~/searxng/searxng/settings.yml searxng:/etc/searxng/settings.yml
docker restart searxng

6. 验证工作正常：

curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{len(d[\"results\"])} results')"

你应该看到类似 10 results 的输出。如果收到 403 Forbidden，说明 JSON 格式仍被禁用——重新检查步骤 4。

7. 配置 Hermes：

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

然后在 ~/.hermes/config.yaml 中选择 SearXNG 作为搜索后端：

web:
  search_backend: "searxng"

或通过 hermes tools → Web Search & Extract → SearXNG 设置。

选项 B — 使用公共实例

公共 SearXNG 实例列在 searx.space。筛选具有 JSON 格式已启用的实例（在表格中显示）。

# ~/.hermes/.env
SEARXNG_URL=https://searx.example.com

公共实例

公共实例有速率限制、稳定性不稳定，且可能随时禁用 JSON 格式。生产使用强烈推荐自托管。

将 SearXNG 与提取提供商配对

SearXNG 处理搜索；你需要单独的提供商用于 web_extract 和 web_crawl。使用按能力配置键：

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"
  extract_backend: "firecrawl"   # or tavily, exa, parallel

使用此配置，Hermes 使用 SearXNG 处理所有搜索查询，使用 Firecrawl 处理 URL 提取——将免费搜索与高质量提取结合起来。

Tavily

AI 优化的搜索、提取和爬取，具有慷慨的免费层。

# ~/.hermes/.env
TAVILY_API_KEY=tvly-your-key-here

在 app.tavily.com 获取密钥。免费层每月包含 1,000 次搜索。

Exa

语义理解的神经搜索。适合研究和查找概念相关内容。

# ~/.hermes/.env
EXA_API_KEY=your-exa-key-here

在 exa.ai 获取密钥。免费层每月包含 1,000 次搜索。

Parallel

具有深度研究能力的 AI 原生搜索和提取。

# ~/.hermes/.env
PARALLEL_API_KEY=your-parallel-key-here

在 parallel.ai 申请访问权限。

配置

单一后端

为所有网络能力设置一个提供商：

# ~/.hermes/config.yaml
web:
  backend: "searxng"   # firecrawl | searxng | tavily | exa | parallel

按能力配置

为搜索和提取使用不同的提供商。这让你可以将免费搜索（SearXNG）与付费提取提供商组合，或反之：

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"     # used by web_search
  extract_backend: "firecrawl"  # used by web_extract and web_crawl

当按能力配置键为空时，两者都回退到 web.backend。当 web.backend 也为空时，后端从存在的 API 密钥/URL 自动检测。

优先级顺序（按能力）：

web.search_backend / web.extract_backend（显式按能力）
web.backend（共享回退）
从环境变量自动检测

自动检测

如果没有显式配置后端，Hermes 根据设置的凭证选择第一个可用的：

存在的凭证	自动选择的后端
`FIRECRAWL_API_KEY` 或 `FIRECRAWL_API_URL`	firecrawl
`PARALLEL_API_KEY`	parallel
`TAVILY_API_KEY`	tavily
`EXA_API_KEY`	exa
`SEARXNG_URL`	searxng

验证设置

运行 hermes setup 查看检测到的网络后端：

✅ Web Search & Extract (searxng)

或通过 CLI 检查：

# Activate the venv and run the web tools module directly
source ~/.hermes/hermes-agent/.venv/bin/activate
python -m tools.web_tools

输出活跃后端及其状态：

✅ Web backend: searxng
   Using SearXNG (search only): http://localhost:8888

故障排查

`web_search` 返回 `{"success": false}`

检查 SEARXNG_URL 是否可访问：curl -s "http://localhost:8888/search?q=test&format=json"
如果收到 HTTP 403，说明 JSON 格式被禁用——在 settings.yml 的 formats 列表中添加 json 并重启
如果连接错误，容器可能未运行：docker ps | grep searxng

`web_extract` 提示"search-only backend"

SearXNG 无法提取 URL 内容。将 web.extract_backend 设置为支持提取的提供商：

web:
  search_backend: "searxng"
  extract_backend: "firecrawl"  # or tavily / exa / parallel

SearXNG 返回 0 个结果

一些公共实例禁用了某些搜索引擎或类别。尝试：

不同的查询
searx.space 上的不同公共实例
自托管你自己的实例以获得可靠结果

在公共实例上被速率限制

切换到自托管实例（参见上方的选项 A）。使用 Docker，你自己的实例没有速率限制。

可选技能：`searxng-search`

对于需要直接通过 curl 使用 SearXNG 的 Agent（例如当网络工具集不可用时的备用），安装 searxng-search 可选技能：

hermes skills install official/research/searxng-search

该技能教 Agent 如何：

通过 curl 或 Python 调用 SearXNG JSON API
按类别过滤（general、news、science 等）
处理分页和错误情况
当 SearXNG 不可达时优雅地降级

后端​

web_extract 如何处理长页面​

哪个模型做摘要？​

当摘要成为障碍时​

设置​

通过 hermes tools 快速设置​

Firecrawl（默认）​

SearXNG（免费，自托管）​

选项 A — 使用 Docker 自托管（推荐）​

选项 B — 使用公共实例​

将 SearXNG 与提取提供商配对​

Tavily​

Exa​

Parallel​

配置​

单一后端​

按能力配置​

自动检测​

验证设置​

故障排查​

web_search 返回 {"success": false}​

web_extract 提示"search-only backend"​

SearXNG 返回 0 个结果​

在公共实例上被速率限制​

可选技能：searxng-search​

后端