jo-inc/camofox-browser

camofox‑browser – AIエージェント向けの反検出ブラウザサーバー

何であるか – 特別にパッチされたFirefoxビルド（Camoufox）を実行し、AIエージェントが本物のウェブをブロッキングされずに閲覧できるREST APIを公開する、非常に小さなNode.jsサーバーです。ブラウザのフィンガープリントはC++レベルでスプーフィングされるため、サイトはヘッドレスまたはインストルメント化されたブラウザではなく、通常のFirefoxと見なします。

エージェントにとってなぜ重要か – 現代のウェブスクレイピングツール（Playwright、ヘッドレスChrome）は、Cloudflare、Googleなど、さまざまなボット検出サービスによってますますブロックされるようになっています。camofox-browserは以下の方法でこの問題を解決します：

• JavaScriptが実行される前から、CPUコア数、WebGL、AudioContext、画面サイズ、WebRTCなど、低レベルのプロパティをスプーフィングします。
• アクセシビリティスナップショット（ページのコンパクトでスクリーンリーダー対応の表現）を提供し、これは生のHTMLと比べて約90 %小さくなり、LLM駆動エージェントのトークン予算を節約します。
• 安定した要素参照（e1, e2, …）を提供するため、エージェントは脆弱なCSS/XPathセレクタに依存せずに、確実にクリックや入力が可能です。

主な機能（READMEに記載）

機能	機能内容
C++反検出	Firefoxのバイナリレベルでパッチすることで、Google、Cloudflare、およびほとんどのボット検出器を回避します。
要素参照	インタラクティブ要素に対して安定した短いIDを返し、エージェントのコマンドを決定論的にします。
トークン効率の良いスナップショット	完全なHTMLではなくアクセシビリティツリーを送信し、ペイロードサイズを大幅に削減します。
低リソースフットプリント	ライズランチとアイドルシャットダウンにより、メモリ使用量は約40 MiBに保たれます。安価なVPSやRaspberry Piでも動作可能。
セッションの隔離と永続化	ユーザーごとに個別のクッキー/ストレージを提供；~/.camofox/profiles/にオプションで永続化。
クッキーインポート	Netscape形式のクッキーファイルを受け取り、エージェントが既存のログイン（例：LinkedIn、Amazon）を再利用可能。
ファイルアップロード	設定されたディレクトリからのファイルを、ネイティブOSダイアログなしにエージェントが添付可能。
プロキシ + GeoIP	住宅用プロキシ経由でトラフィックをルーティング；プロキシIPに合わせてロケール、タイムゾーン、地理的位置を自動同期。
YouTube字幕	yt‑dlp経由で字幕を取得（APIキー不要）。
検索マクロ	@google_search、@youtube_search、@amazon_searchなど、ビルトインのショートカット。
スナップショットスクリーンショット	アクセシビリティスナップショットとともにbase64エンコードされたPNGを返します。
大規模ページ処理	オフセットベースのページネーションでスナップショットを切り詰め、応答を管理可能に保ちます。
ダウンロードキャプチャ	ブラウザがダウンロードしたファイルをキャプチャし、API経由で利用可能（base64インラインはオプション）。
DOM画像抽出	<img>のソース/altテキストをリストアップし、data-URL形式で返すことも可能。
どこでもデプロイ可能	Docker、Fly.io、Railway、または直接npm startで実行。
VNCインタラクティブログイン	NoVNC UIにより、人が視覚的にログイン可能；その結果のストレージ状態はエージェントで再利用可能。
OpenAPIドキュメント	/openapi.jsonに自動生成された仕様、/docsにインタラクティブなSwagger UI。
構造化抽出	/tabs/:tabId/extractにJSONスキーマをPOSTし、フィールドをスナップショット参照（x‑ref）にマッピング。
セッショントレース	オプションで各セッションごとにPlaywrightトレース（スクリーンショット、DOM、ネットワーク）を提供；zip形式でダウンロード可能。
テレメトリ	匿名のクラッシュ/フリーズ報告はCloudflare Workerに送信され、GitHubイシューが作成されます；無効化可能。

実行方法

1. クローン＆インストール

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 最初の実行時にCamoufoxバイナリ（~300 MiB）をダウンロード
   npm start     # http://localhost:9377 でリスニング
   

2. オプション – Docker（本番環境推奨）

   make up            # イメージ構築、バイナリダウンロード、コンテナ起動
   # 停止／削除
   make down
   

   MakefileはCPUアーキテクチャ（x86_64またはaarch64）を自動検出し、Camoufox + yt‑dlpを事前にダウンロードするため、ビルドが高速です。
3. 設定 – 多くの動作は環境変数で制御されます。例：
   • CAMOFOX_API_KEY – 特権エンドポイント（クッキーインポート、VNCログイン）に必要なシークレットトークン。
   • PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD – プロキシルーティングを有効化。
   • CAMOFOX_CRASH_REPORT_ENABLED=false – テレメトリを無効化。
   • CAMOFOX_EXECUTABLE – 自分で管理する場合、事前にダウンロードしたCamoufoxバイナリへのパスを指定。

典型的なエージェントワークフロー

1. タブ作成 – POST /tabs に {userId, sessionKey, url} を送信し、tabId を返す。
2. スナップショット取得 – GET /tabs/:tabId/snapshot でアクセシビリティツリーとbase64 PNGを返す。
3. 操作 – POST /tabs/:tabId/click、.../type、.../scroll などを使い、安定したID（e1, e2）で要素を参照。
4. 構造化データ抽出 – 望ましいフィールドをx‑refIDにマッピングするJSONスキーマを定義し、/tabs/:tabId/extractにPOST。
5. 終了 – DELETE /tabs/:tabId（またはセッション全体を閉じる）でリソースを解放し、オプションでトレースを保存。

統合ポイント

• OpenClawプラグイン – READMEにはopenclawプラグイン（@askjo/camofox-browser）が記載されており、HTTP呼び出しを便利なCLIコマンド（camofox_create_tab, camofox_clickなど）にラップします。OpenClawエージェントフレームワークを使っている開発者に有用です。
• スタンドアロンCLI – npx @askjo/camofox-browser でリポジトリをクローンせずにサーバーを実行可能。
• OpenAPI – 生成された仕様により、任意の言語でクライアントライブラリを生成でき、カスタムLLMオーケストレーターに簡単に統合できます。

開発者 – このプロジェクトは、ユーザーのMacとクラウドマシンの両方で動作する個人用AIアシスタント「Jo」の背後にあるチームによって維持されています。同じチームが、基盤となるフィンガープリントスプーフィングFirefoxフォーク「Camoufox」も開発しました。

---

TL;DR

• camofox‑browser = フィンガープリントスプーフィングされたFirefox（Camoufox）をラップした軽量RESTインターフェース。
• ブロックされずにオープンウェブを閲覧する必要があるAIエージェント向けに設計。
• 小さな構造化スナップショット、安定した要素ID、クッキーインポート、プロキシサポート、オプションのトレースを提供。
• npm install && npm start またはDocker/Makeでインストール；環境変数で設定。