Playwright & Puppeteer

Clearcote の中身はあくまで Chromium なので、いま使っている自動化ツールのブラウザとしてそのまま差し替えて使えます。

SDK を使う方法（推奨）

clearcote パッケージ（npm、PyPI、NuGet）は、アイデンティティ関連のオプションを名前付き引数として受け取り、通常の Playwright オブジェクトを返します。初回利用時にはブラウザをダウンロードして SHA-256 で検証し（ライセンスキーがなければオープンビルド、あれば最新のライセンスビルド。インストールを参照）、後述のデフォルト設定を適用します。

# pip install clearcote
from clearcote import launch

browser = launch(fingerprint="seed-123", platform="windows", brand="Chrome")
page = browser.new_page()
page.goto("https://example.com")
browser.close()

現在の SDK：0.45.0。0.23 以降、Python と Node の launch() はシークレットモードではなく、実際の使い捨てプロファイルディレクトリ（終了時に削除）上で動作します。そのため、プロファイルに由来する特徴が実際の Chrome と一致し、widevine: true で DRM モジュールも読み込めます。返されるのはブラウザに似たハンドルで、newPage() はこれまでどおり使えますが、newContext() は分離されたコンテキストではなく、同じプロファイルのコンテキストを返します。Cookie を分けたい場合はブラウザを別々に起動してください。従来のシークレットモードの Browser が必要なら ephemeralProfile: false / ephemeral_profile=False を、プロファイルを残したいなら userDataDir / user_data_dir を渡します。

async API（clearcote.async_api）は、asyncio ループの中で同じペルソナ・プロキシのオプションを受け取り、Playwright の非同期オブジェクトを返します。こちらの launch() はシークレットモードなので、プロファイルを使う場合（および widevine=True を使う場合）は launch_persistent_context() を使ってください。.NET SDK が対応しているのは、LaunchEphemeralProfileAsync（推奨。.NET の LaunchAsync はシークレットモードで、ヘッドレスのウィンドウを画面に合わせられません）、LaunchPersistentContextAsync、ServeAsync、検証付きダウンロード、ライセンス処理、Geoip、人間らしい入力（起動フラグではなく、HumanClickAsync / HumanTypeAsync / HumanSelectOptionAsync を明示的に呼び出す方式）です。保存済みプロファイル、profile: "auto"、レンダリングの整合性チェック、Widevine、エージェント用ヘルパーは、現時点では Python と Node のみです。コピペで使える一連のワークフローはサンプルを参照してください。

Puppeteer などの CDP クライアント（`serve`）

SDK には Puppeteer 用のランチャーはありません。代わりに serve() が、SDK の起動設定（ペルソナ、プロキシ、デフォルト設定）で Clearcote を起動し、ループバック上に CDP エンドポイントを開きます。そこには Puppeteer、Playwright の connectOverCDP、browser-use、Crawl4AI、Stagehand など、任意の CDP クライアントが接続できます。ライセンスビルドでも動作し、--enable-automation はどこからも付与されません。humanize は Playwright 側の機能なので、この方法で接続したクライアントには適用されません。

import { serve } from "clearcote";
import puppeteer from "puppeteer-core";

const srv = await serve({ fingerprint: "seed-123", platform: "windows" });
const browser = await puppeteer.connect({ browserURL: srv.cdpUrl, defaultViewport: null });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.disconnect();
await srv.close();

ヘッドレスの場合、serve() はクライアントが接続する前に、ブラウザに実寸のディスプレイを与え、ウィンドウを作業領域に合わせます（0.31+）。ウィンドウを小さくしたい場合は windowSize / window_size を渡してください。シェルからは clearcote serve が同じことを常駐サービスとして行います。さらに、接続 URL から取ったアイデンティティ、プロキシ、タイムゾーン、言語で、接続ごとに専用のブラウザを割り当てることもできます。デプロイを参照してください。

バイナリを直接操作する（オープンビルド）

