网络搜索与提取

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	✔	—	—	✔ 免费（自行托管）
Brave Search（免费版）	BRAVE_SEARCH_API_KEY	✔	—	—	2,000 次查询/月
DDGS (DuckDuckGo)	—（无需密钥）	✔	—	—	✔ 免费
Tavily	TAVILY_API_KEY	✔	✔	✔	1,000 次搜索/月
Exa	EXA_API_KEY	✔	✔	—	1,000 次搜索/月
Parallel	PARALLEL_API_KEY	✔	✔	—	付费
xAI (Grok)	XAI_API_KEY 或 hermes auth login xai-oauth	✔	—	—	付费（SuperGrok 或按 token）

Brave Search、DDGS 和 xAI 是仅搜索——当您还需要 web_extract 时，将它们与 Firecrawl/Tavily/Exa/Parallel 配对。DDGS 底层使用 ddgs Python 包；如果尚未安装，运行 pip install ddgs（或让 Hermes 在首次使用时惰性安装）。xAI 在 Responses API 上运行 Grok 的服务器端 web_search 工具——结果是 LLM 生成的，而非基于索引，因此标题、描述和 URL 选择都是模型输出（请参阅下面的信任模型注意事项）。

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

:::tip 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	分块处理：分割为 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-preview
    timeout: 360       # 秒；如果遇到摘要超时可提高

或者交互式选择：hermes model → Configure auxiliary models → 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（包括其爬取模式）需要单独的提取提供商。

选项 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 输出。复制生成的配置并启用它：

# 从容器的自动生成配置中复制出来
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml

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

# 之前（默认——JSON 禁用）：
formats:
  - html
 
# 之后（为 Hermes 启用 JSON）：
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

:::caution 公共实例 公共实例有速率限制、可变正常运行时间，并可能随时禁用 JSON 格式。对于生产环境，强烈推荐自行托管。 :::

---

将 SearXNG 与提取提供商配对

SearXNG 处理搜索；您需要单独的提供商用于 web_extract（包括任何深度爬取模式）。使用按能力键：

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

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

---

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 获取访问权限。

---

xAI（Grok）{#xai-grok}

通过 Grok 在 Responses API 上的服务器端 web_search 工具路由 web_search。Grok 运行实际搜索并以结构化 JSON 形式返回顶级结果。

适用于任一凭证路径——无需新的环境变量，无需新的设置向导：

# ~/.hermes/.env（环境变量路径）
XAI_API_KEY=sk-xai...here

或对于 SuperGrok 订阅者：

hermes auth login xai-oauth

然后选择 xAI 作为搜索后端：

# ~/.hermes/config.yaml
web:
  backend: "xai"

可选参数：

web:
  backend: "xai"
  xai:
    model: grok-4.3              # web_search 所需的推理模型（默认）
    allowed_domains:             # 可选，最多 5 个——与 excluded_domains 互斥
      - arxiv.org
    excluded_domains:            # 可选，最多 5 个
      - example-spam.com
    timeout: 90                  # 秒（默认）

仅搜索——如果还需要 web_extract，请与 Firecrawl / Tavily / Exa / Parallel 配对。在 401 时，提供商执行一次强制 OAuth token 刷新并重试（覆盖窗口期内撤销和主动过期检查无法解码的不透明 token）；环境变量凭证跳过重试。

:::caution 信任模型 与返回逐字搜索引擎结果的基于索引的提供商（Brave、Tavily、Exa）不同，xAI 是一个 LLM，它选择要展示的 URL 并自行编写标题和描述。查询的内容会影响输出，因此恶意构造的查询（例如通过代理拾取的不可信上游输入注入）原则上可以操纵 Grok 发出攻击者选择的 URL。将返回的 URL 与对待任何模型生成的链接一样对待——在获取之前进行验证，特别是如果查询来自不可信输入。 :::

---

配置

单个后端

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

# ~/.hermes/config.yaml
web:
  backend: "searxng"   # firecrawl | searxng | brave-free | ddgs | tavily | exa | parallel | xai

按能力配置

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

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"     # 由 web_search 使用
  extract_backend: "firecrawl"  # 由 web_extract 使用（及其深度爬取模式）

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

优先级顺序（按能力）：

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

自动检测

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

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

xAI Web Search 不在自动检测链中——设置了 XAI_API_KEY（或通过 xAI Grok OAuth 登录）不会自动将网络流量路由到 xAI，因为这些凭证也可用于推理 / TTS / 图片生成，用户可能想要不同的网络后端。使用 web.backend: "xai" 明确选择加入。

---

验证您的设置

运行 hermes setup 以查看检测到的 Web 后端：

✅ Web Search & Extract (searxng)

或通过 CLI 检查：

# 激活虚拟环境并直接运行 web 工具模块
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 显示 “仅搜索后端”

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

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

SearXNG 返回 0 结果

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

• 不同的查询
• 来自 searx.space 的不同公共实例
• 自行托管您自己的实例以获得可靠结果

公共实例上的速率限制

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

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

辅助模型未在配置的超时内完成摘要。要么：

• 在 config.yaml 中提高 auxiliary.web_extract.timeout（新安装默认为 360s，如果键缺失则为 30s）
• 将 web_extract 辅助任务切换到更快的模型（例如 google/gemini-3-flash-preview）——请参阅web_extract 如何处理长页面
• 对于摘要不合适的页面，改用 browser_navigate

---

可选技能：searxng-search

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

hermes skills install official/research/searxng-search

这会添加一个技能，教代理如何：

• 通过 curl 或 Python 调用 SearXNG JSON API
• 按类别过滤（general、news、science 等）
• 处理分页和错误情况
• 在 SearXNG 不可访问时优雅回退