本文へスキップ

インストール

SDK をインストールして検証済みのブラウザを取得させるか、ビルドを自分でダウンロードして検証します。

Clearcote は現在も活発に開発中です。ビルドは Windows x64 版と Linux x64 版を提供しており、SDK は OS に合ったほうをダウンロードします。Apple Silicon の Mac ではブラウザがネイティブで動作します（ライセンスビルドはプレビューとして、ライセンスキーがない場合はオープンな 150 ビルド）。Intel Mac の場合は、launch() が Clearcote の Docker イメージを自動で実行します（macOS を参照）。最小構成の Linux ホストでは、ブラウザのランタイムライブラリ（libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …）をインストールしてください。不足しているものは clearcote info で一覧表示できます。自分でバイナリを root として起動する場合（コンテナではよくあるケース）は --no-sandbox を渡してください。SDK と clearcote serve はこれを自動で処理します。

新登場最新ビルドは、GitHub、カード確認、または会社の Google アカウントがあれば、ブラウザ 1 つまで 無料 です。請求は一切ありません。

無料で入手
bash
npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

最初の launch() で OS に合ったブラウザがダウンロードされ、SHA-256 を確認したうえでキャッシュされます。playwright install を実行する必要はありません。各 SDK は自前の Playwright ドライバーを同梱し、ブラウザも自分で取得します。どのビルドが使われるかは、ライセンスキーを設定しているかどうかで決まります。

ビルド取得元
キーなしオープンビルド — Chromium 151.0.7922.108（v0.1.0-pre.25）。BSD-3 ライセンスで、公開ソースから再現できます。GitHub Releases（SDK のバージョンで固定）
キーありライセンスビルド — Chromium 156.0.8078.47-r57。GitHub で無料（同時に 1 ブラウザまで）、または Pro。clearcotelabs.com（起動のたびに現行のビルド）

ライセンスキーを設定する

SDK は次の順にキーを探します。まず起動オプションの licenseKey / license_key / LicenseKey、次に環境変数 CLEARCOTE_LICENSE_KEY、その次に clearcote login が書き込むファイル ~/.clearcote/license.key です。このファイルは .NET を含むすべての SDK が読み込みます。無料のキーは、ダッシュボードの「Licenses」から取得できます。

bash
clearcote login --device                # sign in from a browser on any device; nothing to paste
clearcote login                         # asks for the key; what you paste is not shown
clearcote login cc_lic_...              # for scripts: checks the key, saves it to ~/.clearcote/license.key
export CLEARCOTE_LICENSE_KEY=cc_lic_...  # or per process / per container

別のデバイスからサインインする

clearcote login --device（SDK 0.40.0+、Python と Node。npm でローカルにインストールした場合は npx clearcote login --device）を使うと、キーを自分でコピーしなくても保存できます。コマンドはリンクと短いコードを表示します。clearcotelabs.com にサインインできる任意のデバイスのブラウザでそのリンクを開き、ページに表示されたコードがターミナルのものと同じであることを確かめ、そのターミナルが自分のものであることを確認するチェックボックスをオンにして、承認します。ページにはデバイスがサインインしたことが表示され、ターミナルには Signed in as に続いてアカウントのメールアドレス（一部を伏せた形）、キーの保存先、プランと有効期限が表示されます。キーそのものは、ページにもターミナルにも表示されません。

コードの有効期間は 10 分です。期限が切れたら、コマンドをもう一度実行して新しいコードを取得してください。待機中に Ctrl-C を押すと何も保存されず、もう一度 Ctrl-C を押すとすぐに終了します。--device は、SSH で接続するサーバー上やコンテナ内で使うとき、またはコーディングエージェントに Clearcote をセットアップさせるときに使ってください。承認は自分のブラウザで行われ、秘密情報がターミナルやその履歴、チャットを通ることはありません。自分のマシンでキーが手元にあるなら、clearcote login でも十分です。0.40.0 以降は、キーを画面に表示せずに読み取ります。

clearcote コマンド

Python と Node のパッケージは clearcote コマンドをインストールします（npm でローカルにインストールした場合は npx clearcote … として実行します）。.NET のパッケージには含まれていません。

