camofox-browser

camofox-browser スキル

Camofox は、Camoufox + Playwright を基盤とする検出回避ブラウザー自動化システムで、以下を備えています。

• オペレーターのワークフロー向け CLI（camofox）
• プログラムによる制御向け REST API（デフォルトのポートは 9377）
• 18 個のプラグインツールを備えた OpenClaw プラグイン連携（plugin.ts）

このスキルは、デフォルトのブラウザー自動化が検知されるボット回避ワークフローに最適化されています。

Camofox と汎用ブラウザースキルの比較

次のいずれかに該当する場合は、汎用ブラウザーツールの代わりにこのスキルを使用してください。

• セッションをまたいで検出回避用のブラウザー ID を維持する必要がある。
• プロキシを考慮した位置情報の動作や地域プリセットが必要である。
• 専用の camofox ツール名を使う OpenClaw プラグインとの互換性が必要である。
• 同じランタイムに対して、CLI と REST API の両方から制御する必要がある。

シンプルなローカルの静的ページスクリプトだけが必要で、検出回避が関係しない場合は、このスキルを使用しないでください。

インターフェースのクイック選択

次の場合は CLI を使用してください。

• ターミナルから対話形式で運用やデバッグを行う。
• 認証情報に対してローカルの暗号化されたボールトプロンプトを使用する。
• アクティブなタブの状態を維持しながら、手軽に単発コマンドを連結する。

次の場合は REST API を使用してください。

• 別のサービス／エージェントランタイムから連携する。
• 明示的な userId と tabId を使って、リクエスト／レスポンスを厳密に制御する。
• OpenClaw と互換性のあるルート形式（/tabs/open、/act、/snapshot）が必要である。

1) コアワークフロー（CLI と API のデュアルインターフェース）

安定した自動化を実現するには、次のループに従ってください。

1. タブを作成／開く
2. スナップショットを取得し、新しい eN 参照を取得する
3. 参照を使って操作する
4. DOM やナビゲーションに変更があったら、スナップショットを再取得する
5. セッションの継続性を保つため、userId を一定に保つ

CLI：

camofox open https://example.com --user agent1
camofox snapshot --user agent1
camofox click e5 --user agent1
camofox type e7 "hello world" --user agent1

API：

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

curl "http://localhost:9377/tabs/<tabId>/snapshot?userId=agent1"

curl -X POST http://localhost:9377/tabs/<tabId>/click \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5"}'

デュアルインターフェースの対応関係（最も一般的な経路）：

目的	CLI	API
タブを開く	camofox open <url>	POST /tabs
参照のスナップショット	camofox snapshot	GET /tabs/:tabId/snapshot
要素をクリック	camofox click <ref>	POST /tabs/:tabId/click
テキストを入力	camofox type <ref> <text>	POST /tabs/:tabId/type
ナビゲート	camofox navigate <url>	POST /tabs/:tabId/navigate
スクリーンショット	camofox screenshot	GET /tabs/:tabId/screenshot

参照形式について：

• 通常のコマンドでは、Camofox の参照は eN 形式の値（例：e1、e2）です。
• 一部のサブコマンドでは、フォームへの割り当てで角括弧付きの値（[e1]="value"）を受け付けます。

2) 検出回避の概要（Camoufox 固有）

Camofox は、Camoufox の起動オプションとプロファイルごとのフィンガープリント永続化を使用する点で、汎用ブラウザーツールとは異なります。

• camoufox-js を使った Camoufox の起動（launchOptions）
• 生成されたフィンガープリント（generateFingerprint）をプロファイルディレクトリごとに永続化
• ヒューマナイズを有効化（humanize: true）
• プロキシを考慮した位置情報の動作（プロキシ設定時は geoip: true）
• ~/.camofox/profiles/ 配下でユーザーごとに永続コンテキストを使用。Linux/macOS ではデフォルトのユーザー名を読み取り可能な形で維持し、Windows では衝突を避けるハッシュ化された内部プロファイルキーを使用

運用時の検出回避動作：

