0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Firecrawl入門 — CLIキーなしで動く範囲と2日キャッシュの仕組み

0
Posted at

はじめに

AIエージェントに「Webを見に行かせる」ための土台として、FirecrawlというOSSプロジェクトが急成長しています。GitHub上のスター数は2026年7月時点で15万を超え1、公式サイトによれば週次でnpm/PyPI合わせて250万回以上ダウンロードされているとのことです2。

この記事では、firecrawl-cli を実際にインストールし、APIキーを一切設定しない状態で各コマンドがどこまで動くか を1つずつ検証しました。結果として、公式ドキュメントの説明だけでは分からなかった「キャッシュの挙動」に気づいたので、その仕組みも合わせて解説します。

この記事で分かること

  • Firecrawlの全体構成（ホスト版APIとセルフホストの違い）
  • firecrawl-cli でAPIキーなしに動くコマンド・動かないコマンドの実測結果
  • スクレイプ結果がデフォルトで2日間キャッシュされる仕組みと注意点

前提環境

  • Claude Code のクラウド実行環境（Linux・Node.js）
  • npm install -g firecrawl-cli（バージョン 1.19.26）

TL;DR

  • Firecrawlは「Webを検索・スクレイプ・操作してAIエージェントに渡す」ためのOSS API。コア部分はAGPL-3.0、SDKはMIT、CLI（firecrawl-cli）はISCライセンスです。
  • scrape と search はAPIキーなしでも動きます（IPベースの無料枠）。一方 map ・crawl ・credit-usage はログインを要求し、無料枠の対象外でした。
  • scrape はデフォルトで 2日間（172,800,000ミリ秒） 同一ページのキャッシュを返すため、同じURLを連続で叩いても最新情報が返ってこない場合があります。

Firecrawlとは

Firecrawlは「検索・スクレイプ・ページ操作をAIエージェントが使いやすい形（Markdown/JSON）で返す」ことに特化したOSSプロジェクトです。主要リポジトリは以下の構成に分かれています。

コンポーネント 役割 配布形態
firecrawl/firecrawl 本体API（Node.js/TypeScript + Rust製クローラー） AGPL-3.0（セルフホスト可）
firecrawl-cli（npm） ターミナルから scrape/search/crawl 等を叩くCLI ISC
firecrawl / @mendable/firecrawl-js（npm） JavaScript SDK MIT

コアのAPIサーバーはAGPL-3.0、SDKはMIT、CLIはISCという住み分けになっており、SDK経由でホスト版APIを叩く分には商用利用でも問題になりにくい構成です1。

CLIを導入する

npm install -g firecrawl-cli
firecrawl --version

実行すると、以下のようにインストールできました（当セッションで実行・生ログ）。

$ firecrawl --version
1.19.26

firecrawl --help でサブコマンド一覧が確認できます。scrape / crawl / map / search / agent / interact など、AIエージェントが「Webで何かを調べて操作する」ための一通りの機能が揃っています。

APIキーなしでどこまで動くか実測した

公式ドキュメントには「一部のコマンドはログインなしでも動く（keyless free tier・IPベースでレート制限）」という記載があります3。実際にログイン済みAPIキーを設定せず、FIRECRAWL_API_KEY 環境変数も設定しない状態で主要コマンドを1つずつ試しました。

動いたコマンド

$ firecrawl scrape https://example.com
Scrape ID: 019f6415-387a-7146-9405-e7e2b14af3ab
# Example Domain

This domain is for use in documentation examples without needing permission. Avoid use in operations.

