网络搜索与内容提取

Hermes Agent 集成了两个可通过模型调用的网络工具，由多个服务提供商支持：

web_search — 搜索网络并返回排序结果
web_extract — 获取并提取一个或多个 URL 的可读内容（后端支持时具备内置深度爬取能力）

两者均通过单一后端选择进行配置。服务提供商可通过 hermes tools 选择，或直接在 config.yaml 中设置。递归爬取功能（如 Firecrawl/Tavily）通过 web_extract 暴露，而非作为独立的 web_crawl 工具。

后端服务

服务提供商	环境变量	搜索	提取	爬取	免费套餐
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 订阅，可通过 工具网关 使用管理型 Firecrawl 实现网络搜索与提取功能，无需 API 密钥。运行 hermes tools 即可启用。

`web_extract` 如何处理长页面

后端返回原始页面的 Markdown 内容，可能非常庞大（论坛线程、文档网站、带嵌入评论的新闻文章）。为保持上下文窗口可用性并降低使用成本，web_extract 在将内容传递给代理前，会先通过 web_extract 辅助模型 处理返回内容。行为完全基于内容大小：

页面大小（字符数）	处理方式
低于 5,000	原样返回 —— 不调用 LLM，完整 Markdown 直接传给代理
5,000 – 500,000	通过 `web_extract` 辅助模型单次摘要，输出上限约 5,000 字符
500,000 – 2,000,000	分块处理：拆分为 10 万字符的块，平行摘要每个块，再合成最终摘要（约 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-preview
    timeout: 360       # seconds; raise if you hit summarization timeouts

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

详情参见辅助模型，了解完整参考及按任务覆盖模式。

当摘要反而造成干扰时

如果你明确需要原始未摘要的页面内容（例如，正在抓取结构化页面，而 LLM 摘要可能会丢失重要字段），请使用 browser_navigate + browser_snapshot。浏览器工具返回的是实时的无障碍树，不经过辅助模型重写（但仍受其自身 8,000 字符快照限制，对超大页面适用）。

设置

通过 `hermes tools` 快速设置

运行 hermes tools，进入 网络搜索与提取，选择一个提供商。向导将提示输入所需 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（包括其爬取模式）需要额外的提取服务提供商。

方案 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 → 网络搜索与提取 → SearXNG 设置。

方案 B —— 使用公共实例

公共 SearXNG 实例列表见 searx.space。请筛选出启用了 JSON 格式 的实例（表格中显示）。

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

公共实例

公共实例存在速率限制、不稳定运行时间，且可能随时禁用 JSON 格式。生产环境强烈建议自托管。

将 SearXNG 与提取服务搭配使用

SearXNG 负责搜索；你需要另一个服务提供商来处理 web_extract（包括任何深度爬取模式）。使用按功能配置的密钥：

# ~/.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 its deep-crawl modes)

当按功能密钥为空时，两者均回退至 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 格式被禁用 —— 请在 formats 的 settings.yml 列表中添加 json，然后重启服务
如果出现连接错误，可能是容器未运行：docker ps | grep searxng

`web_extract` 显示“仅搜索后端”

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

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

SearXNG 返回 0 条结果

某些公共实例会禁用特定搜索引擎或类别。尝试：

使用不同的查询
从 searx.space 换一个不同的公共实例
自行托管实例以获得更可靠的搜索结果

在公共实例上遭遇限流

切换至自托管实例（参见上方的选项 A）。使用 Docker 部署时，自建实例无速率限制。

`web_extract` 返回截断内容并附带“摘要超时”提示

辅助模型在配置的超时时间内未能完成摘要。可采取以下措施之一：

提高 auxiliary.web_extract.timeout 在 config.yaml 中的值（新安装默认为 360 秒，若密钥缺失则为 30 秒）
将 web_extract 辅助任务切换为更快的模型（例如 google/gemini-3-flash-preview）—— 参见如何处理长页面的 web_extract
对于摘要并非合适工具的页面，改用 browser_navigate

可选技能：`searxng-search`

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

hermes skills install official/research/searxng-search

该技能将教会代理：

通过 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 显示“仅搜索后端”​

SearXNG 返回 0 条结果​

在公共实例上遭遇限流​

web_extract 返回截断内容并附带“摘要超时”提示​

可选技能：searxng-search​