search-x

X の検索

xAI の Responses API と x_search ツールを利用した、X/Twitter のリアルタイム検索です。引用、エンゲージメントの状況、画像、直接リンクを含む実際のツイートを返します。スクレイピング、Cookie、ブラウザー自動化は不要です。xAI API を使用します。

セットアップ

xAI API キーを設定します。

openclaw config set skills.entries.search-x.apiKey "xai-YOUR-KEY"

または、環境変数を使用します。

export XAI_API_KEY="xai-YOUR-KEY"

API キーは https://console.x.ai で取得できます。

---

x_search を使った Responses API（推奨）

このスキルで X を検索する主な方法は、x_search ツールを使った Responses API（POST /v1/responses）です。xAI がすべての検索オーケストレーションをサーバー側で処理するため、この方法を推奨します。

仕組み

POST https://api.x.ai/v1/responses
Authorization: Bearer $XAI_API_KEY
Content-Type: application/json

{
  "model": "grok-4-1-fast-non-reasoning",
  "tools": [{"type": "x_search"}],
  "input": "Find recent tweets about Claude Code tips"
}

手動で chat/completions と検索を組み合わせる方法と比べた主な利点：

• サーバー側のオーケストレーション - Grok が X を検索するタイミングと方法を判断するため、クライアント側でツールループを組む必要はありません
• 自動引用 - すべての検索結果に、実際のツイートを指すソース URL が含まれます
• ツールの組み合わせ - 同じリクエストで x_search、web_search、code_interpreter を渡すことができ、Grok は適切なツールを選んで使用します
• 構造化された結果 - 引用はインラインテキストではなく、URL を含む構造化オブジェクトとして返されます

1 回のリクエストでツールを組み合わせる

{
  "model": "grok-4-1-fast-non-reasoning",
  "tools": [
    {"type": "x_search"},
    {"type": "web_search"}
  ],
  "input": "What are people saying about the new React compiler on X, and what does the official documentation say?"
}

Grok は X でソーシャルな議論を検索し、ウェブで公式ドキュメントを検索して、それぞれのソースからの引用を含む単一の応答にまとめます。

---

モデル

モデル	コンテキスト	料金（入力／出力、100 万トークンあたり）	最適な用途
grok-4.20-multi-agent-beta-0309	2M	$2 / $6	複雑な複数ステップの調査
grok-4.20-beta-0309-reasoning	2M	$2 / $6	推論を伴う詳細な分析
grok-4-1-fast-reasoning	2M	$0.20 / $0.50	推論を伴う高速検索
grok-4-1-fast-non-reasoning	2M	$0.20 / $0.50	簡易検索（最安）

Grok 4.20 Multi-Agent Beta

grok-4.20-multi-agent-beta-0309 モデルは、複雑な調査クエリに対してマルチエージェント連携を使用します。複数の Grok エージェントが協力してクエリを分解し、さまざまな観点から検索して、調査結果をまとめます。次のような場合に使用してください。

• 複数のトピックやアカウントを相互に照合する必要がある
• 手早い検索ではなく、包括的な調査が必要である
• 多くのデータポイントにわたる分析、比較、トレンドの統合をユーザーが求めている
• 網羅性を優先し、時間やコストはそれほど重要ではない

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "comprehensive analysis of AI safety discourse evolution"

モデル選択のガイド

• デフォルト（簡易検索）： grok-4-1-fast-non-reasoning - 最安かつ最速で、簡単なツイート検索に適しています
• 推論が必要： grok-4-1-fast-reasoning - 同じ料金で、より優れた分析のために思考の連鎖を追加します
• 画像検索： grok-4.20-beta-0309-reasoning - ツイートとあわせて画像の検索結果を返します
• 詳細な調査： grok-4.20-multi-agent-beta-0309 - 複雑なクエリに対応するマルチエージェントモデルです

---

x_search による検索モード

