camofox-browser

camofox-browser

AI エージェント向けに設計された REST API の背後で、Camoufox（C++ レベルのフィンガープリント偽装機能を備えた Firefox フォーク）をラップするヘッドレスブラウザー自動化サーバーです。デフォルトのポートは 9377 です。ソース：https://github.com/jo-inc/camofox-browser

概要

Camoufox ブラウザーエンジンを HTTP エンドポイントとして公開する Node.js/Express サーバー（server.js）です。エージェントはタブを作成し、安定した要素参照（e1、e2、…）を含むトークン効率の高いアクセシビリティスナップショットを取得して、CSS セレクターや生の座標ではなく参照を使って操作します。Cookie、プロキシ、検索マクロ、YouTube の文字起こし抽出、セッションの永続化が組み込まれています。プラグインにより、新しいルート、ライフサイクルフック、Prometheus メトリクスを追加できます。

アーキテクチャ

Browser Instance (Camoufox)
└── User Session (BrowserContext)   — isolated cookies/storage per userId
    ├── Tab Group (sessionKey)      — groups tabs by conversation/task
    │   ├── Tab (google.com)
    │   └── Tab (github.com)
    └── Tab Group
        └── Tab

主な動作：

• ブラウザーは必要になったときに起動します。アイドル状態のブラウザーは BROWSER_IDLE_TIMEOUT_MS（デフォルトは 5 分）経過後にシャットダウンし、次のリクエスト時に再起動します。アイドル時のメモリ使用量は約 40 MB です。
• セッションは SESSION_TIMEOUT_MS（デフォルトは 30 分）経過後に自動的に期限切れになります。
• セッションが MAX_TABS_PER_SESSION に達すると、エラーを返す代わりに、最も古い、または使用頻度の低いタブが再利用されます。
• すべてのログは 1 行につき 1 つの JSON オブジェクトです（{ts, level, msg, reqId, …}）。/health はリクエストログの対象外です。

インストールと実行

スタンドアロン：

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start            # downloads Camoufox on first run (~300MB)
# → http://localhost:9377

OpenClaw プラグインとして：

openclaw plugins install @askjo/camofox-browser

Docker（付属の Makefile を使用します。このファイルは、ビルド時にバインドマウント経由で Camoufox と yt-dlp を事前ダウンロードします）：

make up              # auto-detects ARCH (aarch64 on M1/M2, x86_64 on Intel)
make down
make reset           # clean rebuild
make fetch           # only download binaries
make up ARCH=x86_64 VERSION=135.0.1 RELEASE=beta.24

make fetch で用意したバインドマウントに Dockerfile が依存しているため、docker build を直接実行しないでください。

Fly.io／Railway：railway.toml が含まれています。Fly.io では、ビルド時にバイナリーをダウンロードする Dockerfile を使用してください（バインドマウントを使う Dockerfile はリモート CI では動作しません）。参考：jo-browser。

with-plugins Docker ステージ、scripts/install-plugin-deps.sh、railway.toml を含むデプロイの詳細：references/deployment.md。

エージェントの基本ワークフロー

POST /tabs                          → { tabId }
GET  /tabs/:tabId/snapshot          → accessibility tree with element refs e1, e2, …
POST /tabs/:tabId/click  { ref }    → interact
POST /tabs/:tabId/type   { ref }    → interact
POST /tabs/:tabId/navigate          → URL or search macro
DELETE /tabs/:tabId                 → cleanup

要素参照はスナップショット内では安定していますが、ページ遷移後にリセットされるため、遷移後は必ず新しいスナップショットを取得してください。スナップショットはアクセシビリティツリーに基づいているため、生の HTML より約 90％小さくなります。

ワークフローの詳細なパターン（offset を使ったページネーション、includeScreenshot=true を使ったスクリーンショット、CSS セレクターへのフォールバック、pressEnter など）：references/agent-usage.md。

認証

2 つのキーがあり、どちらも任意で、環境変数から読み込まれます（設定ファイルからは読み込まれません）。

変数	有効になる機能	未設定の場合の動作
CAMOFOX_API_KEY	Cookie インポートエンドポイント（POST /sessions/:userId/cookies）および ctx.auth() を使用するすべてのルート	それらのルートでサーバーが 403 を返します
CAMOFOX_ADMIN_KEY	POST /stop	エンドポイントが拒否されます