bash
clearcote install              # download + verify the browser now (CI, Docker builds)
clearcote info                 # this machine, SDK, key, cached builds, seats in use, a launch test, missing libraries
clearcote info --proxy <url>   # the exit IP, timezone and language a launch through this proxy would get
clearcote bench --proxy <url>  # what each browser costs here in CPU and RAM, page timings, how many fit at once
clearcote update               # fetch a newer build if one exists (newest open build, or current licensed)
clearcote clear-cache          # delete cached builds — old ones are kept until you do
clearcote login [key]          # clearcote logout removes the saved key
clearcote serve                # a standing CDP endpoint — see Deployment
clearcote connect [code]       # start the helper for the web Profile Manager — see below

どのコマンドも --help を受け付けます。SDK 0.40.0 以降、clearcote info は launch() が実行するビルド（CLEARCOTE_BROWSER_VERSION で指定したビルドを含む）をテストし、キーを clearcote login --device で保存した場合はその有効期限も表示します（貼り付けたキーの有効期限は、どのライセンスサービスからも通知されません）。0.41.0 以降は Linux で、起動時にブラウザから見えるフォントがどの文字体系を描画できるかも報告します（Linux で独自のフォントを使うを参照）。clearcote install --version 154 や --channel preview で特定のビルドを選べます。詳しくはビルドの選び方を参照してください。次は Playwright または Puppeteer に組み込みます。

0.56.0 以降、clearcote info はマシン自体の情報（プロセッサ、メモリ、OS、仮想マシンやコンテナかどうか、ブラウザが描画に使えるグラフィックカードがあるか）から表示します。clearcote bench は --concurrency 個のブラウザ（既定 3）を起動して --url を --duration 秒間（既定 30）読み込み（--proxy を指定した場合はそのプロキシ経由）、このマシンでブラウザ 1 つあたりにかかる CPU スレッドと RAM、読み込み時間、エラー、同時に動かせるおおよそのブラウザ数、そして何を変えるべきかを報告します。空きメモリが足りなそうなときは起動するブラウザを減らし（--force ですべて起動）、各ブラウザは実行中にライセンスの枠を 1 つ使います。出力はサポートへの問い合わせにそのまま貼り付けてください。.NET では ClearcoteBench.RunAsync と ClearcoteHost.Info がコードから同じレポートを返します。

0.61.0 以降、clearcote connect はそのターミナルで Clearcote Helper を起動します。これで app.clearcotelabs.com のWeb 版 Profile Managerから、このコンピューターで プロファイルを起動できます。Connect ウィンドウで I use the Clearcote SDK を選び、表示される ワンタイムコード付きのコマンド（npx clearcote connect 4F7-K2Q）を実行すると、そのタブは承認ページなしで 自動的に接続されます。初回は SDK が固定している Helper のリリースをダウンロードし、SHA-256 を確認します。 ターミナルは開いたままにしてください。Ctrl+C で Helper とそのブラウザが終了します。

macOS

ライセンスキーがある Apple Silicon の Mac（M1 以降、macOS 13 以降）では、SDK（0.51.1+）がライセンス版の macOS ビルドをダウンロードし、Windows や Linux と同じようにネイティブで起動します。これはプレビューで、Windows と Linux より遅れることがあります。現在、macOS は 155.0.8059.39-r49 で、Windows と Linux は 156.0.8078.47-r57 です。ライセンスキーがない場合は、SDK（0.68.4+）が Apple Silicon 向けのオープンな 150 ビルド（v0.1.0-pre.24。オープンな Windows 版・Linux 版より Chromium のバージョンが 1 つ古いビルドです）をダウンロードし、同じくネイティブで起動します。

Intel Mac の場合（および SDK 0.40.0 から 0.68.3 では、ライセンスキーのないすべての Mac）は、launch() を呼ぶと Clearcote の Docker イメージ（teamflatearth/clearcote:sdk-<SDK version>。Docker Desktop が Intel と Apple シリコンのどちらでも実行できる linux/amd64 イメージです）が起動し、SDK はそこに接続して、ローカルで起動したときと同じ Playwright ブラウザを返します。コードを変える必要はなく、close() でコンテナが停止・削除されます。対象は Python（同期・非同期）、Node、.NET（LaunchAsync）の launch() です。永続コンテキストや serve() などのほかのエントリーポイントには引き続き Clearcote のバイナリが必要なため、Mac ではそれらを Docker イメージの中で直接実行してください。