• userId ごとに安定した ID を維持
• PROXY_HOST/PORT/USERNAME/PASSWORD からプロキシ認証情報を任意で設定可能
• Linux では、Xvfb へのフォールバックを備えた headed／仮想ディスプレイモードを任意で使用可能

不安定なボットチェックを回避しやすくする実行時の動作：

• 永続プロファイルディレクトリにより、実行のたびに新しいデバイスフィンガープリントが生成されるのを防ぎます。
• セッションを一貫して再利用することで、ストレージやトークンの急激な変動を抑えます。
• エンジンレベルのスプーフィングにより、サイト更新との競合が起きやすい不安定な JS パッチを避けます。

詳しくは、references/anti-detection.md を参照してください。

3) 必須 CLI コマンド（クイックリファレンス）

コア：

camofox open <url> [--user <user>] [--viewport <WxH>] [--geo <preset>]
camofox close [tabId] [--user <user>]
camofox snapshot [tabId] [--user <user>]
camofox click <ref> [tabId] [--user <user>]
camofox type <ref> <text> [tabId] [--user <user>]

ナビゲーションと操作：

camofox navigate <url> [tabId] [--user <user>]
camofox screenshot [tabId] [--output <file>] [--full-page] [--user <user>]
camofox fill '[e1]="john" [e2]="[email protected]"' [tabId] [--user <user>]
camofox press Enter [tabId] [--user <user>]

確認：

camofox get-text [tabId] [--selector <css>] [--user <user>]
camofox get-links [tabId] [--user <user>]
camofox eval '<js expression>' [tabId] [--user <user>]
camofox wait <selector|navigation|networkidle> [tabId] [--timeout <ms>] [--user <user>]

検索：

camofox search "openclaw plugin" --engine github [tabId] [--user <user>]

全カタログ（全 50 件）：references/cli-commands.md。

グローバルフラグについて：

--user <user>
--port <port>
--format json|text|plain

4) 重要な API エンドポイント（クイックリファレンス）

API ドキュメント：

• インタラクティブドキュメント：GET /api/docs（Swagger UI）
• 代表的なルートのサブセットを対象とする OpenAPI 3.1.0 仕様：GET /openapi.json

タブの基本フロー：

POST   /tabs
GET    /tabs
POST   /tabs/:tabId/navigate
GET    /tabs/:tabId/snapshot
POST   /tabs/:tabId/click
POST   /tabs/:tabId/type
DELETE /tabs/:tabId

状態とアセット：

POST   /sessions/:userId/cookies
GET    /tabs/:tabId/cookies
GET    /tabs/:tabId/screenshot
GET    /tabs/:tabId/downloads
GET    /users/:userId/downloads

高度な機能：

POST   /tabs/:tabId/evaluate
POST   /tabs/:tabId/evaluate-extended
POST   /tabs/:tabId/extract-resources
POST   /tabs/:tabId/batch-download
POST   /tabs/:tabId/resolve-blobs

OpenClaw 互換ルート：

GET    /
POST   /tabs/open
POST   /start
POST   /stop
POST   /navigate
GET    /snapshot
POST   /act

すべてのエンドポイントの一覧（全54件）：references/api-endpoints.md。

互換性に関する警告：

• camofox_youtube_transcript ツールは plugin.ts から削除されました。サーバールートとプラグインツールのどちらも、この機能を提供していません。

5) よく使うパターン

A) フォーム入力と送信

CLI：

camofox snapshot --user agent1
camofox fill '[e4]="Jane Doe" [e5]="[email protected]"' --user agent1
camofox press Enter --user agent1

安全上の注意：

• フィールド間でフォームが変更された場合は、スナップショットを再取得してください。
• タブの所有権を維持するため、すべての手順で同じ --user を使用してください。

API：

curl -X POST http://localhost:9377/tabs/<tabId>/type \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5","text":"[email protected]"}'

B) ステルススクレイピングのループ

camofox open https://target.example --user scraper-us
camofox snapshot --user scraper-us
camofox get-text --selector "main" --user scraper-us
camofox get-links --user scraper-us

推奨されるループの流れ：