x_search ツールは、4 種類の検索モードに対応しています。Grok はクエリに基づいて適切なモードを自動的に選択しますが、プロンプトで指定することもできます。

キーワード検索

完全一致する語句を検索します。特定のフレーズ、ハッシュタグ、用語を含むツイートの検索に最適です。

node {baseDir}/scripts/search.js "Claude Code monorepo tips"

Grok は指定された用語を含むツイートを検索します。フレーズを完全一致で検索するには、クエリ内で引用符を使用します。

セマンティック検索

意味に基づく検索です。特定の語句が使われていなくても、概念に関するツイートを探すのに最適です。

node {baseDir}/scripts/search.js "people frustrated with slow CI/CD pipelines"

Grok は意図を理解し、異なる用語が使われていても関連するツイートを見つけます（例：「ビルド時間が長すぎて困る」、「GitHub Actions がいつまでも終わらない」）。

ユーザー検索

アカウントとそのアクティビティを検索します。プロフィールの検索やアカウントの発見に最適です。

node {baseDir}/scripts/search.js --handles karpathy --days 30 "posts from @karpathy about transformers"

アカウント情報、最近の投稿、エンゲージメントの傾向を返します。トピックフィルターと組み合わせると、特定のテーマについてそのユーザーが何を発信しているかを確認できます。

スレッド取得

会話スレッド全体を取得します。返信の連鎖や議論をすべて読むのに最適です。

node {baseDir}/scripts/search.js --handles sama --days 7 "thread about AI regulation"

Grok は返信、引用ツイート、会話の全体的な文脈を含むスレッド全体を再構成します。

---

コマンド

基本検索

node {baseDir}/scripts/search.js "AI video editing"

クエリを使って X を検索し、ユーザー名、内容、日付、直接リンクを含むツイートを返します。

時間による絞り込み

node {baseDir}/scripts/search.js --days 7 "breaking news"
node {baseDir}/scripts/search.js --days 1 "trending today"
node {baseDir}/scripts/search.js --days 90 "product launch retrospective"

--days フラグで、どこまでさかのぼって検索するかを設定します。デフォルトは 30 日です。「今日何があったか」を検索する場合は --days 1、週ごとのまとめには --days 7、より長期の調査には --days 90 を使用します。

アカウントによる絞り込み

node {baseDir}/scripts/search.js --handles @elonmusk,@OpenAI "AI announcements"
node {baseDir}/scripts/search.js --exclude @bots "real discussions"

--handles を使うと、特定のアカウントに結果を絞り込めます。ノイズを除外するには --exclude を使用します。どちらも、@ の有無にかかわらず、カンマ区切りのリストを受け付けます。

出力オプション

node {baseDir}/scripts/search.js --json "topic"        # Full JSON response with all metadata
node {baseDir}/scripts/search.js --compact "topic"     # Just tweets, no commentary or citations list
node {baseDir}/scripts/search.js --links-only "topic"  # Just X links, one per line

モデルの選択

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "complex research query"
node {baseDir}/scripts/search.js --model grok-4-1-fast-non-reasoning "quick text search"
node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning "topic with images"

---

モード

このスキルは、ユーザーの依頼に応じた 6 つの異なるモードに対応しています。エージェントは、クエリに基づいて適切なモードを選択します。

モード 1：基本的なツイート検索

使用する場面： ユーザーが「X を検索して」「〜についてのツイートを探して」「〜についてみんなは何と言っているか」と依頼した場合。

実行方法：

node {baseDir}/scripts/search.js "query here"

クエリの例：

• 「X で Claude Code のヒントを検索して」
• 「新しい iPhone についてのツイートを探して」
• 「X で Rust についてみんなは何と言っていますか？」

モード 2：スレッドリーダー

使用する場面： ユーザーが「このスレッドを読んで」「このスレッドを展開して」と依頼した場合、または X/Twitter の URL を提示して会話全体を求めた場合。

