本文へスキップ

起動オプション

ほかのページで扱っていない起動オプション:拡張機能、Privacy Sandbox、そのほかのオプションの一覧です。

その他の起動オプション

  • extensions — 展開済み拡張機能のディレクトリパスのリスト(--load-extension + --disable-extensions-except を出力します)。
  • disablePrivacySandbox / disable_privacy_sandbox — true にすると Privacy Sandbox の API(Topics、FLEDGE / Protected Audience、Shared Storage、Private Aggregation、Fenced Frames)を無効にします。0.23 以降はデフォルトでオフです。デフォルトのペルソナは Google Chrome として振る舞い、Google Chrome はこれらの API をすべて搭載しているためです。このオプションを有効にするのは、ペルソナが Google 依存を取り除いた Chromium の場合だけにしてください。WebUSB には影響しません。
  • agentTyping / agent_typing — エージェントのキー入力のテンポ(human(デフォルト)/ fast / instant)。エージェントを参照してください。
  • tlsProfile — TLS ClientHello をペルソナが名乗る Chrome のバージョンと整合させ、ネットワーク層を(ビルド本来の TLS ではなく)UA に合わせます。デフォルトの "match-persona" は brandVersion に従い、"native" は手を加えず、"chrome-<major>" はメジャーバージョンを固定します。フィンガープリントフラグを参照してください。
  • platform: "android" — ベストエフォートのモバイルペルソナ(タッチ、coarse ポインター、モバイルの画面/DPR、Mali/Adreno の WebGL、スマートフォンのビューポート)。デスクトップのエンジンでは GPU の描画はデスクトップのままなので、描画の整合性を取るには canvas ブリッジと組み合わせてください。
  • storageQuota、fingerprintProfile、canvasBridge、webrtcIp、acceptLanguage、disableGpuFingerprint、fingerprintNoise — フィンガープリントフラグを参照してください。

新しいオプション(ライセンスビルド)