1. ページを開く
2. スナップショットを取得する
3. テキスト／リンク／リソースを取得する
4. 次の URL にページネーションまたは移動する
5. スナップショットを再取得する

C) 検索ワークフロー（CLI エンジン）

camofox search "best playwright anti-detection" --engine duckduckgo --user research1

CLI 検索を使用する場合：

• エンジンの一覧は、実装済みの8つの CLI エンジンに固定されています。
• 対応している14のマクロターゲットでは、API のマクロナビゲーションを使用してください。

D) API マクロナビゲーション

curl -X POST http://localhost:9377/tabs/<tabId>/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","macro":"@google_search","query":"camoufox js"}'

6) 認証（Auth Vault）

Auth Vault は、CLI ワークフロー向けのローカル暗号化認証情報ストレージです。

コマンド：

camofox auth save <profile-name> [--url <url>] [--notes <notes>]
camofox auth load <profile-name>
camofox auth load <profile-name> --inject [tabId] --username-ref <ref> --password-ref <ref> [--user <user>]
camofox auth list [--format <format>]
camofox auth delete <profile-name>
camofox auth change-password <profile-name>

セキュリティモデル（実装済み）：

• ペイロード暗号化：AES-256-GCM
• KDF：Argon2id を優先し、利用できない場合は PBKDF2 にフォールバック
• ソルト：16 バイト
• IV：12 バイト
• Vault ディレクトリのモード：0700
• シークレットファイルのモード：0600

運用ガイダンス：

• シェル履歴に生のパスワードを記述するスクリプトは避けてください。
• エージェント間で共有されるログのログインワークフローでは、Vault による注入を優先してください。
• 長期間稼働するボットでは、Vault プロファイルのマスターパスワードを定期的に変更してください。

詳細：references/authentication.md。

7) セッション管理（userId の分離）

セッションの識別情報は、userId と永続プロファイルディレクトリのスコープに限定されます。

• ブラウザーコンテキストは userId をキーにします
• Cookie、プロファイル、フィンガープリントの継続性は、同じ userId に紐づきます
• 1つのフローで異なるユーザーを混在させると、タブ検索の一貫性が損なわれます

CLI パターン：

camofox open https://example.com --user account-a
camofox snapshot --user account-a
camofox click e9 --user account-a

Cookie セッションファイルのヘルパー：

camofox session save checkout-flow --user account-a
camofox session load checkout-flow --user account-a

分離に関する注意：

• tabId の検索はユーザーごとのスコープです。
• 有効な tabId に誤った userId を指定すると、見つからない場合と同様の動作になります。

8) 検索マクロ（CLI と API は別のシステム）

重要な違い：

• CLI の search がサポートするエンジンは8つです： google、youtube、amazon、bing、reddit、duckduckgo、github、stackoverflow

• API の navigate マクロは src/utils/macros.ts で14個のマクロをサポートします： @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

CLI の例：

camofox search "vite plugin" --engine github --user dev1

API マクロの例：

curl -X POST http://localhost:9377/tabs/<tabId>/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId":"dev1","macro":"@google_search","query":"vite plugin github"}'

注：API マクロと CLI 検索エンジンは別のシステムです。CLI と API の動作は分けて扱ってください。

マクロの不一致に関する注意：

• CLI には github と stackoverflow のエンジンがあります。
• 現在のマクロ実装では、API マクロセットに @github_search と @stackoverflow_search は定義されていません。

9) 地理プリセット（8種類）

組み込みのプリセット名：

• us-east
• us-west
• japan
• uk
• germany
• vietnam
• singapore
• australia

CLI：

camofox open https://example.com --geo japan --user jp-agent

API：

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

プリセットのベストプラクティス：

• 明らかなロケールとネットワークの不一致を避けるため、プリセットとプロキシのリージョンを一致させてください。

10) セキュリティ（プロキシ、検出防止設定）

セキュリティを強化して運用するには、環境変数を使用してください：