実行方法：

node {baseDir}/scripts/search.js "thread by @username about [topic] site:x.com"

スレッドを読む場合は、投稿者のアカウントとスレッドのトピックを含むクエリを作成します。Grok の x_search がスレッドを見つけ、返信チェーン全体を返します。ユーザーがツイートの直接 URL を提示した場合は、URL からユーザー名とトピックを抽出して検索します。

クエリの例：

• 「このスレッドを読んでください：https://x.com/karpathy/status/1234567890」
  • 抽出内容：--handles karpathy --days 7 を指定して「@karpathy によるスレッド」を検索
• 「@levelsio のスタートアップについてのスレッドを展開して」
  • 検索：--handles levelsio "スタートアップのスレッド"

スレッドを読む際のヒント：

• --handles を使ってスレッドの投稿者に絞り込みます
• --days 3 または --days 7 を使って期間を絞り込みます
• クエリで「スレッド内の返信をすべて含めて」と Grok に依頼します
• スレッドが非常に長い場合、Grok が要約することがあります。より情報量の多い出力にするには、--compact を付けて再実行します

モード 3：トレンド分析

使用する場面： ユーザーが「トレンドは何ですか」「X で話題になっているのは何ですか」「[トピック] について大きな議論は何ですか」と尋ねた場合。

実行方法：

node {baseDir}/scripts/search.js --days 1 "trending [topic] most discussed"

トレンド分析では、短い期間（1～3 日）を指定し、「トレンド」「バズっている」「最も議論されている」「大きな議論」などの語句を含めます。Grok がエンゲージメントの高い投稿と共通のテーマを特定します。

クエリの例：

• 「今日、AI について X でトレンドになっているのは何ですか？」
  • 検索：--days 1 "AI のトレンド 最も議論されている バズ"
• 「今週、テック業界のレイオフについて Twitter で大きな議論になっているのは何ですか？」
  • 検索：--days 7 "テック業界のレイオフ 最大の議論 最も議論されている"
• 「選挙についてバズっているのは何ですか？」
  • 検索：--days 1 "選挙 バズ トレンド"

トレンドの出力ガイダンス： トレンドの結果を提示する際は、テーマごとに整理します。関連するツイートをまとめ、どのトピックが最も高いエンゲージメントを得ているかを記載します。出力形式の例：

## Trending: [Topic] (last 24 hours)

### Theme 1: [Description]
- @user1: "tweet content" (high engagement)
  https://x.com/user1/status/123
- @user2: "related tweet"
  https://x.com/user2/status/456

### Theme 2: [Description]
- @user3: "tweet content"
  https://x.com/user3/status/789

モード 4：プロフィール／アカウント分析

使用する場面： ユーザーが「X の @handle は誰ですか」「@handle はどんな投稿をしていますか」「@handle の最近の投稿を見せて」と尋ねた場合。

実行方法：

node {baseDir}/scripts/search.js --handles username --days 30 "posts from @username"

プロフィール分析では、--handles を使ってアカウントに絞り込み、最近の活動を検索します。これをトピックフィルターと組み合わせると、特定の話題についてその人が何を発信しているかを確認できます。

クエリの例：

• 「@elonmusk は最近どんな投稿をしていますか？」
  • 検索：--handles elonmusk --days 7 "最近の @elonmusk の投稿"
• 「@karpathy の最近の AI に関する見解を見せて」
  • 検索：--handles karpathy --days 30 "AI 機械学習 ディープラーニング"
• 「X の @levelsio は誰ですか？」
  • 検索：--handles levelsio --days 30 "@levelsio による投稿"

プロフィールの出力ガイダンス： プロフィールの結果を提示する際は、その人物が主にどのような投稿をしているかを要約してから、最近の注目投稿を示します。

## @username - Profile Summary

**Main topics:** AI, startups, indie hacking
**Posting frequency:** ~5-10 tweets/day
**Notable recent posts:**

