本文へスキップ

サンプル

Clearcote のよくあるワークフローを、コピー＆ペーストでそのまま使えるレシピにまとめました。まずは目的に合う最小のレシピから始め、オプションは必要になったときにだけ追加してください。

レシピは Python、Node、.NET の各 SDK 向けに掲載しています（pip install clearcote / npm install clearcote / dotnet add package Clearcote）。.NET SDK が対応するのは主要なワークフローで、launch、永続コンテキスト、serve、プロキシ、geoip（Geoip = true）、Canvas ブリッジを利用できます。ただし、人間らしい入力は launch フラグではなく、HumanClickAsync / HumanTypeAsync を明示的に呼び出して行います。保存済みプロファイル、Widevine、ブラウザ内エージェントは、現時点では Python & Node のみの対応です。

ライセンスキーが設定されていなければ、どのレシピもオープンビルドで動作します。キーを設定すると（clearcote login、CLEARCOTE_LICENSE_KEY、または license_key=）、同じコードで最新のライセンスビルドが動作します。「GitHub で無料」では、同時に実行できるブラウザは 1 つです。意外に思われやすい点が 1 つあります。エンジンはコンソールイベントやページエラーイベントを一切転送しないため、page.on("console") には仕様上何も届きません。出力はページ内で収集し、page.evaluate() で読み出してください。

1. SDK から検証済みのブラウザを起動する

SDK は初回使用時にブラウザをダウンロードし、SHA-256 で検証します。デフォルトではオープンビルド、キーが設定されていれば最新のライセンスビルドです。返されるのは通常の Playwright オブジェクトなので、それ以降の自動化コードは使い慣れた書き方のままです。（0.23 以降、同期版 Python と Node の launch() は使い捨てのプロファイル上で動作し、new_context() はその同じプロファイルを返します。分離されたコンテキストが必要な場合は ephemeral_profile=False / ephemeralProfile: false を渡してください。）

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. どのフレームワークからも使えるステルス CDP エンドポイントを提供する

serve() は Clearcote を常駐型の CDP エンドポイントとして起動し、cdp_url を返します。バイナリを直接起動するため（--enable-automation は付きません）、Playwright、Puppeteer、browser-use、Crawl4AI、Stagehand のどのクライアントからも、コードを変更せずに CDP で接続できます。serve で提供されるプロファイルを使うには、contexts[0] でページを開いてください。ブラウザに対して new_page() を呼ぶと、別の分離されたコンテキストが作成されます。AI エージェントから使う場合は、Claude / Cursor / Cline の接続先を clearcote-mcp サーバーに設定します（pip install clearcote-mcp または npx -y clearcote-mcp。Python 3.10 以降が必要です）。シェルからは clearcote serve で同じエンドポイントを起動でき、接続ごとに別々のアイデンティティを割り当てることもできます。詳しくはデプロイを参照してください。

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. アカウントごとに安定したアイデンティティを 1 つ

決定的なシードと、永続的なユーザーデータディレクトリを使います。シードはブラウザのアイデンティティを安定させ、プロファイルディレクトリは Cookie、ローカルストレージ、権限、セッション状態を保持します。

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. タイムゾーン、言語、位置情報、WebRTC をプロキシに合わせる

geoip を有効にすると、Clearcote はプロキシ経由でそのプロキシの出口 IP を調べ、未設定のタイムゾーン、言語、位置情報、WebRTC アドレスを GeoIP データベース（初回使用時にダウンロード、約 50 MB）から補完します。プロキシごとにタイムゾーンを手作業で合わせる必要はありません。CLEARCOTE_GEOIP_TIMEOUT_SECONDS（デフォルト 20）以内に地域を特定できない場合は、このマシンの時計と言語のまま起動するのではなく、GeoipError で起動を中止します。それでも起動したい場合は、timezone と accept_language の両方を設定してください。.NET では Geoip = true を設定します。

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. 名前付きプロファイルを保存して再利用する

保存した Profile は、複数のスクリプトで共有できる名前付きのペルソナが欲しいときに便利です。プロファイルファイルは平文なので、秘密情報はソース管理に含めないでください。

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Canvas ブリッジは必要な場所でだけ使う

ブリッジモードは、登録可能ドメイン（registrable domain）単位で適用範囲を絞れます。次の例では、列挙したオリジンでのみ canvas/WebGL の読み取りをブリッジし、それ以外ではローカルでレンダリングします。GPU 文字列はレンダリングに使う GPU のもの（ブリッジサーバーが表示するレンダラー）に設定し、報告される GPU とブリッジされたピクセルが一致するようにしてください。ブリッジを有効にすると、レンダラーは Chromium のサンドボックスなしで動作します（モードにかかわらず、SDK がブラウザ全体に --no-sandbox を付加します）。そのため、ブリッジは必要なセッションでのみ有効にしてください。

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

先にブリッジホストを起動しておいてください。サーバーの起動コマンド、ネットワーク構成の指針、フォールバック時の動作については「Canvas ブリッジ」を参照してください。

7. Widevine で DRM 動画を再生する

Clearcote には EME の仕組みは含まれていますが、Google のプロプライエタリな CDM は一切同梱していません。widevine を指定すると、Google のコンポーネントサーバーから Widevine CDM を一度だけ取得して検証し、プロファイルに配置して有効化します。これにより、本物の Chrome と同じように requestMediaKeySystemAccess('com.widevine.alpha') が resolve され、DRM ストリームが再生されます。

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

意図的にオプトイン方式にしています。パッケージが Google の CDM を配布することはなく、1 回限りの取得を実行するのはユーザー自身です（取得したものは ~/.clearcote/WidevineCdm にキャッシュされます）。同期版 Python の launch() と launch_persistent_context() で使えます。Node では上記のように launchPersistentContext() を使ってください（launch() の TypeScript 型にはまだ widevine が宣言されていません）。シークレットモードで動作する Python の非同期版 launch() と、.NET では使えません。セキュリティレベルはソフトウェアベース（L3）です。Google Chrome を名乗りながら Widevine の問い合わせに応答できないブラウザであることは、どのページからでも読み取れます。これが有効にする理由です。詳しくは Widevine & DRM を参照してください。

8. CI でブラウザを事前取得する

テストスイートを開始する前に、検証済みブラウザのキャッシュを用意しておきます。こうすると、並列ジョブが始まる前の早い段階で失敗が表面化します。キーがなければオープンビルドを、CLEARCOTE_LICENSE_KEY が設定されていればライセンスビルドを取得します。「GitHub で無料」のキーでは同時に 1 つのブラウザしか実行できないため、ブラウザテストを直列に実行するか、Pro を使ってください。

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. エージェントタスクを実行してトレースを残す

ブラウザ内エージェントはオプトインです。実行を再現・検証できるよう、永続的なプロファイルディレクトリ、OpenAI 互換のエンドポイントとキー、上限を設けたステップ数を指定してください。

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. SDK を使わない場合の素の Playwright

SDK を使うのが手軽ですが、オープンビルドは通常の Chromium バイナリなので、Playwright や Puppeteer から直接起動できます。ライセンスビルドには SDK が必要です。エンジンが起動時に確認するライセンストークンを SDK が保持しているためです。以下の追加引数は、SDK を使えば自動で付けてくれるデフォルト値です。

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
まずはレシピを小さく保ってください。プロファイルのインポート、Canvas ブリッジ、エージェントモード、GPU の手動上書きは、対象のワークフローで本当に必要になったときにだけ追加しましょう。