自前のランチャーで executablePath（Node）または executable_path（Python）をオープンビルドに向け、アイデンティティのオプションを args として渡すこともできます。ライセンスビルドはこの方法では起動しません。SDK が取得するライセンストークンが必要なので、前述の launch() か serve() を使ってください。--enable-automation は SDK と同じように外してください（Puppeteer や古いバージョンの Playwright はこれを付与し、Chromium を自動化モードに切り替えてしまいます）。この方法では、SDK のデフォルト設定（言語、WebRTC ポリシー、ウィンドウのジオメトリ）は一切適用されません。

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=r"C:\clearcote\chrome.exe",
        headless=False,
        ignore_default_args=["--enable-automation"],
        args=[
            "--fingerprint=seed-123",
            "--fingerprint-platform=windows",
            "--timezone=America/New_York",
        ],
    )
    page = browser.new_page()
    page.goto("https://abrahamjuliot.github.io/creepjs/")
    browser.close()

検証済みバイナリの解決とプリフェッチ

SDK は次の順でブラウザを決定します。明示的に指定した executablePath / executable_path、次に CLEARCOTE_BINARY、次に指定した version（または CLEARCOTE_BROWSER_VERSION）、次にライセンスキーが見つかればライセンスビルド（licenseKey オプション、CLEARCOTE_LICENSE_KEY、~/.clearcote/license.key）、最後にこの SDK バージョンで固定されたオープンビルドです。指定したパスは、起動前にファイルの欠落や途中で切れたファイルがないかチェックされます。起動せずにキャッシュを温めておきたい場合、独自のキャッシュディレクトリを使いたい場合、または実行時に GitHub 上の最新のオープンビルドを使うようにしたい場合は、download / executable_path を呼び出してください。

from clearcote import download, launch

chrome = download(cache_dir=r"C:\clearcote-cache", auto_update=True)
browser = launch(executable_path=chrome, fingerprint="seed-123")

固定モードでは、SDK に組み込まれた SHA-256 値で検証します。autoUpdate / auto_update はオプトインで、リリースのチェックサムマニフェストを検証します。gpg が使える場合は、署名済みマニフェストを、固定された Clearcote 署名鍵のフィンガープリントとも照合します。これはオープンビルドにのみ適用されます。ライセンスキーがある場合、download() は代わりに現行のライセンスビルドを取得します（ビルドは version または releaseChannel で選べます。ビルドの選び方を参照）。.NET の DownloadAsync が取得するのはオープンビルドのみです。ライセンスビルドをプリフェッチするには ExecutablePathAsync(new LaunchOptions { LicenseKey = … }) を使います。

デフォルトで整合性を保つ（追加フラグ不要）

どのオプションで起動しても、エンジンは二次的なサーフェスを、選んだペルソナと一致させます。Windows ペルソナなら、実際の Windows 版 Chrome のデスクトップ環境が返す値に合わせます。ペルソナのプラットフォームはデフォルトでホスト OS になるため、Linux ホストでは platform を指定しない限り、これらは Linux ペルソナに従います。WebGL の getParameter で得られる上限値（WebGL1 + WebGL2）はペルソナの値になります。ただし、このマシンの GPU が実際に対応できる範囲に制限されます。UNMASKED_RENDERER / UNMASKED_VENDOR はセッション中一定です（ペルソナに従い、どのサイトでも同じ GPU）。Windows ペルソナでは、navigator.getBattery() は AC 電源で動くデスクトップを、navigator.connection は家庭用の回線を、AudioContext はそれに見合った Windows WASAPI のサンプルレートとレイテンシを返します。getScreenDetails() はモニター 1 台を返し、@media (pointer: fine) / (hover: hover) はマウスを使うデスクトップと一致します。

153 r26 を Windows 上の headed モードで確認した結果（2026 年 9 月）：BrowserScan の判定は「ボットではない」、CreepJS の stealth は 0% でした。プロキシ経由の場合は geoip を追加して、タイムゾーンと WebRTC を出口に合わせてください。

整合性のあるデフォルト設定（上書き可能）

SDK は、わかりやすい手がかりが漏れないよう、ステルスの観点で正しいデフォルト設定をいくつか適用します。