1. @username (Mar 14): "tweet content"
   https://x.com/username/status/123

2. @username (Mar 12): "tweet content"
   https://x.com/username/status/456

モード 5：画像検索

使用するタイミング： X 上の画像、スクリーンショット、写真、ミーム、またはビジュアルコンテンツをユーザーが求めている場合です。これは大きな差別化要因です。Grok-4.20 は画像検索結果を返すことができます。

実行方法：

node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning "images of [topic]"

重要： 画像検索には必ず grok-4.20 モデルを使用してください。grok-4-1-fast モデルは画像検索結果を返しません。

Responses API と x_search を grok-imagine-image と組み合わせて、検索コンテキストに基づく画像生成を行うこともできます。たとえば、X で話題のミーム形式を検索してから、そのスタイルで新しい画像を生成できます。

クエリの例：

• 「X で火星着陸について共有されている画像を見せて」
  • 検索：--model grok-4.20-beta-0309-reasoning --days 3 "Mars landing images photos"
• 「X でプログラミングに関するミームを探して」
  • 検索：--model grok-4.20-beta-0309-reasoning --days 7 "programming memes funny"
• 「Claude Code について、どんなスクリーンショットが共有されていますか？」
  • 検索：--model grok-4.20-beta-0309-reasoning --days 7 "Claude Code screenshots"

モード 6：マルチエージェント調査

使用するタイミング： 複数の検索観点が必要となる、包括的な分析、トピック横断の比較、または詳細な調査をユーザーが求めている場合です。

実行方法：

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "comprehensive query"

マルチエージェントモデルは、複雑なクエリをサブタスクに分解し、複数の観点から検索して、調査結果を統合します。次のような用途に最適です。

• 「@OpenAI と @AnthropicAI のコミュニティがモデルの安全性について何を話しているか比較して」
• 「今月の React 対 Svelte の議論を包括的にまとめて」
• 「X 上の [event] をめぐる騒動について、全経緯を調査して」

---

プロンプトキャッシュ

xAI はプロンプトキャッシュに対応しており、キャッシュされたトークンの入力コストを 90％削減できます。次のような場合に便利です。

• 類似したシステムプロンプトやコンテキストで検索を繰り返す場合
• 同じベースクエリで、時間の経過に伴うトピックの動向を監視する場合
• 一定間隔で X をポーリングするダッシュボードを構築する場合

キャッシュされたトークンは API によって自動的に検出されます。リクエストの構造を工夫し、呼び出し間でシステムプロンプトとツール定義が一貫するようにしてください。変更するのはユーザークエリだけにします。最初のリクエストには通常料金がかかりますが、同じプレフィックスを持つ以降のリクエストには 90％の割引が適用されます。

---

Batch API

xAI Batch API（2026 年 1 月より GA）は、一括検索処理に対応しています。次のような用途に利用できます。

• 監視ワークフロー - 1 回のバッチで 50 件の異なるトピックやアカウントを検索する
• 調査パイプライン - 多数のクエリを夜間に低コストで実行する
• 競合分析 - 複数の競合他社の X 上での活動を並行して追跡する

バッチ検索の使用方法

POST https://api.x.ai/v1/batch
Authorization: Bearer $XAI_API_KEY

{
  "requests": [
    {
      "custom_id": "search-1",
      "method": "POST",
      "url": "/v1/responses",
      "body": {
        "model": "grok-4-1-fast-non-reasoning",
        "tools": [{"type": "x_search"}],
        "input": "Query 1"
      }
    },
    {
      "custom_id": "search-2",
      "method": "POST",
      "url": "/v1/responses",
      "body": {
        "model": "grok-4-1-fast-non-reasoning",
        "tools": [{"type": "x_search"}],
        "input": "Query 2"
      }
    }
  ]
}

バッチリクエストは非同期で処理されます。バッチステータスエンドポイントをポーリングして、完了を確認してください。結果はリクエストと同じ順序で返されます。