export CAMOFOX_API_KEY='<api-key>'
export CAMOFOX_ADMIN_KEY='<admin-key>'
export PROXY_HOST='proxy.example.net'
export PROXY_PORT='8080'
export PROXY_USERNAME='proxy-user'
export PROXY_PASSWORD='proxy-pass'

動作に関する注意：

• 保護対象のコアエンドポイントと OpenClaw のアクション／デバッグエンドポイントは、CAMOFOX_API_KEY が設定されている場合にのみベアラ認証を強制します（Cookie のインポート／エクスポート、evaluate、タブ／セッションのライフサイクル、ナビゲーション、操作、ダウンロード、トレース、コンソール、エラーを含みます）。
• OpenClaw の /stop には管理者キーによる認証が必要です。
• camofox download は、CLI では現在スタブ／プレースホルダーです（意図的にそのように記載されています）。

推奨される基本環境設定：

export CAMOFOX_PORT=9377
export CAMOFOX_HEADLESS=virtual
export CAMOFOX_MAX_SESSIONS=20
export CAMOFOX_MAX_TABS=10

11) スクリプト実行（camofox run）

camofox run は逐次実行型のスクリプトランナーです（DAG／オーケストレーションパイプラインではありません）。

camofox run script.txt
camofox run script.txt --continue-on-error
cat script.txt | camofox run -

スクリプト形式：

• 1 行に 1 コマンド
• # コメントをサポート
• 引用符で囲んだ引数をサポート
• 入れ子の run は拒否されます

スクリプトの例（login-and-capture.cf）：

# open login page
open https://example.com/login --user ops1
snapshot --user ops1
fill '[e3]="[email protected]" [e4]="not-stored-here"' --user ops1
press Enter --user ops1
wait networkidle --timeout 12000 --user ops1
screenshot --output login-result.png --user ops1

12) 詳細ドキュメント

• references/cli-commands.md — CLI コマンドの完全なカタログと使用パターン。
• references/api-endpoints.md — REST API のルート一覧とリクエスト／レスポンスに関する注意事項。
• references/openclaw-tools.md — OpenClaw プラグインのツール一覧とルート／ツールの対応関係。
• references/anti-detection.md — Camoufox の検出回避モデル、フィンガープリントの継続性、ステルスに関するガイダンス。
• references/authentication.md — Auth Vault の暗号化モデルと認証情報のワークフロー。
• references/session-management.md — userId の分離、コンテキストのライフサイクル、セッションの継続性。
• references/search-macros.md — CLI の検索エンジンと API のマクロナビゲーション動作。
• references/proxy-presets.md — 地域プリセット、プロキシ設定、地域を一致させる際の手法。
• references/scripting.md — camofox run のスクリプト形式、制約、実行動作。
• references/snapshot-refs.md — スナップショット参照（eN）の処理、更新ルール、要素ターゲット指定の信頼性。
• references/media-extraction.md — スクリーンショット／ダウンロード／リソースの抽出とメディアのワークフロー。
• references/display-vnc.md — 画面表示あり／仮想ディスプレイのモードと VNC の運用ガイダンス。

13) すぐに使えるテンプレート

• templates/stealth-scraping.sh — 検出回避のデフォルト設定を使用したステルススクレイピングのワークフロー。
• templates/search-and-extract.sh — 複数の検索エンジンで検索し、構造化された結果を抽出します。
• templates/authenticated-session.sh — Auth Vault でログインし、認証済みセッションを確立するフロー。
• templates/form-automation.sh — スナップショット取得、操作、検証を繰り返すフォーム自動化。
• templates/multi-session-pipeline.sh — 並列マルチセッション収集パイプライン。
• templates/screenshot-capture.sh — 監査や証拠収集のためのスクリーンショット取得ワークフロー。

14) 重要な注意事項

• このリポジトリのプラグインシステムは OpenClaw プラグインツールであり、MCP ツールではありません。
• このコードベースには MCP サーバーの実装はありません。
• 現在、OpenClaw プラグインでは plugin.ts に 18 個のツールが定義されています。
• camofox_youtube_transcript ツールは plugin.ts から削除されました。サーバールートもプラグインツールも、この機能を公開していません。
• CLI の要素参照は eN（例：e1、e2）であり、@eN ではありません。
• 開発上の判断における信頼できる唯一の情報源は AGENTS.md です。