リクエストは Authorization: Bearer <key> で認証します。ループバック（127.0.0.1）からのリクエストでは、Bearer チェックがスキップされます。openssl rand -hex 32 でキーを生成できます。

REST API の概要

主なグループ — スキーマとクエリパラメーターの詳細：references/api-reference.md。

グループ	エンドポイント
タブのライフサイクル	POST /tabs、GET /tabs、GET /tabs/:id/stats、DELETE /tabs/:id、DELETE /tabs/group/:groupId、DELETE /sessions/:userId
ページ操作	GET /tabs/:id/snapshot、POST /tabs/:id/click、/type、/press、/scroll、/navigate、/wait、GET /tabs/:id/links、/images、/downloads、/screenshot、POST /tabs/:id/back、/forward、/refresh
YouTube	POST /youtube/transcript（yt-dlp による高速処理、ブラウザーへのフォールバック）
セッション	POST /sessions/:userId/cookies、GET /sessions/:userId/storage_state
サーバー	GET /health、POST /start、POST /stop

検索マクロ

検索 URL を組み立てる代わりに、{"macro": "@<name>", "query": "…"} を使って移動します。

@google_search · @youtube_search · @amazon_search · @reddit_search · @reddit_subreddit · @wikipedia_search · @twitter_search · @yelp_search · @spotify_search · @netflix_search · @linkedin_search · @instagram_search · @tiktok_search · @twitch_search

Reddit マクロは HTML を解析せず、JSON を直接返します。@reddit_subreddit にクエリ "programming" を指定すると、/r/programming.json を取得します。

セッション、Cookie、プロキシ、VNC

• userId による ユーザーごとのセッション分離。sessionKey によるタブのグループ化（旧エイリアス：listItemId）。
• Cookie のインポート：Netscape 形式のファイルを ~/.camofox/cookies/ に配置します（CAMOFOX_COOKIES_DIR で変更できます）。リクエストあたり最大 500 個の Cookie、ファイルサイズは最大 5 MB、フィールドは Playwright の許可リストに基づいてサニタイズされ、パストラバーサルはブロックされます。
• セッションの永続化：persistence プラグインは、各ユーザーの storage_state.json を ~/.camofox/profiles/<hashed-userId>/ に書き込みます。camofox.config.json で "persistence": { "enabled": false } を指定して無効にするか、CAMOFOX_PROFILE_DIR でパスを変更できます。
• プロキシモード：シンプルモード（PROXY_HOST／PROXY_PORT による単一エンドポイント）または PROXY_STRATEGY=backconnect（Decodo／Bright Data／Oxylabs 用のローテーションするスティッキーセッション）。Camoufox の GeoIP は、プロキシの出口 IP に基づいてロケール、タイムゾーン、位置情報を自動設定します。
• VNC によるインタラクティブなログイン：ENABLE_VNC=1 と VNC_PASSWORD を設定します。noVNC の Web UI は NOVNC_PORT（デフォルトは 6080）で利用できます。GET /sessions/:userId/storage_state で、生成された認証状態をエクスポートします。

詳細（Cookie の形式、backconnect セッションのローテーション、ストレージ状態の再利用、VNC のワークフロー）：references/sessions-cookies-proxy.md。

環境変数

デフォルト値を含む完全な一覧：references/deployment.md。よく設定される項目：

変数	デフォルト
CAMOFOX_PORT / PORT	9377
CAMOFOX_API_KEY	未設定（Cookie のインポートは無効）
MAX_SESSIONS	50
MAX_TABS_PER_SESSION	10
SESSION_TIMEOUT_MS	1800000（30 分）
BROWSER_IDLE_TIMEOUT_MS	300000（5 分）
HANDLER_TIMEOUT_MS	30000
MAX_CONCURRENT_PER_USER	3
MAX_OLD_SPACE_SIZE	128（MB、Node V8 ヒープ）
PROXY_STRATEGY	未設定（シンプルモード）
PROMETHEUS_ENABLED	未設定（メトリクスは無効）

プラグインシステム

プラグインは plugins/<name>/index.js に配置し、register(app, ctx) をエクスポートします。camofox.config.json（{"plugins": ["youtube", …]}）に従って読み込まれます。ファイルまたは plugins キーがない場合は、plugins/ 内のすべてのプラグインが読み込まれます（後方互換性）。

サードパーティ製プラグインを CLI からインストールします：

