X（Twitter）の検索

x_search という道具を使うと、エージェントが X（Twitter）の投稿・プロフィール・スレッドを直に検索できます。中身は https://api.x.ai/v1/responses にある Responses API の、xAI に組み込まれた x_search です。実際に検索するのは Grok 自身で、元の投稿への出典を添えた、まとめの答えが返ってきます。

X 上でのいまの話題、反応、主張が知りたいときは、web_search ではなくこちらを使ってください。ウェブ一般のページには、これまでどおり web_search／web_extract を使います。

x_search と xurl の違い

Hermes は、X に対して2つの窓口を用意できます。

両方を混ぜて進めるときは、まず x_search で候補になる公開の投稿を見つけ、対象の投稿・利用者・操作がはっきりしてから xurl read などの厳密な xurl のコマンドに切り替えてください。X の状態を変える操作は、必ず xurl の出力か X の API の応答で確かめます。x_search の答えは、書き込みが行われた証拠には決してなりません。

認証

x_search は、xAI の資格情報がどちらかあれば登録されます。

どちらも同じ窓口に同じ中身を送ります。違うのは認証に使うトークンだけです。両方を設定している場合は、明示的な XAI_API_KEY が勝ちます — 契約に紐づく OAuth のトークンでも /v1/responses は使えますが、x_search には出典のない、Grok が説明するだけの弱い形で答えが返ってきます。API の鍵なら実際の投稿が返ります。つまり鍵を設定していると、x_search は従量課金の API を使うことになります。契約の枠内で使いたければ XAI_API_KEY を外してください（そのぶん、答えが弱くなる点は先ほどのとおりです）。

この道具の check_fn は、モデルに渡す道具の一覧が組み直されるたびに、xAI の資格情報の解決を走らせます。True が返るのは、トークンが取得できて、中身が空でなく、期限切れだった場合は更新にも成功したときです。取り消されたトークンで更新にも失敗すると、この道具は一覧から隠れます。モデルからは、そもそも見えなくなります。

道具を有効にする

xAI の資格情報（OAuth のトークンか XAI_API_KEY）があれば自動で有効になります。使いたくない場合は hermes tools → Search → x_search で明示的に切ってください。

hermes tools
# → 🐦 X (Twitter) Search   (press space to toggle on)

選択画面では、資格情報の選び方が2つ出ます。

1. xAI Grok OAuth (SuperGrok / Premium+) — まだログインしていなければ、ブラウザで accounts.x.ai が開きます
2. xAI API key — XAI_API_KEY の入力を求められます

どちらでも条件は満たせます。すでに持っているほうを選んでかまいません。この道具の働きはどちらでも同じです。両方を設定した場合、呼び出しのときは OAuth が優先されます。

設定

# ~/.hermes/config.yaml
x_search:
  # xAI model used for the Responses call.
  # grok-4.5 is the recommended default; any Grok model
  # with x_search tool access works.
  model: grok-4.5

  # Optional reasoning effort: low, medium, high, or xhigh. When omitted,
  # the selected model's default applies. xhigh is supported only by
  # models that document it, such as grok-4.20-multi-agent.
  # reasoning_effort: low

  # Request timeout in seconds. x_search can take 60–120s for
  # complex queries — the default is generous. Minimum: 30.
  timeout_seconds: 180

  # Number of automatic retries on 5xx / ReadTimeout / ConnectionError.
  # Each retry backs off (1.5x attempt seconds, capped at 5s).
  retries: 2

reasoning_effort は、xAI の Responses API へ reasoning: {effort: ...} として送られます。推論の度合いを設定できないモデルでは、指定しないままにしてください。値が正しくない場合は、API に要求を出す前に失敗します。

道具に渡せる項目

エージェントは、次の引数を付けて 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）を設定したうえで、2つの出典の経路がどちらも空で返ってきたときに 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 での今日より後にできません。まだ始まっていない期間に投稿が存在するはずはなく、出典が必ず0件になる呼び出しだからです。
• to_date が未来なのは認められます（届いた順に投稿を拾うため、「昨日から明日まで」と指定したい場面はあります）。

検査に通らなかったときは、xAI への HTTP の呼び出しではなく、{"error": "..."} という形の結果として返ります。

使い方の例

エージェントへの語りかけです。

> What are people on X saying about the new Grok image features? Focus on responses from @xai.

エージェントは、次のように動きます。

1. query="reactions to new Grok image features"、allowed_x_handles=["xai"] を付けて x_search を呼びます
2. まとめの答えと、個々の投稿へつながる出典の一覧を受け取ります
3. 答えと参照先を返します

次に「いちばんいいものに返信して」「その投稿にいいねして」と頼まれた場合、エージェントは xurl のスキルに切り替え、対象の投稿を正確に確かめたうえで X の API の操作を使うべきです。x_search は、あくまで見つけるための道具です。

困ったときは

「No xAI credentials available」と出る

認証の2つの経路がどちらも通らないときに出ます。~/.hermes/.env に XAI_API_KEY を設定するか、hermes auth add xai-oauth を実行してブラウザでのログインを済ませてください。そのあと、エージェントが道具の一覧を読み直せるよう、セッションを開き直します。

「x_search is not enabled for this model」と出る

設定した x_search.model に、サーバー側の x_search を使う権限がありません。grok-4.5（既定）か、対応している別の Grok のモデルに変えてください。いま対応しているモデルは xAI の文書で確認できます。

道具が一覧に出てこない

考えられる原因は2つです。

1. 道具の組が有効になっていない。 hermes tools を実行し、🐦 X (Twitter) Search に印が付いているか確かめてください。
2. xAI の資格情報がない。 check_fn が False を返すため、一覧に出ないままになります。hermes auth status で xai-oauth のログイン状態を確かめ、（API の鍵を使うなら）XAI_API_KEY が設定されているかを見てください。

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 の準備の手引き
• xurl のスキル — ログインを伴うアカウントの操作のための、公式の X の API のコマンド
• Web 検索と本文の取り出し — X 以外の、ウェブ一般の検索
• ツール一覧 — 道具の全一覧