---

出力形式

検索結果をユーザーに提示する際は、エンゲージメント情報を含むツイートカード形式にしてください。

標準的なツイートカード形式

@username (Display Name) - Mar 14, 2026
"The full tweet content goes here, preserving the original text
exactly as posted."

Link: https://x.com/username/status/1234567890123456789

コンパクト形式（大量の検索結果向け）

- @username: "Tweet content truncated if needed..." (Mar 14)
  https://x.com/username/status/123

リンクのみの形式

ユーザーが URL だけを求めている場合（たとえば、ブラウザーで開く場合や別のツールに渡す場合）：

https://x.com/user1/status/123
https://x.com/user2/status/456
https://x.com/user3/status/789

形式に関する主なルール

1. すべてのツイートに X への直接リンクを必ず含める
2. ツイートの原文を維持し、言い換えない
3. すべてのツイートに投稿者の @handle を含める
4. Grok がエンゲージメント情報（いいね、リツイート、返信）を返した場合は、それらを含める
5. ユーザーがタイムラインを求めている場合を除き、時系列ではなく関連度順に検索結果をまとめる
6. 検索結果がない場合は、その旨を明確に伝え、別のクエリを提案する
7. ユーザーがより多くを求めている場合を除き、出力は 10～15 件のツイートまでにする

---

エラーからの復旧

API キーがない場合

XAI_API_KEY が設定されておらず、設定ファイルにもキーが見つからない場合：

Error: No xAI API key found.
Set XAI_API_KEY in your environment or run:
  openclaw config set skills.entries.search-x.apiKey "xai-YOUR-KEY"
Get your key at: https://console.x.ai

レート制限（HTTP 429）

xAI API にはレート制限があります。429 エラーが発生した場合：

1. 10～15 秒待ってから、一度だけ再試行します
2. それでもレート制限がかかる場合は、ユーザーに「xAI API のレート制限に達しました。1 分後にもう一度お試しください。」と伝えます
3. 再試行は 1 回までにしてください。ユーザーは手動で再実行できます

認証エラー（HTTP 401／403）

1. API キーが無効または期限切れの可能性があることをユーザーに伝えます
2. キーを確認するため、https://console.x.ai を案内します
3. 次のコマンドを提案します：export XAI_API_KEY="xai-NEW-KEY"

検索結果が空の場合

Grok がツイートを返さない場合：

1. 期間を広げてみます：--days 7 の代わりに --days 90 を指定します
2. ハンドルのフィルターを削除してみます
3. よりシンプルな検索語を試します
4. ユーザーに次のように伝えます：「この検索条件に一致するツイートは見つかりませんでした。より広い検索語または長い期間で試してください。」

タイムアウト／ネットワークエラー

1. Grok の複雑な検索には 5～15 秒かかることがあります。これは正常です
2. マルチエージェント検索には 15～30 秒かかることがあります。想定内です
3. リクエストがタイムアウトした場合は、よりシンプルな検索条件でもう一度試します
4. ネットワークが停止している場合は、そのことをユーザーにはっきりと伝えます

---

環境変数

変数	必須	デフォルト	説明
XAI_API_KEY	はい	-	console.x.ai で取得した xAI API キー
SEARCH_X_MODEL	いいえ	grok-4-1-fast-non-reasoning	検索に使用するデフォルトのモデル
SEARCH_X_DAYS	いいえ	30	デフォルトの期間（日数）

---

チャットでの使用例

シンプルな検索

ユーザー：「X で Claude Code について人々が何と言っているか検索して」 アクション： node {baseDir}/scripts/search.js "Claude Code" を実行します 提示する内容： リンク付きのツイートカード

期間を指定した検索

ユーザー：「Rust と Go の比較について、先週のツイートを見つけて」 アクション： node {baseDir}/scripts/search.js --days 7 "Rust vs Go" を実行します

