jo-inc/camofox-browser

Stealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.

camofox-browser – AIエージェントのための検知回避ブラウザサーバー

概要 – パッチ適用済みのFirefoxバイナリ (Camoufox) を実行し、REST APIを公開するNode-JSサービスです。自律型AIエージェントが、指紋採取やブロックをされることなくウェブを閲覧できるようにします。ブラウザはC++レベルで修正されており、JavaScriptが実行される前にハードウェア、WebGL、WebRTC、画面サイズなどを偽装します。サーバーは軽量な アクセシビリティスナップショット (ページUIツリーのコンパクトな表現) とオプションのスクリーンショットを返し、クリック、入力、スクロールなどを確実に行うための安定した要素参照 (e1, e2 …) を提供します。

AIにとっての重要性 – 大規模言語モデルエージェントは、ウェブサイトからリアルタイムの情報を取得する必要があることがよくあります。従来のヘッドレスブラウザ (Playwright, Chrome) は、ボット対策サービス (Google, Cloudflare) によって容易に検知・ブロックされます。camofox-browserは以下の方法でこれを解決します：

Camoufoxの低レベルな指紋偽装を使用し、セッションを通常のデスクトップ版Firefoxのように見せかけます。
トークン効率の良いAPIを提供し (スナップショットは生のHTMLより約90 %小さい)、LLMのトークン使用量を削減します。
セッション分離、Cookieインポート、プロキシ/GeoIP処理、VNCベースの手動ログインをサポートし、エージェントがタスク間で認証済みセッションを維持できるようにします。

主な機能

C++検知回避 – ハードウェア並行性、WebGL、AudioContext、画面ジオメトリ、WebRTCなどをJSが認識する前に偽装します。
要素参照 – 決定論的なアクションのための安定した識別子 (e1, e2)。
アクセシビリティスナップショット – コンパクトなJSON UIツリー。オプションでbase64 PNGスクリーンショット。
セッション管理 – ユーザーごとのストレージ、Cookieインポート (Netscape形式)、永続プロファイル、オプションのIndexedDB永続化。
プロキシ & GeoIP – 自動ロケール/タイムゾーンマッチングを備えた住宅用プロキシサポート。
検索マクロ – Google、YouTube、Amazon、Redditなどの組み込みショートカット。
YouTube文字起こし – yt-dlp経由 (APIキー不要)。
大規模ページ処理 – スナップショットのページネーション、ダウンロードキャプチャ、画像抽出。
トレース – セッションごとのオプションのPlaywrightトレース (スクリーンショット、DOM、ネットワーク)。zipとしてダウンロード可能。
デプロイ性 – Docker、Fly.io、Railway、Raspberry Piに対応。低いアイドルメモリ消費 (~40 MiB)。
テレメトリ – 匿名化されたクラッシュ/ヘルスレポートをCloudflare Workerに送信し、GitHub issueを作成。オプトアウト可能。

開始方法

クローンとインストール：

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install   # 初回実行時にCamoufox (~300 MiB) をダウンロード
npm start     # サーバーが9377ポートで待機

APIの呼び出し (例：タブを作成)：

curl -X POST http://localhost:9377/tabs \
     -H 'Content-Type: application/json' \
     -d '{"userId":"agent1","url":"https://example.com"}'

レスポンスには tabId とアクセシビリティスナップショットが含まれます。

提供されているOpenClawプラグインコマンド (camofox_click, camofox_typeなど) または直接HTTPエンドポイントを使用してページと対話します。

認証が必要なサイトの場合、Cookieをインポートします：

export CAMOFOX_API_KEY=$(openssl rand -hex 32)
# Netscape形式のCookieファイルを ~/.camofox/cookies/ に配置
camofox_import_cookies linkedin.txt

提供されている Makefile/build.ps1 を使用してDocker (またはFly.io/Railway) でデプロイします。スクリプトはビルドを高速化するためにバイナリを事前ダウンロードします。

典型的なユースケース – LLMベースのパーソナルアシスタント (例：jo) が 「Redditで2024 Tesla Model Yの最新レビューを探して要約して」 というリクエストを受け取ります。エージェントは camofox_browser を呼び出してRedditを開き、検索マクロを実行し、アクセシビリティスナップショットを介してUIツリーを抽出し、関連要素を解析して回答を作成します。これらすべてにおいて、基盤となるブラウザはRedditのボット対策に対して検知不可能なままです。

制限事項 / 考慮事項

Camoufoxバイナリ (≈300 MiB) が必要です。YouTube文字起こしにはオプションで yt-dlp が必要です。
テレメトリはデフォルトで有効です。プライバシーが懸念される場合は CAMOFOX_CRASH_REPORT_ENABLED=false で無効にしてください。
トレースはセッション作成時にのみ有効にでき、後から切り替えることはできません。
本サービスはPlaywright制御のFirefoxのラッパーであるため、ネットワークレベルでブラウザをブロックするサイト (IPバンなど) には、依然として信頼できるプロキシが必要です。

ライセンス – MIT。