以下のオプションにはライセンスビルド(「GitHub で無料」または Pro)が必要です。それぞれに必要なエンジンのリビジョンを角かっこ内に示しています。古いエンジンでは、152 r22 のオプションは SDK が警告を出してスキップし、154 r32 のオプションは SDK がエンジンを確認して、ビルドが対応していなければオフのままにします。それ以外はエンジンが無視します。

  • stockRuntime / stock_runtime / StockRuntime(または CLEARCOTE_STOCK_RUNTIME=1)— デバッグ用の実行で、Playwright に標準の DevTools の挙動を戻します。対象は、コンソールとページエラーのイベント、page.setContent()、遷移後の exposeFunction() です。ページから観測できるため、デフォルトではオフです。このスイッチを持たないエンジンではスイッチなしで起動し、SDK が一度だけ警告します。ローカルと Docker での起動のみが対象です。イベントとデバッグを参照してください。[154 r32; SDK 0.41.0]
  • personaEnv / persona_env / PersonaEnv — SDK 0.41.0 以降はデフォルトでオンです。ペルソナのスイッチ(シード、すべてのペルソナ上書き、プロキシの認証情報、canvas ブリッジのトークン)を、コマンドラインではなく環境変数経由でブラウザに渡します。コマンドラインは、ローカルのどのユーザーでもプロセス一覧から読み取れるためです(Linux では /proc/<pid>/cmdline、Windows ではプロセスの詳細)。エンジンは、ヘルパープロセスのコマンドラインにもこれらを載せません。false または CLEARCOTE_PERSONA_ENV=0 を指定するとコマンドラインに残ります。たとえば、そこから値を読み取る自作のツールがある場合に使います。Docker イメージも、コンテナ内のブラウザに対して同じことを行います。[154 r32]
  • ペルソナトークン — ライセンス版 Chromium 156 ビルド(r51 以降)では、SDK が起動のたびにシードまたはプロファイルに対する署名付きペルソナを Clearcote のペルソナサービスから取得し、上記のスイッチとともにブラウザに渡します。無効にする設定はなく、トークンがなければブラウザは起動しません。SDK 0.63.0、Profile Manager 0.27.0、または対応する Docker イメージが必要です。[156 r51; SDK 0.63.0]
  • ライトかダークか — 154 r32 以降はペルソナがカラースキームを決め(およそ 3 つに 1 つのプロファイルがダークを好みます)、CSS、matchMedia、Sec-CH-Prefers-Color-Scheme リクエストヘッダー、システムカラーがすべてそれに従います。Playwright は作成するすべてのコンテキストでライトをエミュレートしますが、これはダークのペルソナと矛盾します。そのため SDK 0.41.0 以降、そのようなビルドでは、ローカル起動で作成されるコンテキストはカラースキームに手を加えません。それでもエミュレートしたい場合は colorScheme / color_scheme / ColorScheme を渡してください。ペルソナ自体をライトまたはダークにするには、args に --fingerprint-color-scheme=light|dark を指定します。古いビルドでは Playwright のデフォルトのままです。[154 r32]
  • allowThirdPartyCookies / allow_third_party_cookies — サードパーティ Cookie。標準の Chrome と同じくデフォルトで許可されます(SDK 0.45.0 以降)。false でブロックします。埋め込みのサインイン、決済、チャレンジのフレームはこれに依存しています。152 r22 より前のビルドは常にブロックします。[152 r22]
  • transparentProxy / transparent_proxy — リクエストヘッダーと接続タイミングからプロキシの存在を隠します(平文 HTTP のリクエストにはプロキシヘッダーが付かず、プロキシ経由の接続は再利用された接続のようなタイミングを報告します)。プロキシが必要です。[152 r22]
  • fingerprintVoices: false / fingerprint_voices=False — ペルソナのリストではなく、このマシン本来の音声合成ボイスを使います。[152 r22]
  • fingerprint: "off" — トラブルシューティング用に、ペルソナなしで起動します。[152 r22]
  • socks5Udp / socks5_udp — WebRTC の UDP を socks5:// プロキシ経由で流します。これにより音声、ビデオ、ピア接続が動作し、しかも通信はプロキシのアドレスから出ていきます。プロキシ側で許可されている必要があり、住宅用プロキシのプールの多くは許可していません。[151 r17]
  • portableProfile / encryptionKey — マシン間でコピーできるプロファイル(前述)。[151 r14; Python, Node & .NET (0.58.0+)]
  • personaSchema / persona_schema — シードをどのアイデンティティモデルで導出するかを指定します。現行のモデル 7(2026-10-26 の r52 から提供)を使う場合は未設定のままにしてください。グラフィックスカードがマシンの種類(ノートかデスクトップか)を決め、プロセッサー、スレッド数、メモリ、画面がそれぞれ実際のブラウザトラフィックと同じ出現率で選ばれます。5 は r45〜r51、4 は 154 r37〜155 r44、3 は 154 r36、2 は 153 r29〜154 r35 とまったく同じ値を導出するので、それらのビルドで作成したアイデンティティを維持するには該当する値を設定します。1 は r29 より前の元のモデルです。6 はありません。0.64.1 以降、どの SDK でも 5 と 7 を指定できます。別のマシンで同じシードを使う場合を参照してください。realGpuHost / real_gpu_host は、実際のグラフィックスカードを搭載したマシンでのみ追加してください。[151 r19; Python, Node & .NET]
  • shaderDialect: "hlsl" — SDK 0.39.0 以降、Linux または macOS ホスト上の Windows ペルソナではデフォルトで有効です。false でオフになります。シェーダー方言を参照してください。[151 r15]
  • profile: "auto" — シードの代わりに、このマシン向けに選んだ、実機から取得したフィンガープリントで起動します。profileSelect / profile_select で調整できます。Python、Node & .NET(LocalProfile = "auto"、0.58.0+)。Node では SDK 0.31.1 以降、デフォルトの launch()、launchPersistentContext()、serve() で動作します。0.31.0 以前は ephemeralProfile: false が必要で、serve() では失敗していました。