headed での起動では、デフォルトでビューポートをエミュレートしません（viewport: null / no_viewport=True）。そのため window.innerWidth は実際の OS ウィンドウに追従します。実際のウィンドウの上にエミュレートした 1280×720 が載っていると、ありえないウィンドウ構成という手がかりになります。上書きするには viewport を明示的に指定してください。ウィンドウマネージャーのない Linux サーバー（Xvfb や自前のコンテナ）では --start-maximized が効きません。そうした環境では、headed のウィンドウは最初のページの前に、最大化したデスクトップのウィンドウと同じように画面の作業領域に合わせられます（SDK 0.42.0）。
ヘッドレスでの起動では、最初のページの前に、現実的なディスプレイと、それに合わせたウィンドウが割り当てられます。ペルソナがあればペルソナの画面、なければ実際のデスクトップのサイズです。SDK 0.42.0 以降は、ペルソナが適用されない場合でもすべてのプラットフォームでこれが保たれるため、エンジンそのままの 800×600 のヘッドレスサーフェスがページから見えることはありません。viewport や screen オプションを自分で指定するとこの動作はオフになり、--screen-info を自分で指定するとディスプレイを自分で設定することになります。--window-size、--window-position、--start-maximized を自分で指定した場合は、ディスプレイはそのままで、ウィンドウを合わせる処理だけが省かれます。serve() では --window-position だけを指定した場合もディスプレイは保たれ、ジオメトリを完全に自分で管理することになるのは、サイズを指定するスイッチか --screen-info を指定した場合だけです。
Linux では WebGL のサーフェスが 1 つになります。Linux ホストでは、Linux ペルソナの WebGL はヘッドレスでも headed でも EGL 経由の Mesa で描画されます（SDK 0.42.0。ホストに libegl1 が必要です）。そのため、どちらのモードでも、ページから見えるレンダラー文字列、拡張機能の一覧、上限値は 1 通りで、実際の Linux マシンの多くが報告する OpenGL ES の形式になります。EGL がない場合、headed の起動では Mesa のデスクトップ GL を使います。また、Windows ペルソナは SwiftShader で描画されます。args に自分で指定した --use-angle や --use-gl が優先されますが、その場合もヘッドレスの起動には --ignore-gpu-blocklist が付くため、WebGL は引き続き動作します。
154 r32 以降のライセンスビルドでは、ライトかダークかはペルソナが決めます。Playwright は通常ライトを強制しますが、SDK が作成するコンテキストでは Playwright のカラースキームのエミュレーションをオフのままにします（SDK 0.41.0+）。それでもエミュレートしたい場合は colorScheme / color_scheme を渡してください。
154 r32 以降のライセンスビルドでは、ペルソナはコマンドラインに載りません。シード、ペルソナの上書き、プロキシの認証情報は、プロセス一覧の項目ではなく環境変数経由でブラウザに渡されます（SDK 0.41.0+。コマンドラインに残すには personaEnv: false）。起動オプションを参照してください。
WebRTC のデフォルトは disable_non_proxied_udp です。プロキシを通らない UDP は送信されず、マシン自身のアドレスは外に出ません。これを上書きするのは、args に自分で指定した --webrtc-ip-handling-policy だけです。ただしオープンビルドでは webrtcIp / geoip も上書きし、WebRTC の UDP が再び自分の回線から送信されるようになります（ライセンスビルドはどの場合も WebRTC の UDP をブロックします）。このポリシーで webrtcIp がない場合、ページは ICE 候補をまったく取得できません。プロキシ経由なら、geoip（または webrtcIp）を渡して WebRTC がプロキシのアドレスを報告するようにするか、socks5Udp で実際の UDP を SOCKS5 プロキシ経由で流してください。
プロキシ経由では QUIC / HTTP-3 はオフです。プロキシ経由の実際の Chrome と同じで、プロキシを通らない UDP は試行されません。
ペルソナのプラットフォームはデフォルトでホスト OS、ブランドは Google Chrome です。timezone も geoip もない場合、タイムゾーンは言語に従います（en-US → ニューヨーク）。
エンジンが対応している場合、プロキシの認証情報は Playwright ではなくブラウザに渡されます。SOCKS5 では常に（Playwright は SOCKS5 の認証にまったく対応していません）、HTTP(S) では 151 r19+ でブラウザに渡され、ページキャッシュが有効のまま保たれます（Python & Node）。詳しくは後述します。
humanize は、trusted クリックの前に毎回操作可能性の事前チェック（表示されているか / 有効か / 安定しているか + elementFromPoint による被覆チェック）を行い、必要に応じてネイティブのクリックにフォールバックします。そのため、trusted クリックがオーバーレイの下やアニメーションの途中で発火することはありません。

ヒント：シードを自分のアカウント ID やテナント ID から導出すれば、各アイデンティティを再現できます。同じシードなら、いつでも同じブラウザフィンガープリントになります。スイッチの一覧はフィンガープリントフラグを参照してください。