セットアップ: Crawl4AI (サイドカー)

免責事項

このページは生成AIによって作成された下書きです。内容は確認済みですが、正確な情報はソースコードもあわせてご確認ください。

セットアップ: Crawl4AIサイドカー

fetch_urlツールは、デフォルトでプロセス内のsafe_httpエンジンを使用します。JSを多用するページでレンダリングされたコンテンツが必要な場合、信頼された開発環境でのみブラウザレンダリングサイドカーをオプションで使用できます。

デフォルトのエンジンの順序はsafe_httpです。Crawl4AIはTomoriBotの保護されたHTTPクライアント外でリダイレクトを追跡するため、プライベートネットワーク取得が許可されている場合にのみ使用されます。本番環境以外では自動的に許可され、設定は不要です。本番環境では明示的なFETCH_URL_ALLOW_PRIVATE_NETWORK=trueのオプトインが必要ですが、推奨しません。

Crawl4AIは、ブラウザでレンダリングされたマークダウンサイドカーです。Playwrightベースのヘッドレスブラウザを実行し、独自のコンテンツフィルターを使用してLLMフレンドリーなマークダウンをサーバー側で抽出します。TomoriBot側での後処理は必要ありません。

Crawl4AIのセットアップパスを1つ選択してください。

A. Docker Compose (TomoriBotをDockerで実行する場合)

リポジトリのDocker ComposeスタックでTomoriBotを実行している場合は、このパスを使用します。まず、.envにCRAWL4AI_BASE_URL=http://crawl4ai:11235/とFETCH_URL_ENGINE_ORDER=crawl4ai,safe_httpを設定します。本番環境以外ではプライベートネットワークのオプトインは不要です。このスタックをRUN_ENV=productionで実行する場合のみFETCH_URL_ALLOW_PRIVATE_NETWORK=trueを追加してください。

次に、以下で起動します。

docker compose --profile fetch-crawl4ai up -d

これにより、TomoriBotのDockerネットワーク上でCrawl4AIサイドカーを含むComposeスタックが開始されます。

TomoriBotをbun run devで直接実行している場合は、代わりに以下のスタンドアロンパスを使用してください。

SearXNGサイドカーも必要な場合は、プロファイルをチェーンします。

docker compose --profile searxng --profile fetch-crawl4ai up -d

Crawl4AIのAPIトークン認証を有効にする場合は、.envにCRAWL4AI_TOKENを設定します。ComposeはそれをCRAWL4AI_API_TOKENとしてコンテナに渡し、TomoriBotはそれをベアラートークンとして送信します。

---

B. スタンドアロンDocker (bun run devを実行する場合)

まず、ボットがホストの公開されたコンテナポートに接続するように、.envにCRAWL4AI_BASE_URL=http://localhost:11235/とFETCH_URL_ENGINE_ORDER=crawl4ai,safe_httpを設定します。本番環境以外ではプライベートネットワークのオプトインは不要です。RUN_ENV=productionで実行する場合のみFETCH_URL_ALLOW_PRIVATE_NETWORK=trueを追加してください。

次に、TomoriBotをbun run devで直接実行する代わりに、bun run launch --crawl4aiを使用します。これにより、コンテナのライフサイクルが自動的に処理され、サイドカーが正常になるのを待ってからボットが起動します。

bun run launch --crawl4ai

SearXNGサイドカーも必要な場合:

bun run launch --searxng --crawl4ai

コンテナを自分で管理したい場合は、.envのCRAWL4AI_BASE_URL=http://localhost:11235/を維持したまま、以下を実行します。

PowerShell:

docker run -d --name crawl4ai -p 11235:11235 --shm-size=3g `
  unclecode/crawl4ai:latest

Bash (Linux/macOS):

docker run -d --name crawl4ai -p 11235:11235 --shm-size=3g \
  unclecode/crawl4ai:latest

サイドカーを保護する場合は、docker runに-e CRAWL4AI_API_TOKEN=your_tokenを渡し、.envにCRAWL4AI_TOKEN=your_tokenを設定します。

その後、コンテナが正常に動作したら（docker psで(healthy)と表示されたら）、bun run devを実行します。

---

C. ブラウザサイドカーなし

CRAWL4AI_BASE_URLは設定しないでください。fetch_urlツールは保護されたsafe_httpエンジンを使用します。

---

起動順序 (重要)

TomoriBotは、起動後の最初のfetch_url呼び出しでサイドカーのヘルスをプローブし、その結果を60秒間キャッシュします。その最初のプローブが実行されたときにコンテナの準備ができていない場合、ボットは次の1分間、コンテナが利用できないものとして扱います。

スタンドアロンDockerの場合、TomoriBotを起動する前にサイドカーコンテナを起動してください。bun run launch --crawl4aiはすでにこれを自動で行います。

初回セットアップ

1. コンテナを起動し、docker psで(healthy)と表示されるまで待ちます。

   docker ps

2. 上記のセットアップパスの値を使用して、.envにCRAWL4AI_BASE_URLを設定します。
3. TomoriBotを起動します（bun run devまたはdocker compose up）。

再起動後の復帰

以前の実行でコンテナがすでに存在する場合は、名前の競合を避けるためにdocker runの代わりにdocker startを使用してください。

# Start an existing container
docker start crawl4ai

# Confirm healthy before starting TomoriBot
docker ps

その後、通常通りTomoriBotを起動します。bun run devを再起動すると、メモリ内のヘルスキャッシュがリセットされるため、コンテナの準備が先にできていれば、正しいエンジンがすぐにピックアップされます。

---

Cookieの注入 (認証済みフェッチ：オプション)

Crawl4AIは、ページをフェッチする際にヘッドレスブラウザがすでにログインしているように見せるために、ブラウザレベルのCookieの注入をサポートしています。これは、コンテンツを表示するためにセッションが必要なサイト（ペイウォールのニュース、プライベートフォーラム、ログインで保護されたダッシュボードなど）に役立ちます。

safe_httpフォールバックはCookieの注入をサポートしていません。CookieはCrawl4AIがアクティブな場合にのみ適用されます。

制限事項: Cookieの注入はログインの壁をバイパスしますが、ボットのフィンガープリントはバイパスしません。積極的なボット検出（特にTwitter/X）を行うサイトは、キャンバス/WebGLのフィンガープリントを通じてヘッドレスPlaywrightを検出し、有効なセッションCookieがあっても空のページを提供します。Cookieの注入は、認証のみで制限をかけているサイトでうまく機能します。

Cookieの取得

1. ブラウザを開き、ターゲットサイトにログインします。
2. 開発者ツール（F12）→ アプリケーションタブ → ストレージ → Cookie → サイトのドメインを選択します。
3. 必要な各CookieのValue（通常はセッショントークン：サイトのCookie名を確認してください）をコピーします。

Crawl4AI

.envでCRAWL4AI_COOKIES_JSONをJSON配列として設定します。

CRAWL4AI_COOKIES_JSON=[{"name":"session","value":"YOUR_SESSION_TOKEN","domain":".example.com"}]

これが設定されると、fetch_urlは自動的に/mdエンドポイントからbrowser_config.cookiesを使用した/crawlに切り替わります。/mdはCookieの注入をサポートしていません。

Cookieオブジェクトのフィールド

フィールド	必須	説明
name	はい	Cookie名
value	はい	Cookie値
domain	いいえ	ドメインのスコープ（例: .x.com）。正確性を期すために推奨されます。
path	いいえ	パスのスコープ。省略した場合、デフォルトは/になります。

注意: Cookieの値は機密情報です。パスワードのように扱ってください。これらはあなたのアカウントへの完全なセッションアクセスを許可します。.envをバージョン管理にコミットしないでください。

---

エンジンの順序と環境変数

変数	デフォルト	説明
CRAWL4AI_BASE_URL	未設定	設定するとCrawl4AIが有効になります。Docker Composeからはhttp://crawl4ai:11235/を使用し、TomoriBotがマシンで直接実行されている場合はhttp://localhost:11235/を使用します。
CRAWL4AI_TOKEN	未設定	オプションのベアラートークン。有効にする場合は、Crawl4AIコンテナのCRAWL4AI_API_TOKENと一致する必要があります。
FETCH_URL_ENGINE_ORDER	safe_http	コンマ区切りのエンジンリスト。safe_httpは常に最終フォールバックとして追加され、従来のmcp_fetch名はそのエイリアスです。プライベートネットワーク取得が許可されていない場合（オプトインなしの本番環境）、Crawl4AIは無視されます。
FETCH_URL_TIMEOUT_MS	15000	Crawl4AIおよびURLフェッチサイドカーのエンジンごとのリクエストタイムアウト。
FETCH_URL_MAX_CONTENT_LENGTH	50000	続きを取得する必要が生じる前に、1回のフェッチで返す最大文字数。
FETCH_URL_HEALTHCHECK_CACHE_SEC	60	Crawl4AIのヘルスプローブ結果が再チェックされる前にキャッシュされる時間。
FETCH_URL_ALLOW_PRIVATE_NETWORK	false	本番環境専用のオプトイン。本番環境以外（RUN_ENV != production）ではSSRFガードが自動的に緩和されるため、localhost/プライベート/内部URLの取得とCrawl4AIディスパッチは設定なしで機能します。信頼された本番環境でプライベートネットワーク取得を許可する場合のみtrueに設定してください。
FETCH_URL_FILTER_MODE	fit	Crawl4AIの/mdフィルターモード。fitはLLMで使用するためにマークダウンをクリーンに保ちます。fetch_url(..., raw=true)はリクエストごとにこれをオーバーライドします。