from clearcote import launch

browser = launch(fingerprint="acct-1")   # on macOS: runs teamflatearth/clearcote:sdk-<version>
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()                          # stops and removes the container
  • Docker Desktop がインストールされ、起動している必要があります。そうでない場合、launch() は対処方法を示す DockerUnavailableError（.NET では DockerUnavailableException）を送出します。初回の起動ではイメージをダウンロードし、ライセンスキーがあれば最新ビルドも clearcote-cache ボリュームに一度だけダウンロードします。次回以降の起動は数秒で始まります。
  • コンテナに渡されるもの：ペルソナのオプション、headless、proxy、args、version、ライセンスキー（ほかのマシンと同じ方法で探され、clearcote login で保存したキーも含みます）。コンテナが受け付けられないオプションは、名前を示して拒否されます。キーとプロキシは、コンテナが一度だけ読み込んで削除するファイルとして渡されるため、docker inspect には表示されません。また、キーやプロキシを指定した起動は、コンテナがライセンスビルドを実行していない場合やそのプロキシを使っていない場合には拒否されます。
  • 何も動いたまま残りません。プログラムが close() を呼ばずに終了したり強制終了されたりしても、そのコンテナは接続がなくなってから約 30 秒後に自動で停止します。また、次回の起動時に、元のプログラムがもう存在しない残りのコンテナが削除されます。実行中のほかのプログラム、ほかのユーザー、ほかのマシンに属するコンテナには一切手を触れません。SDK 0.41.0 以降、close() は Docker がコンテナとそのボリュームを削除し終えてから戻るため、その後 docker ps -a に表示されることはありません。
  • Chrome はサンドボックスを維持します（SDK 0.41.0+ と sdk-0.41.0 以降のイメージ）。起動時にイメージの seccomp プロファイルを渡すため、Chrome はコンテナ内でサンドボックスありで動作します（Chrome のサンドボックスを参照）。これには x86_64 CPU 上の Docker が必要です。Apple シリコンではイメージがエミュレーションで動作するため、現時点ではサンドボックスはオフのままです。
  • コンテナでは Linux が動作します。そのため、デフォルトのペルソナは Linux のものです。コンテナから別のプラットフォームを名乗る前に、デプロイを読んでください。
設定動作
docker=False（Node では docker: false、.NET では Docker = false）または CLEARCOTE_DOCKER=0Docker を使いません。その場合 macOS では、互換性のある Clearcote バイナリを executable_path で自分で指定します。
docker=True または CLEARCOTE_DOCKER=1Docker が使えるすべての OS で Docker イメージを使います。
docker_image=（Node では dockerImage、.NET では DockerImage）または CLEARCOTE_DOCKER_IMAGE別のイメージやタグを実行します。たとえば teamflatearth/clearcote:sdk-0.46.0 に固定する場合に使います。sdk-0.40.0 より古いイメージも警告付きで動作しますが、キーとプロキシは docker inspect で見える変数として渡され、プログラムが異常終了してもコンテナは自動で停止しません。
CLEARCOTE_DOCKER_IDLE_EXIT放置されたコンテナが停止するまでに待つ秒数（デフォルトは 30、0 = 停止しない）。
CLEARCOTE_DOCKER_CACHE_VOLUMEライセンスビルドを保存するボリューム（デフォルトは clearcote-cache）。

イメージは SDK のリリースから数分後に公開されるため、アップグレードの直後には対応するタグがまだ存在しないことがあります。その場合はエラーでそのことが示されます。それまでの間は、CLEARCOTE_DOCKER_IMAGE で以前のタグを指定できます。

手動インストール（オープンビルド）

バイナリを直接使いたい場合は、GitHub Releases にオープンビルドがあります。ライセンスビルドはそこでは公開していません。ライセンスビルドは SDK、clearcote serve、Docker イメージのいずれかを通じて動作し、SDK が用意する実行トークンがなければ起動しません。

1. ダウンロード

