<!-- Source: https://hermesbible.com/docs/user-guide/features/web-search -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/web-search

網路搜尋與內容萃取

Hermes Agent 包含兩個可供模型呼叫的網路工具，背後支援多個供應商：

• web_search — 搜尋網路並回傳排序結果
• web_extract — 從一個或多個網址抓取並萃取可讀內容

兩者透過單一後端選項進行設定。供應商可透過 hermes tools 選擇，或直接在 config.yaml 中設定。

後端

Brave Search、DDGS 和 xAI 僅支援搜尋功能 — 當你同時需要 web_extract 時，可將其任一與 Firecrawl/Tavily/Exa/Parallel 搭配使用。DDGS 底層使用 ddgs Python 套件；如果尚未安裝，請執行 pip install ddgs（或讓 Hermes 在首次使用時自動安裝）。xAI 透過 Responses API 執行 Grok 的伺服器端 web_search 工具 — 結果由 LLM 生成而非基於索引，因此標題、描述和網址選擇皆為模型輸出（詳見下方信任模型注意事項）。

按功能拆分： 你可以針對搜尋與萃取獨立使用不同供應商 — 例如使用 SearXNG（免費）進行搜尋，使用 Firecrawl 進行萃取。詳見下方按功能配置。

提示 — Nous 訂閱者

如果你持有付費的 Nous Portal 訂閱，網路搜尋與萃取可透過 Tool Gateway 使用託管的 Firecrawl — 無需 API 金鑰。新安裝可執行 hermes setup --portal 登入並一次啟用所有 Gateway 工具；現有安裝可透過 hermes tools 僅切換網路功能。

---

web_extract 如何處理長頁面

後端回傳原始頁面 Markdown，其內容可能非常龐大（論壇討論串、文件網站、帶有嵌入留言的新聞文章）。為了保持你的上下文視窗可用並控制成本，web_extract 會在將內容交給 Agent 之前，透過 web_extract 輔助模型處理回傳的內容。行為純粹基於內容大小：

摘要會保留引文、程式碼區塊和關鍵事實的原始格式 — 它是內容壓縮器，而非改寫器。如果摘要失敗或逾時，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，然後選擇供應商。設定精靈會提示輸入所需的網址或 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

注意 — 公開實例

公開實例有速率限制、運行時間不穩定，且可能隨時停用 JSON 格式。若用於正式環境，強烈建議自架。

---

將 SearXNG 與萃取供應商搭配使用

SearXNG 處理搜尋；你需要單獨的供應商來處理 web_extract。使用按功能拆分的金鑰設定：

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

有了這個設定，Hermes 會使用 SearXNG 處理所有搜尋查詢，使用 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}

透過 Responses API 上 Grok 的伺服器端 web_search 工具路由 web_search。Grok 執行實際搜尋，並以結構化 JSON 回傳前幾名結果。

支援任一種憑證路徑 — 無需新增環境變數或設定精靈：

# ~/.hermes/.env（環境變數路徑）
XAI_API_KEY=sk-xai-your-key-here

或針對 SuperGrok 訂閱者：

hermes auth login xai-oauth

然後將 xAI 選為搜尋後端：

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

選用參數：

web:
  backend: "xai"
  xai:
    model: grok-build-0.1        # 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）；使用環境變數憑證時會跳過重試。

注意 — 信任模型

與基於索引的供應商（Brave、Tavily、Exa）回傳逐字搜尋引擎結果不同，xAI 是 LLM 選擇要顯示哪些網址並自行撰寫標題與描述。查詢的內容會影響輸出，因此惡意構造的查詢（例如 Agent 從不受信任的上游輸入中擷取到的注入內容）理論上可以引導 Grok 產生攻擊者選擇的網址。請以對待任何模型生成連結的方式對待回傳的網址 — 在抓取前進行驗證，尤其是當查詢來自不受信任的輸入時。

---

設定

單一後端

為所有網路功能設定一個供應商：

# ~/.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 金鑰/網址自動偵測後端。

優先順序（按功能）：

1. web.search_backend / web.extract_backend（明確的按功能設定）
2. web.backend（共用回退）
3. 從環境變數自動偵測

自動偵測

若未明確設定後端，Hermes 會根據已設定的憑證自動選擇第一個可用的後端：

xAI Web Search 不在自動偵測鏈中 — 設定 XAI_API_KEY（或透過 xAI Grok OAuth 登入）不會自動將網路流量導向 xAI，因為這些憑證也用於推論 / TTS / 圖像生成，使用者可能希望網路功能使用不同的後端。請以 web.backend: "xai" 明確選用。

---

驗證你的設定

執行 hermes setup 以查看偵測到的網路後端：

✅ Web Search & Extract (searxng)

或透過 CLI 檢查：

# 啟用 venv 並直接執行網路工具模組
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 無法萃取網址內容。請將 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（全新安裝預設為 360 秒，缺少金鑰時為 30 秒）
• 將 web_extract 輔助任務切換至更快的模型（例如 google/gemini-3-flash-preview）— 見「web_extract 如何處理長頁面」
• 對於摘要不適用的頁面，改用 browser_navigate

---

選用技能：searxng-search

對於需要透過 curl 直接使用 SearXNG 的 Agent（例如作為網路工具組不可用時的備用方案），安裝 searxng-search 選用技能：

hermes skills install official/research/searxng-search

這會新增一個技能，教導 Agent 如何：

• 透過 curl 或 Python 呼叫 SearXNG JSON API
• 按類別篩選（general、news、science 等）
• 處理分頁與錯誤情況
• 當 SearXNG 無法連線時優雅回退

---

---

X（Twitter）搜尋