[Learn more](https://iana.org/domains/example)

$ firecrawl search "test query anonymous"
Anonymous Block in Query Service | Adobe Experience Platform
  URL: https://experienceleague.adobe.com/en/docs/experience-platform/query/key-concepts/anonymous-block
  ...

scrape と search は、認証情報を何も渡していないのに実際にネットワーク越しにページ内容・検索結果を取得できました。ログインを促すプロンプトも出ません。

動かなかった（ログインを要求された）コマンド

$ firecrawl map https://example.com

  🔥 firecrawl cli v1.19.26
  Turn websites into LLM-ready data

Welcome! To get started, authenticate with your Firecrawl account.

  1. Login with browser (recommended)
  2. Enter API key manually

Enter choice [1/2]:

map ・crawl ・credit-usage の3つは、標準入力を閉じた状態（< /dev/null）で実行してもこのログイン選択画面がそのまま表示され、非対話環境では実行できませんでした。parse（ローカルファイルのMarkdown変換）はAPI通信自体が発生しないため、当然ながら認証なしで動作します。

つまり「無料枠で動く」と一括りにはできず、scrapeとsearchだけがIPベースの無料枠の対象 というのが実測結果でした。

2日間キャッシュに気づいた話

scrape コマンドで同じURLを3回連続で叩いたところ、奇妙な挙動に気づきました。ランダムなUUIDを返す https://httpbin.org/uuid を3回スクレイプすると、3回とも同じUUID が返ってきたのです。

$ for i in 1 2 3; do firecrawl scrape "https://httpbin.org/uuid"; done
{"uuid": "dee83b13-c9d7-4a2f-a840-4a0a5eeb4dd5"}
{"uuid": "dee83b13-c9d7-4a2f-a840-4a0a5eeb4dd5"}
{"uuid": "dee83b13-c9d7-4a2f-a840-4a0a5eeb4dd5"}

比較のため、同じURLを curl で直接2回叩くと、想定通り毎回異なるUUIDが返りました。

$ curl -s https://httpbin.org/uuid; curl -s https://httpbin.org/uuid
{"uuid": "db8705e9-ab31-4775-b609-2af39a098c65"}
{"uuid": "98baafcf-1e34-4ece-8ae4-05e5a4d362fc"}

つまりこのキャッシュはネットワーク経路の問題ではなく、Firecrawl側の仕様でした。公式ドキュメントの scrape エンドポイントには maxAge というパラメータがあり、デフォルト値は172,800,000ミリ秒（2日間） と明記されています。この期間内にキャッシュされたページがあれば、実際にページへアクセスし直さずキャッシュを返す仕様です4。

maxAge（デフォルト: 172800000ms = 2日）
  → この期間内にキャッシュされたバージョンがあれば、再スクレイプせずキャッシュを返す
  → 常に最新のページ内容が必要な場合は maxAge: 0 を明示的に指定する

料金プランのドキュメントには「新鮮さが不要ならキャッシュを有効にすると高速化できる」という説明はあっても、「デフォルトで2日間キャッシュされる」点は積極的に強調されていません。速報性が必要なスクレイプ（在庫確認・価格監視・最新ニュース収集など）にそのまま使うと、意図せず古い情報を掴んでしまう可能性があるため注意が必要です。

セルフホストの選択肢

Firecrawl本体はDockerで自前ホストすることも可能です。公式の SELF_HOST.md によれば、以下の構成が必要になります5。

  • Docker / Docker Compose
  • Redis（キュー管理・レート制限）
  • PostgreSQL（設定・スクレイプデータの保存）
  • Playwright（ブラウザベースのスクレイピング用マイクロサービス）
# .env を用意してから
docker compose build
docker compose up

CLIから使う場合は --api-url にセルフホスト先のURLを指定すると、ホスト版のAPIキー認証がスキップされる仕様になっています。ただし公式ドキュメントは「セルフホスト版にはFire-engine（IPブロック回避等の強化機能）が含まれない」と明記しており、大規模サイトのクロールにはホスト版との機能差がある点は理解しておく必要があります5。

著者視点の発見ポイント

実際に手を動かして一番驚いたのは、「無料で動く」という触れ込みの粒度が公式ドキュメントの説明より細かかった点です。ドキュメント上は「一部コマンドがログインなしで動く」としか書かれておらず、どのコマンドが対象かは実際に1つずつ叩いてみるまで分かりませんでした。scrape と search だけが無料枠の対象で、map や crawl はいきなりログイン画面に遷移する——この非対称性は、CI/CD等の非対話環境でFirecrawlを組み込もうとしたときに事前に把握しておかないとハマりやすいポイントだと感じました。

まとめ

  • Firecrawlは検索・スクレイプ・ページ操作をAIエージェント向けに提供するOSSプロジェクト。コアはAGPL-3.0、SDKはMIT、CLIはISC。
  • firecrawl-cli は scrape と search だけがAPIキーなしのIPベース無料枠で動作し、map・crawl・credit-usage はログインが必須。
  • scrape はデフォルトで2日間キャッシュを返す仕様。速報性が必要な用途では maxAge: 0 を明示するか、この挙動を前提に設計する必要がある。

無料枠だけで試せる範囲は限られていますが、「AIエージェントにWebを見せる」実装の第一歩として、CLIをインストールしてどのコマンドが実際に動くか手元で確認してみることをおすすめします。

参考リンク

  1. firecrawl/firecrawl - GitHub（2026年7月時点でスター15万超・AGPL-3.0コア＋MIT SDK構成を確認） ↩ ↩2

  2. Firecrawl公式サイト「About」（週次250万ダウンロードの記載） ↩

  3. Firecrawl CLI Docs（keyless free tierの記載） ↩

  4. Firecrawl Scrape API Reference（maxAge デフォルト172800000msの記載） ↩

  5. SELF_HOST.md - firecrawl/firecrawl（Docker/Redis/PostgreSQL/Playwright構成、Fire-engine非対応の記載） ↩ ↩2

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?