最新の v0.1.0-pre.* リリースをダウンロードしてください。現在の最新は v0.1.0-pre.25（Chromium 151.0.7922.108）です。各リリースには次のファイルが含まれます。

  • clearcote-<version>-windows-x64.zip — Windows 版ビルド（Chromium + ランタイム + VC++ DLL）
  • clearcote-<version>-linux-x64.tar.xz — Linux 版ビルド
  • .sha256 ファイルと SHA256SUMS.txt — チェックサム
  • .asc ファイル + clearcote-signing-key.asc — GPG の分離署名と公開鍵

オープンビルドは、私たちを信頼しなくても済むように作られています。展開する前に、ダウンロードしたものがビルド・署名されたものと完全に一致することを確認してください。手順は検証のページにあります。

3. 展開する

Windows 版のアーカイブはそれだけで完結しています。VC++ 2015–2022 のランタイム DLL を同梱しているため、クリーンな Windows 10/11 マシンでそのまま動作します。Linux 版のアーカイブには、上に挙げたランタイムライブラリが必要です。

Expand-Archive clearcote-151.0.7922.108-windows-x64.zip -DestinationPath C:\clearcote

# you now have:
#   C:\clearcote\chrome.exe
#   C:\clearcote\chrome.dll  + runtime, locales, ICU, ANGLE, VC++ DLLs

4. スモークテスト

シードを指定して起動し、フィンガープリントテストのページを開きます。

C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows https://abrahamjuliot.github.io/creepjs/

--fingerprint のシードが同じなら、起動するたびに同じアイデンティティになります。新しいシードなら新しいアイデンティティです。シードから導出した値ではなく実機から取得した値を返したい場合は、取得済みのプロファイルをインポートします（フィンガープリントフラグを参照）。そのあと Playwright または Puppeteer に組み込みます。

Docker で実行する

公式イメージは Clearcote を CDP エンドポイントとして実行します。イメージを pull し、Playwright、Puppeteer、browser-use などのクライアントを Chrome DevTools Protocol 経由でそこへ向けるだけで、コードの変更は要りません。

bash
# Chrome's sandbox profile, shipped in the image
docker run --rm --tmpfs /opt/xdg-cache --entrypoint cat teamflatearth/clearcote /etc/clearcote/seccomp.json > clearcote-seccomp.json
docker run -d --rm --shm-size=1g -p 127.0.0.1:9222:9222 --security-opt seccomp=clearcote-seccomp.json -e CC_FINGERPRINT=user-7423 teamflatearth/clearcote   # CDP on http://localhost:9222
python
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://localhost:9222")   # your code, unchanged
    page = browser.new_page(); page.goto("https://example.com")

ペルソナは環境変数で設定します。CC_PLATFORM（windows/linux/macos/android）、CC_FINGERPRINT（シード）、CC_BRAND（Edge など）、CC_ACCEPT_LANGUAGE、CC_TIMEZONE、CC_TLS_PROFILE です。CC_FINGERPRINT を設定しないと、コンテナごとにランダムなシードが割り当てられ、再起動後も維持されます。アイデンティティを選んだり再利用したりするには、この変数を設定します。イメージに入っているのはオープンビルドです。最新のライセンスビルドを使うには -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache を追加します。ビルドはボリュームに一度だけダウンロードされます。ブラウザは仮想ディスプレイ上で headed モードで動作し（純粋なヘッドレスにするには CC_HEADLESS=1）、イメージは linux/amd64 です。Dockerfile は監査可能なので、自分で再ビルドしてみてください。CDP エンドポイントはブラウザを完全に制御できるため、信頼できるネットワークにだけ公開してください（-p 127.0.0.1:9222:9222 ならホスト内に限定されます）。詳しくはデプロイを参照してください。

ダウンロード制限

ライセンス版ビルドのダウンロードにはライセンスごとの回数制限があり、起動のたびにアーカイブ全体を取得する構成が 暴走しないようになっています。キャッシュにビルドがある起動は何もダウンロードせず、回数にも数えられません。 数えるのは実際のダウンロードだけです。

制限対象数えるもの
20 回のダウンロード / 分、30 回 / 24 時間すべてのライセンス、ビルドごと（バージョン + OS）同じビルドのアーカイブのダウンロード。新しいリリースでは枠がリセットされます。
10 種類のビルド / 24 時間無料ライセンス取得した異なるビルドの数。今日すでにダウンロードしたビルドは再度数えられません。
60 回のチェック / 分IP アドレスごと起動のたびに /api/v1/download/pro へ行うビルドのチェック（キャッシュの有無を問わず）。

