メインコンテンツへ移動
AIチュートリアル

Playwrightで非公開・API不要のXスクレイパーを構築する

x-scraper-no-apiのインストールと使い方を解説します。Node.jsとPlaywrightで動作するセルフホスト型CLIを使い、APIキーや第三者サービスなしで、公開X検索、タイムライン、投稿への返信をJSON、JSONL、CSV、Markdownとしてエクスポートできます。

約11分で読了
Playwrightで非公開・API不要のXスクレイパーを構築する

x-scraper-no-apiの機能

x-scraper-no-apiは、ローカルで認証済みのChromiumブラウザを、Xの公開コンテンツ向けデータパイプラインに変えます。最初に一度手動でログインすると、コマンドラインツールで検索結果、公開タイムライン、公開返信付きの投稿を収集できます。

結果は、json、jsonl、csv、md形式でマシンに直接保存されます。このプロジェクトは、X APIキー、ホスト型スクレイピングサービス、プロキシ、サードパーティの中継サービスを使用しません。

主な機能

  • APIキーや開発者アカウント不要: 公式APIプランの代わりに、自分のブラウザーセッションを使用します。
  • 手動認証: ログインは自分で行い、ツールがパスワードや二要素認証コードを扱うことはありません。
  • セッションを永続化: ブラウザープロファイルは~/.xscraper/に保存されるため、次回以降はヘッドレス実行できます。
  • 高度なX検索: from:、since:、until:、min_faves:、filter:media、lang:などの演算子を使用できます。
  • LLM対応の出力: Markdownはトークン効率のよいAIエージェントのコンテキスト向けに設計され、JSON、JSONL、CSVはプログラムによるワークフローに対応します。
  • 堅牢な解析: スクレイパーは壊れやすいHTMLクラス名に依存せず、X自身のフロントエンドが送信する構造化GraphQLデータを取得します。
  • 適切なリクエスト制限: 人間らしい間隔、取得項目数の上限、Xから負荷の兆候が示された場合の自動バックオフを使用します。
  • エージェント対応: リポジトリには、OpenClaw、HermesなどのCLI対応エージェント向けSkillが含まれています。

インストールと初回セットアップ

1. macOSのビルドツールをインストールする

macOSでは、ネイティブ依存関係で必要になる場合があるため、Xcode Command Line Toolsをインストールします。

xcode-select --install

2. Node.jsをインストールする

公式インストーラーまたはバージョンマネージャーを使って、Node.js 18以降をインストールします。このプロジェクトにはNode.js 18以降が必要です。Node.jsのダウンロードページから開始できます。

3. GitHubからスクレイパーをインストールする

作業ディレクトリを作成して移動し、リポジトリから直接パッケージをインストールします。

mkdir -p 'xscraper' && cd 'xscraper' && npm install github:JoinArtisanVent/x-scraper-no-api

4. Playwright用のChromiumをインストールする

Playwrightが使用するChromiumブラウザーをダウンロードします。

npx playwright install chromium

5. 手動でログインする

初回ログインフローを開始します。

npx xscraper login

実際のブラウザーウィンドウが開きます。必要な場合は二要素認証を含め、Xへのログインを自分で行います。ツールは生成されたブラウザーセッションを~/.xscraper/にローカル保存します。認証情報を受け取ったり処理したりすることはありません。

閲覧に使用しても問題ないXアカウントを使用してください。このツールが対応するのは公開投稿のみで、非公開アカウント、ダイレクトメッセージ、制限されたコンテンツには対応していません。

基本的な使い方

高度な演算子でXを検索する

完全なX検索式をsearchコマンドに渡します。この例では、指定日以降にOpenAIが投稿した、500件以上の「いいね」が付いた投稿を検索し、Markdownで返します。

xscraper search "from:openai since:2026-01-01 min_faves:500" --limit 50 --format md

このツールは、アカウントフィルター、日付範囲、言語フィルター、メディアフィルター、エンゲージメントのしきい値など、Xの高度な検索構文に対応しています。

「最新」タブをリクエストする

検索結果は通常、デフォルトの検索動作を使用します。「最新」タブを使用する場合は--latestを追加します。

xscraper search "ai agents" --latest --limit 25

公開タイムラインをエクスポートする

公開ユーザー名を指定してtimelineを使用します。この例ではCSV出力をファイルに書き込みます。

xscraper timeline @nasa --limit 100 --format csv -o nasa.csv

投稿と公開返信を収集する

Xの投稿URLを指定してtweetコマンドを使用します。

xscraper tweet https://x.com/nasa/status/1846987139428634858 --format json

