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

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

X (Twitter) 搜尋

x_search 工具讓 agent 能直接搜尋 X (Twitter) 的貼文、個人檔案和討論串。它由 xAI 內建的 x_search 工具提供支援，使用 https://api.x.ai/v1/responses 上的 Responses API — Grok 本身在伺服器端執行搜尋，並回傳帶有原始貼文引用的綜合結果。

当你特別想搜尋 X 上的即時討論、回應或主張時，請使用此工具而非 web_search。對於一般網頁，請繼續使用 web_search / web_extract。

提示

如果你已經在為 xAI 模型付費使用 Portal，Live Search 的調用會使用同一個 xAI 金鑰進行計費。參見 Nous Portal。

驗證

x_search 在任一 xAI 憑證路徑可用時都會註冊：

兩者使用相同的端點和載荷 — 唯一的差異在於 bearer token。當兩者都設定時，SuperGrok OAuth 優先，因此 x_search 會使用你的訂閱配額而非付費 API 額度。

工具的 check_fn 每次在模型工具列表重建時都會執行 xAI 憑證解析器。回傳 True 表示 bearer 可取得且非空，且（如果已過期）成功重新整理。已撤銷且重新整理失敗的 token 會隱藏工具 schema — 模型根本看不到它。

啟用工具

當 xAI 憑證（OAuth token 或 XAI_API_KEY）存在時自動啟用。如不需要，可透過 hermes tools → Search → x_search 明確停用。

hermes tools
# → 🐦 X (Twitter) Search   （按空白鍵切換開關）

選擇器提供兩種憑證選擇：

1. xAI Grok OAuth (SuperGrok / Premium+) — 若尚未登入，會開啟瀏覽器到 accounts.x.ai
2. xAI API key — 提示輸入 XAI_API_KEY

兩種選擇都能滿足門控要求。你可以選擇已有的憑證；工具在兩種模式下運作方式相同。如果兩者都設定，OAuth 在調用時會優先使用。

設定

# ~/.hermes/config.yaml
x_search:
  # 用於 Responses 調用的 xAI 模型。
  # grok-4.20-reasoning 是建議的預設值；任何具有 x_search
  # 工具存取權限的 Grok 模型都可以。
  model: grok-4.20-reasoning

  # 請求逾時秒數。x_search 對於複雜查詢可能需要 60–120 秒
  # — 預設值已相當寬裕。最小值：30。
  timeout_seconds: 180

  # 5xx / ReadTimeout / ConnectionError 時的自動重試次數。
  # 每次重試會退避（1.5 倍嘗試秒數，上限 5 秒）。
  retries: 2

工具參數

agent 使用以下參數調用 x_search：

工具回傳的 JSON 包含：

• answer — Grok 的綜合文字回應
• citations — Responses API 頂層欄位回傳的引用
• inline_citations — 從訊息內文提取的 url_citation 註解（每個包含 url、title、start_index、end_index）
• degraded — 當任何縮小範圍的篩選器（allowed_x_handles、excluded_x_handles、from_date、to_date）已設定且兩個引用通道都回傳空值時為 true。此時 answer 是從模型自身的知識綜合而來，而非來自 X 索引，因此應視為無來源。其他情況為 false（包括「未設定篩選器」的情況 — 廣泛的無來源答案只是一般答案，不是篩選失敗）
• degraded_reason — 簡短字串說明哪些篩選器處於作用中狀態，或在 degraded 為 false 時為 null
• credential_source — OAuth 解析成功時為 "xai-oauth"，API 金鑰解析成功時為 "xai"
• model、query、provider、tool、success

日期驗證

from_date / to_date 在 HTTP 請求前會在用戶端進行驗證：

• 兩者若提供，都必須能解析為 YYYY-MM-DD。
• 兩者都設定時，from_date 必須在 to_date 之前或相同。
• from_date 不得晚於今天 UTC — 不存在尚未開始的時間窗口中的貼文，因此該調用保證會回傳零引用。
• to_date 可以是未來日期（調用者可能合理地要求「從昨天到明天」以擷取即將發布的貼文）。

驗證失敗會以結構化的 {"error": "..."} 工具結果回傳，永遠不會發送 HTTP 請求到 xAI。

範例

與 agent 對話：

X 上的人對新的 Grok 圖片功能有什麼評論？專注於 @xai 的回應。

agent 會：

1. 使用 query="reactions to new Grok image features"、allowed_x_handles=["xai"] 調用 x_search
2. 取得綜合答案加上引用特定貼文的列表
3. 附上參考資料回覆答案

疑難排解

"No xAI credentials available"

當兩種驗證路徑都失敗時，工具會顯示此訊息。請在 ~/.hermes/.env 中設定 XAI_API_KEY，或執行 hermes auth add xai-oauth 並完成瀏覽器登入。然後重新啟動你的 session，讓 agent 重新讀取工具登錄。

"x_search is not enabled for this model"

設定的 x_search.model 無法存取伺服器端的 x_search 工具。切換到 grok-4.20-reasoning（預設值）或其他支援的 Grok 模型。請參閱 xAI 文件 取得最新清單。

工具未出現在 schema 中

兩個可能原因：

1. 工具集未啟用。 執行 hermes tools 並確認 🐦 X (Twitter) Search 已勾選。
2. 無 xAI 憑證。 check_fn 回傳 False，因此 schema 保持隱藏。執行 hermes auth status 確認 xai-oauth 登入狀態，並檢查 XAI_API_KEY 是否已設定（如果你使用 API 金鑰路徑）。

degraded: true — 無引用的答案

當你使用了 allowed_x_handles、excluded_x_handles 或日期範圍，且回應回傳 degraded: true 時，表示 xAI 的 X 索引沒有回傳匹配的貼文，但 Grok 仍從其訓練資料中產生了綜合答案。此答案無來源 — 不要將其視為真實的 X 搜尋結果。

值得檢查的原因：

• 帳號名稱拼寫錯誤。 移除 @，仔細檢查拼寫，並確認該帳號存在。
• 日期範圍太窄或滑過了今天的貼文；擴大範圍並重試。
• xAI 索引空白期。 某些活躍帳號在 x_search 中偶爾無法顯示，即使它們定期發布貼文。幾分鐘後重試，或在需要特定帳號的時間線時使用 xurl 技能直接讀取 X API。

參見

• xAI Grok OAuth (SuperGrok / Premium+) — OAuth 設定指南
• Web Search & Extract — 一般（非 X）網頁搜尋
• Tools Reference — 完整工具目錄