アカウントを指定した検索

ユーザー：「最近、@karpathy はどんな投稿をしている？」 アクション： node {baseDir}/scripts/search.js --handles karpathy --days 14 "posts from @karpathy" を実行します

スレッドの読み取り

ユーザー：「このスレッドを読んで：https://x.com/sama/status/1234567890」 アクション： ハンドル（sama）を抽出し、node {baseDir}/scripts/search.js --handles sama --days 7 "thread" を実行します

トレンドの確認

ユーザー：「今日、X で AI に関して何がトレンドになっている？」 アクション： node {baseDir}/scripts/search.js --days 1 "AI trending most discussed viral" を実行します

画像検索

ユーザー：「新しい MacBook について X で共有されている画像を見せて」 アクション： node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning --days 7 "new MacBook images photos screenshots" を実行します

マルチエージェント調査

ユーザー：「今月の X における AI 安全性の議論を包括的に分析して」 アクション： node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 --days 30 "AI safety debate comprehensive analysis all perspectives" を実行します

複数ハンドルの比較

ユーザー：「@OpenAI と @AnthropicAI は AI 安全性について何と言っている？」 アクション： node {baseDir}/scripts/search.js --handles OpenAI,AnthropicAI --days 30 "AI safety" を実行します

除外フィルター

ユーザー：「ボットアカウントを除外して、X で AI ニュースを検索して」 アクション： node {baseDir}/scripts/search.js --exclude bots,spam --days 7 "AI news" を実行します

後で見るためのリンク

ユーザー：「今月のインディーハッキングに関するおすすめのツイートへのリンクを教えて」 アクション： node {baseDir}/scripts/search.js --links-only --days 30 "indie hacking best advice" を実行します

パイプ処理用の JSON

ユーザー：「TypeScript に関するツイートの生の JSON を取得して」 アクション： node {baseDir}/scripts/search.js --json "TypeScript" を実行します

一括モニタリング

ユーザー：「X で競合他社の 10 アカウントをモニタリングするよう設定して」 アクション： Batch API を使用して、競合他社のハンドルごとに 1 件、合計 10 件のクエリを一度に送信します

---

最良の結果を得るためのヒント

1. クエリは具体的にしてください。 「Claude Code tips for monorepos」のほうが、「Claude Code」よりも常に優れています。
2. ハンドルによるフィルターで、関連性を高めましょう。 特定のユーザーをフォローすると、ノイズを大幅に減らせます。
3. 目的に合わせて期間を設定してください。 速報なら1日、週間まとめなら7日、調査なら30〜90日です。
4. 画像を含むクエリにはgrok-4.20モデルを使ってください。 Xから画像の検索結果を返すのはこれらのモデルだけです。
5. 詳細な調査にはマルチエージェントを使ってください。 grok-4.20-multi-agent-beta-0309は、多角的な分析に優れています。
6. モードを組み合わせましょう。 トピックを検索し、興味深いスレッドを見つけてから、そのスレッド全体を読みます。
7. 素早く確認するには--compactを使ってください。 多数のツイートをすばやく確認したいときは、コンパクトモードでコメントを省けます。
8. ワークフローには--links-onlyを使ってください。 リンクをブラウザー起動ツール、ブックマークツール、または別のスキルに渡せます。
9. プロンプトキャッシュを活用しましょう。 繰り返し検索する際にシステムプロンプトを統一すると、入力コストを90％節約できます。
10. 大量処理にはBatch APIを使ってください。 モニタリング、競合分析、調査パイプラインでは、バッチ処理が役立ちます。

---

関連スキル

• /xai - X検索を使わずにGrokと直接チャットします（一般知識、コーディング、分析）
• /last30days - 複数の情報源を対象に、過去30日間に起きたことを調査します（Xだけではありません）
• /parallel - 複数の検索を並列で実行し、調査ワークフローを高速化します