jo-inc/camofox-browser — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでAI エージェント向けのボット検出回避ブラウザサーバー、Camoufox で C++ レベルのフィンガープリントスプーフィングを実装

camofox-browser は、Camoufox(C++レベルで指紋偽装を行うFirefoxフォーク)をREST APIでラップした、AIエージェント向けのステルスヘッドレスブラウザサーバーです。Cloudflareやボット検知を回避しつつ、PuppeteerやPlaywrightの代替として使える設計になっています。OpenClawプラグインやMCPサーバーとしても提供され、既存のエージェント基盤に組み込めます。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

server.js が Express ベースのREST APIを立て、lib/launcher.js が Camoufox バイナリを起動してブラウザセッションをユーザーIDごとに分離管理します。生のHTMLではなくアクセシビリティスナップショットを返し、各要素に e1・e2 のような安定した参照IDを付与するため、エージェントは座標ではなく参照でクリックやタイプを実行できます(lib/snapshot.js)。plugins/ 配下は persistence(cookie・localStorage・IndexedDBの永続化)、vnc(noVNC経由の対話ログイン)、youtube(yt-dlpによる字幕抽出)という3つの拡張機能で構成され、いずれも events フックで本体に接続します。mcp/server.mjs は同じ mcp/lib/tool-contracts.mjs を参照し、OpenClawプラグインとMCPサーバーでツールの挙動が構造的に一致するよう設計されています。Dockerfile ではビルド時にCamoufoxバイナリを焼き込み、Xvfbで仮想ディスプレイを用意してWebGLレンダリングまで擬似的なデスクトップ環境として動かします。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
git clone後に npm install を実行すると、postinstallスクリプトが約300MBのCamoufoxバイナリを初回だけダウンロードします。
STEP 02
npm start を叩くと http://localhost:9377 でサーバーが起動し、health エンドポイントやOpenAPIドキュメントが/docsで確認できます。
STEP 03
camofox_create_tab や camofox_navigate といったツールでページを開くと、生HTMLの代わりにアクセシビリティスナップショットとe1・e2形式の要素参照が返ってきます。
STEP 04
cookie未導入の状態でログイン系サイトを操作すると、plugins/vnc を有効化してnoVNC(6080番ポート)経由で人間が視覚的にログインし、storage_stateをエクスポートする流れを体験できます。
STEP 05
YouTube動画URLを /youtube/transcript に投げると、まずyt-dlpによる高速抽出が試され、未インストールの場合はブラウザベースのフォールバックに自動で切り替わります。
STEP 06
idle状態が続くとブラウザプロセスが自動シャットダウンし、メモリ使用量が約40MBまで下がる挙動を、$5 VPSやRaspberry Piのような小規模環境で確認できます。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

手元には、アクセシビリティスナップショットと要素参照(e1・e2など)でエージェントを安全にページ操作させられるREST API、OpenClawプラグイン、MCPサーバーの3形態が揃います。加えてcookie永続化・VNC対話ログイン・YouTube字幕抽出・プロキシ経由のGeoIP設定・セッショントレースなど、実運用を意識した周辺機能一式が手に入ります。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

初回起動で約300MBのCamoufoxバイナリをダウンロードするため、ネットワーク環境やディスク容量によっては起動までに時間がかかります。

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD環境変数がすでに設定されている環境では、README記載の通り注意しないとバイナリ取得がスキップされ実行時にクラッシュします。

better-sqlite3のネイティブビルドはDebianのバージョン差(bookwork系とtrixie系)でglibc互換性の問題が起きる旨がDockerfileのコメントに明記されており、環境依存の落とし穴として留意が必要です。

匿名化されたクラッシュ・ハングのテレメトリがGitHub Issue経由でデフォルト送信される仕様のため、社内ポリシー次第ではCAMOFOX_CRASH_REPORT_ENABLED=falseでのオプトアウト確認が必要です。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

AIエージェントに実際のウェブサイトを操作させたいが、既存のヘッドレスブラウザがボット検知で弾かれて困っている開発者に向いています。unit・e2e・live・pluginsと層別に整理されたテスト群、OpenAPI自動生成、MCPとOpenClawで挙動を共有する設計など、README記載の主張を裏付けるソース構造がそろっているため、実機検証なしでも一定の信頼性を持って判断してよいレポジトリだと言えます。ただし初回起動の重さや環境依存の落とし穴は事前に把握したうえで導入するのが安全です。