制限を超えると、SDK は JSON 本文付きの HTTP 429 を受け取ります。code は DOWNLOAD_RATE_LIMITED（ビルドごとの枠）または DOWNLOAD_LIMIT_EXCEEDED（無料プラン）で、 制限がリセットされるまでの秒数を示す Retry-After ヘッダーが付きます。ビルドがキャッシュ済みの起動はそのまま動きます。 SDK 0.62.0 以降、新しいビルドをダウンロードできない起動は、失敗する代わりにキャッシュにある同じ Chromium バージョンの最新ビルドを起動し、Retry-After が過ぎるまでそのダウンロードを再試行しません。 正確なリビジョン（r50）に固定した起動は、引き続きそのビルドかエラーになります。

これらの制限に当たるのは、空のキャッシュを持つ新しいマシンやコンテナが一斉に多数起動するときです。起動ごとでは なくマシンごとに一度だけ各ビルドをダウンロードしましょう。約 460 MB のダウンロードがなくなり、起動も速くなります。

  • キャッシュをボリュームに置く。CLEARCOTE_CACHE を再起動後も残るディレクトリに 向けます。それを共有する起動は最初のダウンロードを待ち、それを再利用します。
  • ブラウザをイメージに焼き込む。ビルド時に clearcote install を実行すれば、どの コンテナもビルドが入った状態で起動します。アップグレード時はイメージを作り直してください。
bash
# 1. a shared, persistent cache
docker run -v clearcote-cache:/clearcote-cache -e CLEARCOTE_CACHE=/clearcote-cache …

# 2. or in your Dockerfile: download once while the image is built (the key stays out of the layers)
ENV CLEARCOTE_CACHE=/opt/clearcote-cache
RUN --mount=type=secret,id=clearcote_key \
    CLEARCOTE_LICENSE_KEY="$(cat /run/secrets/clearcote_key)" clearcote install

Need a higher limit? Tell us how you run Clearcote and we'll raise it for your licence.

Chat with us

ペルソナの上限

起動のたびに、ペルソナ（シードとオプションが表すフィンガープリント）をペルソナサービスから取得します。ライセンスごとに、1 日に取得できる異なるペルソナの数が決まっています。その日にすでに使ったペルソナの再取得はカウントされないため、決まったプロファイルの組み合わせなら何度でも再起動できます。

プラン1 日あたりの異なるペルソナ数
無料750
Pro とその他の有料プラン1,000,000

ペルソナは、1 つのシードと 1 組のフィンガープリントオプション（ブランド、プラットフォームなど）の組み合わせです。そのため、同じシードでも Chrome と Edge では 2 つと数えます。カウントは 00:00 UTC にリセットされます。上限を超えると、リセットまでの間、起動はペルソナサービスからの HTTP 429（daily persona quota reached）で失敗します。

この上限に当たるのは、起動のたびにまったく新しいランダムなシードを使う場合です。代わりに、決まったシードのプールを再利用してください。たとえば数百個の名前のリストを順番に使います。どのシードも起動するたびに同じフィンガープリントを保ち、再起動してもカウントは増えません。

動作要件

  • Windows 10 / 11 x64、または上記のランタイムライブラリを入れた Linux x64（glibc）。
  • macOS：Apple Silicon（macOS 13+）では追加のものは不要です（ライセンスキーありは SDK 0.51.1+、なしは 0.68.4+）。Intel Mac の場合は、launch() には Docker Desktop が起動している必要があります（SDK 0.40.0+）。
  • Windows では VC++ 再頒布可能パッケージを別途入れる必要はありません。アーカイブに同梱されています。
  • SDK：Node 20+、Python 3.8+、または .NET 8。それぞれ専用の Playwright ドライバー（playwright-core、playwright、Microsoft.Playwright）を取り込みます。
  • オープンビルドのバイナリを直接使う場合：既存の Playwright または Puppeteer のインストール（Clearcote が置き換えるのはブラウザで、ドライバーではありません）。