信頼性の高いトラブルシューティング用チェックリスト：

1. camofox health --format json
2. camofox get-tabs --user <user> --format json でタブの存在を確認します
3. camofox snapshot で参照を更新します
4. 同じ --user を指定して、失敗した操作を再実行します
5. 画面表示モードを変更した場合は、新しいタブを作成します（古いタブ ID は無効になります）

付録 A — 50 コマンドのクイックインデックス

コア（5）：

• open
• close
• snapshot
• click
• type

ナビゲーション（4）：

• navigate
• screenshot
• go-back
• go-forward

コンテンツ（7）：

• get-text
• get-url
• get-links
• get-tabs
• eval
• wait
• search

インタラクション（6）：

• fill
• scroll
• select
• hover
• press
• drag

コンソール／エラー取得（2）：

• console
• errors

トレース（5）：

• trace start
• trace stop
• trace chunk-start
• trace chunk-stop
• trace status

セッション（4）：

• session save
• session load
• session list
• session delete

ダウンロード／Cookie（4）：

• cookie export
• cookie import
• download（スタブ）
• downloads

認証（5）：

• auth save
• auth load
• auth list
• auth delete
• auth change-password

サーバー（3）：

• server start
• server stop
• server status

高度な機能（4）：

• annotate
• health
• version
• info

パイプライン（1）：

• run

付録 B — API エンドポイントの種類

コア REST ルート（core.ts）：

• Cookie：ユーザー／タブ単位でインポート／エクスポート
• ライフサイクル：ヘルスチェック、プリセット、タブの作成／一覧表示／終了、セッションの終了
• インタラクション：移動、スナップショット、待機、クリック、入力、キーの押下、スクロール、要素のスクロール
• 評価：evaluate と evaluate-extended
• ナビゲーション状態：戻る、進む、更新
• 抽出：リンク、スクリーンショット、統計情報、リソースの抽出、一括ダウンロード、Blob の解決
• ダウンロードの追跡：一覧表示／取得／内容取得／削除
• 表示モード：表示の切り替え

OpenClaw ルート（openclaw.ts）：

• /、/tabs/open、/start、/stop、/navigate、/snapshot、/act

付録 C — レスポンス処理の推奨事項

CLI 出力の処理：

• 機械的な解析には --format json を優先してください。
• スカラー値が 1 つだけ返される場合（直接のパスやステータス文字列など）のみ、plain を使用してください。
• 脆弱なシェル分割でテキスト出力を解析するのは避けてください。

API レスポンスの処理：

• 4xx エラーは、まずリクエスト／ユーザー／タブの不一致として対処してください。
• 既定では、冪等な読み取り（GET）のみを再試行してください。
• evaluate-extended では 429 と 408 を明示的に処理してください。

付録 D — 不一致と互換性に関するガードレール

このリポジトリのリビジョンで文書化されているガードレール：

• OpenClaw プラグインのツールシステムが存在し、主要機能として扱われています。
• このコードベースに MCP サーバーの実装は存在しません。
• camofox_youtube_transcript ツールは plugin.ts から削除されています。ルート POST /youtube/transcript は未登録のままです。
• CLI の download は引き続きプレースホルダー／スタブであり、機能しない直接ダウンロードコマンドとして扱ってください。

付録 E — 安全な自動化の最低限の契約

堅牢な自動化が必要な場合は、エージェントのロジックで次の契約を適用してください。

1. すべてのコマンド／呼び出しで、必ず明示的に userId（または --user）を渡してください。
2. ref に依存する操作の前に、必ずスナップショットを取得してください。
3. ナビゲーションまたは大幅な動的更新の後は、必ず ref を再取得してください。
4. 長時間稼働するシステムでは、終了処理時に必ずユーザーセッション（DELETE /sessions/:userId）を終了してください。
5. 認証情報／Cookie は、平文のスクリプトではなく、必ず Vault または Cookie のインポートを使って永続化してください。