出力形式とコマンドオプション

  • --limit <n>は項目数の最大値を設定します。デフォルトは50、上限は200です。
  • --formatはjson、jsonl、csv、mdを選択します。LLMワークフローにはMarkdownが実用的です。
  • -o <file>は標準出力の代わりにファイルへ出力します。
  • --headedはブラウザーを表示したままにするため、処理の確認やトラブルシューティングができます。

JSONレコードには、投稿ID、URL、作成時刻、テキスト、言語、作成者の詳細、エンゲージメント指標、ハッシュタグ、メディア、スクレイピング時刻を含めることができます。

{
  "id": "1846987139428634858",
  "url": "https://x.com/nasa/status/1846987139428634858",
  "created_at": "Wed Oct 16 12:34:56 +0000 2026",
  "text": "Liftoff! …",
  "lang": "en",
  "author": { "username": "nasa", "name": "NASA", "verified": true },
  "metrics": { "replies": 1200, "reposts": 4800, "likes": 32000, "views": 1500000 },
  "hashtags": ["EuropaClipper"],
  "scraped_at": "2026-09-26T10:00:00.000Z"
}

AIエージェントでスクレイパーを使う

リポジトリにはskills/x-scraper-no-api/SKILL.mdにエージェントSkillが含まれています。OpenClawまたはHermesからskills/ディレクトリを参照するか、Skillマニフェストをエージェントに適したskillsフォルダーへコピーできます。

カスタムLLMスクリプトでは、CLIをサブプロセスとして実行し、Markdown出力を取得します。

import subprocess

ctx = subprocess.run(
    ["xscraper", "search", "local-first software", "--limit", "50", "--format", "md"],
    capture_output=True,
    text=True,
    timeout=600,
).stdout

付属のSkillは安全性に関する契約を定義しています。公開データのみを使用し、制限値を小さく保ち、認証情報を決して扱わず、スクレイピングしたコンテンツを信頼できない入力として扱います。

信頼性の高い実行のための高度なヒント

制限を絞り込む

設計上、1回の実行で取得できる項目数は200件までです。調査やエージェントのコンテキストには、1回の大規模な収集処理よりも、控えめな制限値で焦点を絞った検索を複数回行うほうが適しています。

プロンプトにはMarkdownを使う

出力先がLLMのプロンプトの場合は、--format mdを選択してください。この形式はトークン効率を考慮して設計されており、標準出力から直接取得したり、-oで保存したりできます。

トラブルシューティング中はヘッド付きモードを使う

ブラウザーの動作を確認したい場合は、--headedを追加してください。クエリが期待どおりに動作することを確認したら、このフラグを省略すれば、通常の実行をヘッドレスで行えます。

結果が少なくなる場合もある

コマンドが要求した数より少ない項目しか返さない場合、利用可能なタイムラインや検索結果を単に使い切った可能性があります。これは正常な動作であり、必ずしもエラーを示すものではありません。

責任ある利用の制限を守る

このプロジェクトでは、CAPTCHAの解決、プロキシのローテーション、アカウントの共有利用、認証情報の取り扱い、レート制限の回避を意図的に行いません。実行規模を控えめにし、自動的なペーシングとクールダウンが機能するようにし、Xの利用規約および適用される法律を遵守してください。

プロジェクトの仕組み

実際のChromiumインスタンスが、人間の操作と同じようにXを読み込みます。スクレイパーは、Xが自身のフロントエンドに送信するGraphQL JSONを受動的に取得し、そのデータを安定した出力スキーマに正規化します。Xの内部エンドポイントを直接呼び出すことはなく、変更されやすいHTMLのクラス名にも依存しません。

主なソースファイルは、5つの目的別の領域に分けられています。

  • src/cli.jsは、CommanderベースのCLIを定義します。
  • src/session.jsは、永続的なPlaywrightプロファイルと手動ログインを管理します。
  • src/scraper.jsは、GraphQLレスポンスをインターセプトし、レコードを正規化します。
  • src/ratelimit.jsは、ペーシング、上限、バックオフを処理します。
  • src/output.jsは、JSON、JSONL、CSV、Markdownを書き出します。

まとめ

x-scraper-no-apiは、APIキー、ツイートごとのクレジット、ホスト型の仲介サービスを使わずに、公開Xデータをローカルで収集する方法を提供します。Node.jsをインストールし、手動で一度認証すれば、CLIを使って、ファイル、スクリプト、AIエージェントのワークフローに適した形式で、焦点を絞った検索、タイムライン、公開返信をエクスポートできます。利用は控えめにし、収集したデータを責任を持って扱ってください。