エンジンのビルドに依存しないもの:

  • version / releaseChannel — ビルドを選びます。ビルドの選び方を参照してください。
  • licenseKey / license_key / LicenseKey — ライセンスキー(CLEARCOTE_LICENSE_KEY にも ~/.clearcote/license.key にもない場合)。
  • licenseThroughProxy / license_through_proxy(または CLEARCOTE_LICENSE_THROUGH_PROXY=1)— ライセンス関連の通信を、このマシンから直接ではなく、起動時に指定したプロキシ経由で送ります。
  • launch() の ephemeralProfile / userDataDir — 前述の「SDK を使う方法」の説明を参照してください。
  • widevine: true — DRM コンテンツの再生(両ビルドとも対応)。Widevine & DRM を参照してください。
  • quiet — SDK の起動時の警告と進捗の出力を抑制します。
  • fontDirs / font_dirs / FontDirs — Linux で独自のフォントを使います。後述を参照してください。

Linux で独自のフォントを使う(fontDirs)

Linux では、ブラウザから見えるのは SDK が指定したフォントだけです。つまり、リリースに同梱された、Windows フォントとメトリック互換の代替フォントのバンドル(Arial→Arimo、Segoe UI→Selawik、Times New Roman→Tinos、…)です。ホストにインストールされたフォントは一切届かないため、マシン上の何かによってページの計測結果が変わることはありません。SDK 0.41.0 以降(Python、Node、.NET。launch()、永続コンテキスト、serve())では、次の 2 つの設定でディレクトリを追加できます。

  • fontDirs / font_dirs / FontDirs、または CLEARCOTE_FONT_DIRS — 独自のフォントです。一般的には Windows マシンの C:\Windows\Fonts のコピーで、バンドルより前に並びます。154 r32 以降のライセンスビルドでは、これらが提供するファミリーはどれも、代替フォントではなくそのフォント自身として、自身の名前で描画されます。Windows でそのファミリーを指す名前もそれに従います。Helvetica、Times、Courier、そして CSS の総称ファミリー(sans-serif → Arial、serif → Times New Roman、monospace → Consolas、system-ui → Segoe UI)です。古いエンジンでは、ペルソナが列挙するファミリーには引き続き代替フォントを描画し、ディレクトリのフォントはほかのどのフォントにもない文字にだけ使います。ディレクトリではないパスを指定すると、ライセンスの枠を確保する前に、起動がその場で失敗します。
  • CLEARCOTE_FALLBACK_FONT_DIRS — ほかのどのフォントにもない文字(CJK、インド系の文字、絵文字、…)にだけ使うフォントで、バンドルの後に並びます。どのファミリーも置き換えません。Docker イメージは、同梱している各文字体系用のフォントをこれに設定しています。
from clearcote import launch

# a copy of a Windows machine's C:\Windows\Fonts, on the Linux host
browser = launch(fingerprint="acct-1", platform="windows", font_dirs=["/srv/windows-fonts"])
# or: CLEARCOTE_FONT_DIRS=/srv/windows-fonts (several directories: separate them with ":")
  • どちらの変数も : 区切りのリストです。ファミリー名はフォントファイル自体から読み取るため、fontconfig のツールは不要です。どちらにも /usr/share/fonts 全体を指定しないでください。ホストのラテン文字のファミリーがバンドルと競合し、Windows ペルソナが報告する文字幅が変わってしまいます。
  • clearcote info(Python と Node)は Linux で、起動時にブラウザから見えるフォントが 29 の文字体系のうちどれを描画できるか、指定したフォントディレクトリ、主要な Windows ファミリーのうちどれを本物のフォントとして提供しているかを報告します。
  • 独自のフォントを指定したまま代替フォントを使い続けるには、args に --disable-genuine-font-faces を渡します(154 r32+)。SDK はこれを検出して自身のフォントルールをそのまま維持するので、エンジンと fontconfig の間でファミリーの扱いが食い違うことはありません。
  • 独自のフォントを使う Windows と macOS では無視され、クラウドでの起動と macOS の Docker 起動では拒否されます。自分のコンテナでは、フォントをマウントし、そこで CLEARCOTE_FONT_DIRS を設定してください(デプロイを参照)。使用許諾を受けたフォントだけを使ってください。
  • 0.41.0 より前の .NET SDK はブラウザにバンドルをまったく指定していなかったため、Linux 上の .NET からの起動ではホストのフォントが使われ、代替フォントは一切使われませんでした。現在は Python や Node と同じ動作になったため、Linux 上で Windows ペルソナが計測する値が変わります。