cloakbrowser

CloakBrowser

パッチ適用済みソースの Chromium と、Playwright 互換の Python ラッパーです。フィンガープリントは C++ レベルで変更されるため（canvas、WebGL、audio、fonts、WebRTC、TLS、CDP input、navigator.webdriver、plugin list、window.chrome、…）、検出サービスには本物のブラウザーとして認識されます。実際に本物のブラウザーだからです。次の Chrome アップグレードで動かなくなる JS shim は使いません。

この VPS のインストール状態

インストール済みです。

• cloakbrowser CLI は、安定版 OpenClaw コンテナーイメージ内の /home/node/.local/bin/cloakbrowser にあります。
• ステルス Chromium バイナリーは、 /home/node/.cloakbrowser/chromium-<version>/chrome にあります。
• ラッパー Python は /usr/local/bin/cloakbrowser-python から利用できます。 同梱スクリプトはこの安定したラッパーを使用するため、Codex が HOME を 隔離されたセッションディレクトリーに設定している場合でも動作します。

新規チェックアウトや新しいマシンでセットアップが必要な場合：

uv tool install cloakbrowser
cloakbrowser install        # downloads the ~206 MB Chromium binary

cloakbrowser CLI が管理するのはバイナリー（install、info、update、 clear-cache）のみです。スクレイパーではありません。スクレイピングには、 このスキルのスクリプトを使うか、Python をインラインで記述してください。

判断フロー — 適切なツールを選ぶ

タスク	使用するもの
ページの HTML または表示テキストを取得する	scripts/fetch.py
ページまたは要素の PNG を保存する	scripts/screenshot.py
ページを PDF にレンダリングする	scripts/pdf.py
ページに対して JS 式を実行し、JSON を取得する	scripts/eval-js.py
ステルスが機能していることを確認する	scripts/check-stealth.py
複数のツール呼び出しやスキルで共有する、長時間稼働のブラウザー	scripts/serve.sh + CDP
複数ステップの対話フロー（ログイン、クリック、入力、条件判定）	インライン Python — 以下を参照

まずは常に同梱スクリプトを使ってください。argparse を使用し、 --humanize、--proxy、--geoip、--wait などを指定できるため、 ほとんどの用途に対応できます。

同梱スクリプト

すべてのスクリプトは実行可能です（#! は適切な Python を指しています）。 絶対パスで実行してください。

SK=/root/.openclaw/skills/cloakbrowser/scripts

$SK/fetch.py https://example.com                       # full HTML on stdout
$SK/fetch.py https://example.com --text                # visible text only
$SK/fetch.py https://example.com --selector "h1"       # scoped to a selector
$SK/fetch.py https://protected.example --humanize      # behavioural stealth
$SK/fetch.py https://geo.example --proxy socks5://u:p@host:1080 --geoip

$SK/screenshot.py https://example.com /tmp/out.png --full
$SK/screenshot.py https://example.com /tmp/hero.png --selector ".hero"
$SK/screenshot.py https://example.com /tmp/m.png --viewport 390x844

$SK/pdf.py https://example.com /tmp/page.pdf --format A4
$SK/pdf.py https://example.com /tmp/wide.pdf --landscape

$SK/eval-js.py https://news.example "Array.from(document.querySelectorAll('h2')).map(h=>h.innerText)"
$SK/eval-js.py https://example.com  "({ua: navigator.userAgent, w: innerWidth})"

$SK/check-stealth.py        # JSON report + exit 0 if all 4 stealth tells pass

$SK/serve.sh --port 9222    # starts cloakserve in background; logs /tmp/cloakserve.log

使い方は一貫しています。位置引数に URL（該当する場合は OUTPUT）を指定し、 続けて任意のフラグ --humanize、--proxy、--geoip、--wait、 --timeout を指定します。

インライン Python — スクリプトで対応できないすべての用途

複数ステップのフロー（ログイン、フォームへの入力、クリック操作、条件付きの待機） には、単発のスクリプトを作成してください。uv ツールの venv にある インタープリターを使用します。

CB_PY=/usr/local/bin/cloakbrowser-python

"$CB_PY" - <<'PY'
from cloakbrowser import launch
b = launch(headless=True, humanize=True)
p = b.new_page()
p.goto("https://example.com/login", wait_until="domcontentloaded")
p.fill("#email", "[email protected]")
p.fill("#password", "…")
p.click("button[type=submit]")
p.wait_for_url("**/dashboard**")
print(p.title())
b.close()
PY

API は Playwright の同期 API と同じです。Playwright のドキュメントにあるものは、 すべてここでも使えます。異なる点は次のとおりです。

• from playwright.sync_api ではなく from cloakbrowser import launch を使用します。
• sync_playwright().start() は不要です。launch() はトップレベル関数です。
• すべてのステルスフラグ（humanize、proxy、geoip、auto_update）は、 ページではなく launch() に渡します。

セッションを永続化するには、launch_persistent_context(user_data_dir) を使用してください。

references/stealth-knobs.md を読み込むタイミング

次の場合に読んでください。

• ステルスを使っていても対象サイトにブロックされる場合 （humanize／proxy／persistent profile の段階的な適用順序を説明しています）。
• ユーザーが proxy、residential と datacentre の違い、geo matching について質問した場合。
• 複数のツール呼び出しにわたって 1 つのブラウザーを共有する必要がある場合 （CDP サーバーモード）。

通常の「この URL を取得する」「このページのスクリーンショットを撮る」といった作業には、 上記の表とスクリプト例で十分です。リファレンスを読み込む必要はありません。

アンチパターン

• pip install cloakbrowser でシステム全体にインストールしないでください。この VPS では PEP 668 によってブロックされます。 uv tool install cloakbrowser を使用してください（インストール済みです）。
• playwright install を実行しないでください。CloakBrowser には独自の Chromium が付属しており、Playwright にバンドルされたバイナリは使用しません。
• システムの Python から cloakbrowser をインポートしないでください。これは uv ツールの venv 内にのみ存在します。venv の Python またはバンドルされたスクリプトを使用してください。
• 保護されていないサイトを通常どおりスクレイピングする際に、humanize=True を有効にしないでください。遅延が増えるだけで、メリットはありません。
• 1 回限りの取得で serve.sh を実行し続けないでください。CDP サーバーは、共有の長時間セッション用です。1 つの URL だけなら fetch.py のほうが高速です。

トラブルシューティング

• Binary not found／初回起動時にハングする → cloakbrowser install を実行してください。
• ModuleNotFoundError: cloakbrowser → 使用している Python が違います。/usr/local/bin/cloakbrowser-python またはバンドルされたスクリプトを使用してください（スクリプトの shebang はすでにそのパスを指しています）。
• 起動が遅い → バイナリは起動時に更新を確認します。更新確認を省略するには、launch() に auto_update=False を渡すか、CLOAKBROWSER_AUTO_UPDATE=0 を設定してください。
• それでもブロックされる → エスカレーションの順序については、references/stealth-knobs.md を参照してください（humanize → レジデンシャルプロキシ + geoip → 永続プロファイル）。