ローカルでもクラウドでも、1 つの SDK
お使いのマシンで Clearcote を起動するのと同じ launch() で、当社のサーバー上でも起動できます。cloud=True(Python)または cloud: true(Node)を渡すか、CLEARCOTE_CLOUD=1 を設定すると、ホスト型ブラウザに接続された、いつもと同じ Playwright の Browser が返ってきます。スクリプトの残りの部分はそのままで動きます。
スクリプトをクラウドで実行する
SDK 0.34.0 以降と、「API keys」ページで作成した API キーが必要です。キーを CLEARCOTE_API_KEY に設定して、次のように実行します。
from clearcote import launch
browser = launch(cloud=True, fingerprint="acct-1", country="de")
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
browser.close() # ends the cloud sessionこの呼び出しの裏側で、SDK は POST /api/v1/browsers でセッションを作成し、CDP で接続して、ローカル起動と同じように humanize を設定します。ページは browser.contexts[0] で開いてください。このコンテキストがセッションのプロファイルを持っています。browser.new_page() も使えますが、プロファイルの Cookie を持たない別のコンテキストが開きます(その場合も、ローカルと同じく SDK が Playwright のエミュレートされたビューポートをオフにします)。
ブラウザの裏にあるホスト型セッションは、Python では browser.cloud_session、Node では cloudSessionOf(browser)(browser.cloudSession でも可)で取得できます。中身は作成時のレスポンスで、id、worker、expiresAt を含み、1 回限り有効な connectUrl は除かれています。この id を Cloud クライアントで使うと、引き継ぎや録画とイベントを扱えます。
環境変数で切り替える
呼び出しで cloud を省略すると、環境変数によって決まります。そのため、1 つのスクリプトを、ノート PC ではローカルで、本番環境ではクラウドで、コードを変えずに実行できます。
| 変数 | 意味 |
|---|---|
CLEARCOTE_CLOUD | 1、true、yes のいずれか: cloud 引数のない launch() がクラウドブラウザを起動します。それ以外の値または未設定: ローカルのブラウザを起動します。 |
CLEARCOTE_API_KEY | あなたの cc_live_… キー。クラウドの呼び出しすべてに必要です。 |
CLEARCOTE_API_URL | 接続先の API。デフォルトは https://www.clearcotelabs.com です。変更するのは開発用のコントロールプレーンを使う場合だけにしてください。https:// である必要があります。プレーンな http:// は、キーが暗号化されずにネットワークを通ることがないよう、このマシン(localhost、127.0.0.1、::1)に対してだけ受け付けます。 |
export CLEARCOTE_API_KEY=cc_live_...
python scrape.py # a local browser
CLEARCOTE_CLOUD=1 python scrape.py # the same script on a hosted browser明示的な引数が常に優先されます。cloud=False / cloud: false は、CLEARCOTE_CLOUD の値に関係なくローカルで起動します。
オプション
クラウドモードの launch() は、POST /api/v1/browsers のオプションを受け取ります。Node では API の名前をそのまま使い、Python では snake_case を使って SDK が名前を変換します。各オプションの詳しいルールは「ホスト型ブラウザ」のリファレンスにあります。
| Python | Node と API | 意味 |
|---|---|---|
identity | identity | アカウントごとに 1 つのラベル。同じデバイスと、その IP がオンラインである限り同じ住宅用 IP を使います。 |
fingerprint | fingerprint | デバイスのシード。同じシードからは同じデバイスプロファイルが得られます。 |
light_stealth | lightStealth | デフォルトは true。 |
platform | platform | windows、macos、linux、android のいずれか。 |
brand | brand | Chrome、Edge、Opera、Vivaldi のいずれか。 |
timezone | timezone | IANA 名。例: Europe/Berlin。 |
locale, accept_language | locale | Accept-Language。例: de-DE,de。accept_language(Node では acceptLanguage)は別名です。 |
geoIdentity | geoIdentity | Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event. |
geoip | geoip | タイムゾーンと言語を出口 IP に合わせます。 |
proxy | proxy | "managed"(デフォルト)、{ server, username, password }、または http://user:pass@host:8080 のような URL。URL は SDK がそのオブジェクトに分解します。 |
country | country | マネージド住宅用プールでの出口の国。 |
state | state | マネージドプールでの出口の州または地域。country が必要です。 |
city | city | マネージドプールでの出口の都市。state が必要です。 |
proxy_session | proxySession | 固定(sticky)用のラベル。同じラベルを使うと、後で同じ出口 IP が戻ってきます。 |
timeout_sec | timeoutSec | セッションの長さの上限(秒)。 |
idle_timeout_sec | idleTimeoutSec | CDP コマンドがこの時間届かなければセッションを終了します。 |
max_gb | maxGb | トラフィックがこの量に達したらセッションを停止します。 |
headless | headless | デフォルトは true。false(実際のウィンドウ)にすると、ページにはアイデンティティの画面サイズではなく、サーバー自身のディスプレイが報告されます。 |
humanize | humanize | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input". |
keep_alive | keepAlive | 切断した後もブラウザを動かし続けます。 |
version | version | 特定の Clearcote リリースを実行します。 |
profile | profile | クラウドプロファイル。"name" で読み込み、{ name, persist: true } で書き戻しも行います。 |
url | url | ブラウザを受け取る前に、最初のタブで開かれます。 |
adblock | adblock | 既知の広告ホストとトラッカーホストを、読み込まれる前に拒否します。 |
solve_sliders | solveSliders | デフォルトは true。スライドして確認するタイプのチャレンジを自動でドラッグします。false でオフになります。SDK 0.35.0 以前はこの名前を受け付けません(常にオンです)。 |
solve_checkboxes | solveCheckboxes | デフォルトは true。「verify you are human」のチェックボックスを自動でクリックします。false でオフになります。SDK 0.36.2 以前はこの名前を受け付けません(常にオンです)。 |
solve_press_hold | solvePressHold | デフォルトは true。「press and hold」型の確認ボタンを、完了が報告されるまで自動で押し続けます。false でオフになります。SDK 0.49.0 以前はこの名前を受け付けません(常にオンです)。 |
challenge_service | challengeService | デフォルトはオフ。true または { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur }(Python では max_solves、max_spend_eur、api_key も使えます)。無料のアクションで解決できないチャレンジを、あなたのキーか当社のキーで解決サービスに送ります。SDK 0.38.0 以降が必要です。 |
record | record | セッションを MP4 で録画します。 |
note | note | セッションに付ける自分用のラベル。 |
worker | worker | 以前のセッションと同じサーバーで起動します。 |
humanize | humanize | 未指定または True(SDK 0.44.0 以降): ローカル起動と同じく SDK 自身の humanize がマウス、キーボード、スクロールを扱い、サーバー側の humanize はオフになります。False: どちらも使いません。0.44.0 より前は、未指定だとホスト型ブラウザに任され、マウスの移動だけが人間らしくなっていました。 |
show_cursor | showCursor | マウスを追いかける赤い点を表示します。観察やデバッグ用です。humanize と同じく SDK 側の機能です。 |
api_key, api_url | apiKey, apiUrl | この起動で使うアカウントと API サーバー。デフォルトは CLEARCOTE_API_KEY と CLEARCOTE_API_URL。オプションとして送信されることはありません。 |
timeout, slow_mo | timeout, slowMo | CDP 接続に対する Playwright 自身のオプション(ミリ秒)。API には送信されません。 |
同じ点と違う点
同じ点:
- Playwright のオブジェクトが返ります。
launch()はBrowserを、launch_persistent_context()はBrowserContextを返します。同期でも非同期でも、ローカルとまったく同じです。 - 人間らしい入力がデフォルトでオンです。SDK 0.44.0 以降、クラウドで起動すると、ローカルで
humanize=Trueを指定したときと同じく SDK 側で humanize を行います。マウスは人間らしい軌跡で動き、キーは 1 つずつ入力され、スクロールはホイールのノッチ単位になり、座標指定のクリックはエンジン自身が再生します。各ステップがネットワークを通るため、通常の入力より遅くなります。シンプルで速い入力にしたい場合はhumanize=Falseを渡してください。どちらの場合も、起動時にホスト型ブラウザ自身のマウス移動はオフになるため、カーソルを動かすのはどちらか一方だけです。SDK を使わずに接続するクライアントでは、ホスト型ブラウザ側の機能がそのまま残ります。サーバー上でマウスを動かし、クリックごとに人間が押す程度の時間ボタンを押し続け、大きなスクロールをホイールのノッチ単位に分割します。 - 同じエンジン。ホスト型セッションは SDK がダウンロードするのと同じ Clearcote のリリースで動きます。そのため、ペルソナのオプションはどちらでも同じ意味を持ち、
versionは同じビルドを固定します。
違う点:
- ローカル専用のオプションは拒否されます。
executable_path、args、user_data_dir、extensions、ignore_default_argsなど、手元のマシン上のバイナリでしか意味のないオプションは、無視されるのではなく、Python ではValueError("<name> is not available for cloud browsers")を送出します(Node でも同じメッセージのエラーになります)。 - フォルダの代わりにプロファイル。クラウドブラウザには、あなたのディスク上のフォルダがありません。実行をまたいで Cookie やサイトのストレージを残すには、名前付きのクラウドプロファイルを使います(下記参照)。
profileはクラウドプロファイルを指します。ローカルでは、profileは取得済みのデバイスプロファイル("auto")を選びます。クラウドモードでは、保存済みのクラウドプロファイル(Cookie、localStorage、IndexedDB)の名前を指定します。- ホスト型のデフォルト値。クラウドセッションはホスト型のデフォルト値から始まります。Windows のペルソナ、
lightStealthオン、出口 IP に合わせたシード・タイムゾーン・言語、Google Chrome が持つ Widevine モジュール、人間らしいマウス移動、そして自分のproxyを渡さない限り住宅用の出口 IP です。 - 終了。
browser.close()は接続を切り、クライアントがいなくなった時点でセッションは終了します。念のため SDK も API 経由でセッションを停止します。keep_alive/keepAliveを指定すると、ブラウザはそのまま動き続け、あなたが停止するか制限に達するまで終了しません。 - ホスト型の制限。
file://、拡張機能、プライベートネットワークは使えません。ダウンロードは接続経由で取得し(「ファイルのダウンロード」を参照)、page.on("console")には何も届きません。制限を参照してください。 - 課金。クラウドブラウザは、ほかのホスト型セッションと同じく、トラフィック 1 GB ごとにプリペイド残高から課金されます。ローカルのブラウザには、ライセンス以外の費用はかかりません。
クラウドプロファイル上の永続コンテキスト
cloud=True を指定した launch_persistent_context() は、フォルダの代わりにプロファイル名を受け取ります。profile: { name, persist: true } で起動したクラウドセッションの最初のコンテキストを返します。セッションはプロファイルを読み込み、コンテキストを閉じるとセッションが終了して、Cookie とサイトのストレージがプロファイルに書き戻されます。
from clearcote import launch_persistent_context
ctx = launch_persistent_context(cloud=True, profile="shop-account", country="de")
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://shop.example.com/account")
ctx.close() # ends the session and saves "shop-account"cloud=True と一緒に user_data_dir を渡すと、profile= を使うよう案内する ValueError が送出されます。1 つのプロファイルに保存できるのは、同時に 1 セッションだけです。手元にある Cookie からプロファイルを作るには、Cookie 同期を使います。
Cloud クライアント
API のそれ以外の機能すべてにクライアントがあります。セッション、エージェントの実行、プロファイル、Webhook です。CLEARCOTE_API_KEY と CLEARCOTE_API_URL を読み込むか、引数として受け取ります。Python クライアントは標準ライブラリだけを使います。AsyncCloud には asyncio 用に同じメソッドがあります。
from clearcote.cloud import Cloud, CloudError
cloud = Cloud() # or Cloud(api_key="cc_live_...", base_url="https://www.clearcotelabs.com")
session = cloud.browsers.create(country="de", record=True)
print(session["id"], session["connectUrl"])
try:
cloud.browsers.stop(session["id"])
except CloudError as e:
print(e.status, e.code, e.message)| 名前空間 | メソッド |
|---|---|
browsers | create(**options), get(id), list(status=None, note=None, limit=None, before=None), stop(id), live(id, control=False), share(id, control=None, minutes=None, recording=None), handoff(id, reason=None, timeout_sec=None), handoff_done(id), wait_handoff(id, timeout=None, poll=2.0), events(id, after=0, limit=None), recording_url(id), download_recording(id, path) |
runs | create(task, url=None, schema=None, secrets=None, wait=True, timeout=None, poll=1.5, on_update=None, **options), get(id), list(limit=None, before=None), cancel(id), wait(id, timeout=None, poll=1.5, on_update=None) |
profiles | list(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …) |
webhooks | create(url, events=None, description=None), list(), delete(id), test(id) |
どのメソッドも、エンドポイントの JSON をそのまま返します。Python では dict、Node ではプレーンなオブジェクトです。一覧系の呼び出しは、素のリストではなく、{ balanceEur, sessions } や { runs } のような API のオブジェクトを返します。SDK 自身が待機する時間(timeout、poll)は、どちらの言語でも秒単位です。
Node には camelCase で同じメソッドがあり(handoffDone、waitHandoff、importCookies、recordingUrl、downloadRecording)、省略可能な引数は 1 つのオブジェクトにまとめて渡します。live(id, { control })、events(id, { after, limit })、runs.create(task, { url, schema, country, … })、importCookies(name, cookies, { mode })、webhooks.create(url, { events }) のようになります。呼び出しが失敗すると CloudError が送出され、HTTP の status(API に到達できなかった場合は 0)、API の code、その message を持ちます。コードの一覧は「エラー」にあります。待機が timeout を超えた場合は、代わりに CloudTimeoutError が送出され、その last には SDK が最後に読み取った状態が入っています。実行や引き継ぎはサーバー上で続きます。不正なオプションは、何かを送信する前に、Python では ValueError、Node では Error になります。SDK は Webhook の署名用に verify_webhook / verifyWebhook もエクスポートしています。
clearcote cloud コマンド
SDK に付属する clearcote コマンド(pip install clearcote または npx clearcote)には、同じ API を扱う cloud グループがあります。
# an agent run: prints the result when it finishes
clearcote cloud run "Find the price of the cheapest plan" --url https://example.com/pricing \
[--schema schema.json] [--secret name=value]... [--secret-domain name=host]... [--handoff] [--record] [--json]
# sessions
clearcote cloud sessions
clearcote cloud stop <id>
clearcote cloud events <id>
clearcote cloud recording <id> -o session.mp4
# copy cookies into a cloud profile (--domain or --all-domains is required)
clearcote cloud profile sync <name> (--from-profile DIR | --from-cdp URL | --from-file state.json | --login URL) \
(--domain example.com... | --all-domains) [--replace]
# webhooks
clearcote cloud webhooks add https://example.com/hooks/clearcote [--event run.finished]...
clearcote cloud webhooks list
clearcote cloud webhooks rm <id>
clearcote cloud webhooks test <id>どのコマンドも、--json を付けると要約の代わりに API のレスポンスを出力します。run は結果を待ち、実行が succeeded になった場合だけ 0 で終了する(それ以外は 1、使い方の誤りは 2)ので、シェルスクリプトでも使えます。recording は -o を付けなければ <id>.mp4 に保存します。すべてのフラグは clearcote cloud --help で確認できます。
各コマンドにはそれぞれ専用のページがあります。エージェントの実行、録画とイベント、プロファイル同期、Webhook です。
MCP: AI アシスタント用のクラウドブラウザ
MCP サーバーにも同じ切り替えがあります。env に CLEARCOTE_CLOUD=1 と CLEARCOTE_API_KEY を設定すると、ツールが操作する共有ブラウザがクラウドブラウザになります。API キーを設定すると、タスク全体をエージェントの実行に任せて結果の JSON を返す run_task ツールも使えるようになります。
{
"mcpServers": {
"clearcote": {
"command": "npx",
"args": ["-y", "clearcote-mcp"],
"env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
}
}
}