npm run plugin install https://github.com/user/camofox-screenshot-plugin
npm run plugin install git:github.com/user/my-plugin
npm run plugin install ./path/to/my-plugin
npm run plugin list
npm run plugin remove my-plugin

同梱されるデフォルトのプラグイン：

プラグイン	有効	目的
youtube	はい	yt-dlp（高速）またはブラウザーのフォールバック経由で /youtube/transcript を利用
persistence	はい	ユーザーごとのストレージ状態をディスクに保存
vnc	いいえ（ENABLE_VNC=1 が必要）	noVNC によるブラウザーでのインタラクティブなログイン

OpenClaw スキャナーの分離（重大な制約）

OpenClaw のスキルスキャナーは、1 つの .js ファイルにルールペアの両方が含まれているとフラグを立てます。違反すると公開ができなくなります。ルール：

• env-harvesting（CRITICAL）：同じファイル内に /process\.env/ と /\bfetch\b|\bpost\b|http\.request/i。正規表現では大文字と小文字が区別されないため、'POST' のような文字列リテラルや process.env に言及するコメントも検出されます。
• dangerous-exec（CRITICAL）：同じファイル内に child_process のインポートと exec／spawn の呼び出し。
• potential-exfiltration（WARN）：同じファイル内に readFile と fetch／post／http.request。

適用される構成：

• process.env の読み取りは lib/config.js のみに配置します。
• child_process／execFile／spawn は plugins/youtube/youtube.js、plugins/vnc/vnc-launcher.js、lib/launcher.js のみに配置します。
• server.js にはルートを配置しますが、process.env と child_process は一切含めません。
• lib/metrics.js には process.env と HTTP メソッドの文字列リテラルを含めません。prom-client は PROMETHEUS_ENABLED=1 の場合にのみ遅延ロードされます。
• lib/request-utils.js には HTTP メソッドの文字列を含めますが、process.env は含めません。

環境変数やサブプロセスを必要とする機能を追加するときは、そのコードを lib/ モジュールに配置し、結果を server.js またはプラグインのルートファイルにインポートしてください。

プラグインの register(app, ctx) API、29 イベントのバス、ctx.createMetric、変更可能なフック（browser:launching、session:creating など）、依存関係ファイル apt.txt と post-install.sh、およびリファレンス実装の youtube については、references/plugin-development.md を参照してください。

テスト

npm test               # unit + e2e + plugin
npm run test:e2e       # e2e only
npm run test:live      # hits real sites (Google, macros)
npm run test:debug     # with server stdout
npm run test:plugins   # all plugin tests
npx jest plugins/youtube

主要ファイル

• server.js — Express のルートとブラウザーのロジック（process.env、child_process は含みません）
• lib/config.js — すべての環境変数の読み取り
• lib/launcher.js — Camoufox サブプロセスの起動
• lib/cookies.js — Cookie ファイルの入出力
• lib/metrics.js — Prometheus メトリクス（遅延ロード）
• lib/request-utils.js — actionFromReq、classifyError
• lib/snapshot.js — アクセシビリティツリー
• lib/macros.js — 検索マクロの URL 展開
• lib/plugins.js — プラグインローダーとイベントバス
• lib/auth.js — API キー／ループバックミドルウェア
• lib/persistence.js — アトミックなストレージ状態
• lib/inflight.js — 処理中のリクエストの集約
• lib/tmp-cleanup.js — 孤立した一時ファイルのクリーンアップ
• camofox.config.json — プラグインの読み込みリスト
• openclaw.plugin.json — OpenClaw ゲートウェイ統合マニフェスト（camofox 独自の設定とは別）
• plugins/youtube/、plugins/persistence/、plugins/vnc/ — 同梱プラグイン
• scripts/install-plugin-deps.sh — apt.txt と post-install.sh 用の Docker ビルドフック

参考資料

ファイル	読むタイミング
api-reference.md	正確なエンドポイントのスキーマ、クエリパラメーター、リクエスト／レスポンス本文
deployment.md	Docker／Fly／Railway／Make のターゲット、環境変数の一覧、ロギング、yt-dlp のインストール
agent-usage.md	スナップショット → ref → クリックのフロー、ページネーション、スクリーンショット、マクロの使い方
sessions-cookies-proxy.md	Cookie のインポート、セッションの永続化、プロキシ／GeoIP、VNC ログイン、ストレージ状態の再利用
plugin-development.md	register(app, ctx) API、イベント、スキャナーの分離、メトリクス、依存関係ファイル