プロファイル、Cookie 同期、シークレット、2FA
自動化する価値のある作業の多くは、ログインの先にあります。コードにパスワードを書かずにホスト型ブラウザをログイン済みにする方法は 3 つあります。一度ログインしてセッションをプロファイルに保存する方法、手元にある Cookie をCookie 同期でプロファイルにコピーする方法、そしてモデルが一切見ることのないシークレットから、エージェントの実行に 2FA コードも含めてログイン情報を入力させる方法です。
プロファイル
プロファイルは、セッションの Cookie、localStorage、IndexedDB を名前を付けて保存します。profile: { name: "shop-account", persist: true } でセッションを開始すると、プロファイルを読み込み、セッション終了時に書き戻します。profile: "shop-account" で開始すると、読み取り専用で読み込みます。identity や fingerprint を渡さない限り、プロファイルは専用のアイデンティティも持ちます。同じデバイスで、その IP がオンラインである限り同じ住宅用 IP です。詳しいルールはプロファイル:ログインは一度だけを、SDK から使う場合はクラウドプロファイル上の永続コンテキストを参照してください。
プロファイルの中身を、値を含めずに確認するには:
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
# "name": "shop-account",
# "cookies": 42,
# "domains": ["example.com", "shop.example.com"],
# "bytes": 18211,
# "storage": "Local Storage,IndexedDB",
# "updatedAt": "2026-10-02T09:20:11.000Z"
# }domains は最大 50 サイトを、先頭のドットなしでソートして列挙します。bytes は圧縮後のサイズです。storage は一緒に保存されたサイトストレージ(Local Storage、IndexedDB)を示し、インポートした Cookie だけを持つプロファイルでは空になります。存在しない名前には 404 NOT_FOUND が返ります。
Cookie の値を返すエンドポイントはありません。プロファイルの中身が開かれるのは当社のサーバー上だけで、インポートをマージするとき、保持内容を数えるとき、そしてそのプロファイルでセッションを実行するサーバー上に限られます。
Cookie 同期
すでにどこか(自分のブラウザ、ローカルの Clearcote、Playwright スクリプト)でログインしているなら、その Cookie をクラウドプロファイルにコピーすれば、そのプロファイルを使うすべてのセッションがログイン済みの状態で始まります:
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
-H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{
"mode": "merge",
"cookies": [
{ "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
"secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
]
}'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
# "bytes": 18211, "updatedAt": "…" }- 一般的な Cookie 形式ならどれでも使えます。CDP 形式(
Network.getCookies、Network.Cookie/CookieParam)も Playwright 形式(context.cookies()、storage state ファイルのcookies)もそのまま使えます。domainの代わりにurlを指定しても構いません。expiresがない場合、expires: -1(0 以下の任意の値)、またはsession: trueの場合はセッション Cookie として扱われ、すでに期限切れの Cookie はスキップされます。sameSiteは大文字・小文字を問わずLax、Strict、Noneのいずれかで、Noneにはsecure: trueが必要です。 - Chrome と同じようにチェックされます。Chrome が拒否する Cookie(値に
;を含むもの、secureなしのsameSite: "None"、ルールに反する__Secure-や__Host-Cookie、/で始まらないパス)が 1 つでもあると、インポート全体が400になり、メッセージでその Cookie が示されます。 - 保存されるのは
name、value、domain(小文字化)、path(デフォルトは/)、secure、httpOnly、sameSite(送信した場合のみ)、expires(セッション Cookie では省略)です。partitionKeyなどそれ以外のフィールドは破棄されます。 mode: "merge"(デフォルト)は Cookie を追加し、名前・ドメイン・パスが同じものを置き換えます。mode: "replace"はプロファイルの Cookie を送信したリストとまったく同じにします。どちらの場合も、プロファイルの localStorage と IndexedDB は保持されます。- 制限:1 リクエストあたり最大 5000 Cookie、マージ後のプロファイル内も最大 5000(
400 TOO_MANY)。名前は 256 文字、値は 4096 文字、パスは 1024 文字まで。プロファイル全体は圧縮後で最大 3.5 MB(413 TOO_LARGE)。インポートは 10 分あたり 60 回までです。 - まだ存在しないプロファイルは作成されます。プロファイルに保存するセッション(
persist: true)が起動中または実行中の間は、インポートは409 PROFILE_IN_USEで拒否されます。そのセッションが終了時にインポート内容を上書きしてしまうためです。 - インポートしたセッション Cookie(有効期限なし)は、ほかの Cookie と同じく次のセッションに読み込まれます。プロファイルを保存するセッションは、実際のブラウザが再起動時にするのと同じくそれらを破棄するため、その後も必要な場合は再度インポートしてください。
レスポンスには、インポート後のプロファイル内の Cookie 数(cookies)と、送信した Cookie のうち取り込まれた数(imported:期限切れと重複は除外)が含まれ、ドメインの先頭 50 件がソートされて列挙されます。
手元のマシンから SDK で
clearcote コマンドは、Cookie がある場所から読み取り、指定したドメインの分だけをアップロードします:
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com
# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com
# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net
# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com--domain(複数指定するには繰り返します)は、ブラウザがそのドメインに送信する Cookie を選びます。そのドメイン自身、サブドメイン、親ドメインの Cookie です(--domain shop.example.comは.example.comの Cookie も含みますが、.comのような単なるサフィックスの Cookie は含みません)。--domainも--all-domainsもない場合、コマンドは実行を拒否します。プロファイルの Cookie をうっかりすべてアップロードしないためです。--all-domainsはすべてをアップロードします。この作業専用に作ったプロファイルでのみ使ってください。--replaceはmode: "replace"を送信します。デフォルトはマージです。- コードからは
profiles.sync(name, …)で同じ指定ができます。from_profile、from_cdp、from_file、login_urlのうちちょうど 1 つ(Node ではfromProfile、fromCdp、fromFile、loginUrl)、次にdomains=[…]またはall_domains=True(allDomains: true)、そしてreplace=Trueです。戻り値は上記のインポートのレスポンスで、一致する Cookie がない場合は何もアップロードせずにValueError(Node ではError)を送出します。
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud
cloud = Cloud()
# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])
# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com") # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies) # mode="merge"有効な間、Cookie はパスワードと同じ価値を持ちます。セッション Cookie を持っている人は誰でも、あなたとしてログインしている状態になります。アップロードするのは作業に必要なドメインだけにしてください。サイトによっては、ログインをそのときのデバイスや IP に結び付け、コピーされた Cookie をログアウトさせるものがあります。そうしたサイトでは、代わりにホスト型セッション内で persist: true を指定して一度ログインしてください。
シークレットと 2FA
エージェントの実行は、モデルが一切見ることのない値を入力できます。パスワード、口座番号、TOTP 認証アプリの現在のコードなどです。これらを secrets に入れ、タスク内では {{name}} として参照します:
import os
from clearcote.cloud import Cloud
run = Cloud().runs.create(
"Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
"Then open Orders and read the number of the latest order.",
url="https://shop.example.com/login",
secrets={
"email": "me@example.com",
"password": {"value": os.environ["SHOP_PASSWORD"]},
"otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
},
schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
profile={"name": "shop-account", "persist": True}, # next time it starts signed in
)
print(run["status"], run["result"]["output"])| フィールド | 型 | 意味 |
|---|---|---|
"name": "value" | string | 通常の値。実行の url のホスト(とそのサブドメイン)で入力されます。 |
value | string | 値。1〜1024 文字。 |
totp | base32 string | 値の代わりに指定する 2FA シークレット。QR コードの横に表示されるセットアップキーです(英字 A–Z と数字 2–7、最大 128 文字。スペースや小文字が含まれていても構いません)。実行時には現在のコードが入力されます。 |
digits | 6 | 8 | TOTP のみ。デフォルトは 6。 |
period | 30 | 60 | TOTP のみ、秒単位。デフォルトは 30。 |
domains | string[] | 入力を許可するホスト。example.com のようなホスト名を 1〜10 個(ラベルが 2 つ以上。スキーム、パス、ポート、* は不可)。それぞれサブドメインを含みます。デフォルトは url のホストです。 |
- シークレットは文字列、
{ value, domains? }、{ totp, domains?, digits?, period? }のいずれかです。1 回の実行につき最大 20 個。名前は英字で始まり、英字・数字・_を使った 32 文字以内です。 - タスク内の
{{name}}がsecretsにない場合は400(unknown secret "name")になります。urlのない実行でdomainsのないシークレットを渡した場合も同様で、結び付けるホストがないためです。参照はスペースを入れずに、正確に{{name}}と書いてください。 - タスクで一度も参照されないシークレットも指定できます。その場合は作成時のレスポンスの
warningsで通知されます。 - ホストに注意してください。デフォルトでは、シークレットは
urlのホストとそのサブドメインに結び付けられます。https://shop.example.com/loginの対象はshop.example.comで、login.example.comは含まれません。ログインフォームが別のホスト(シングルサインオン、ID プロバイダー)にある場合は、そのホストをdomainsに指定してください。 - TOTP コードは、認証アプリと同じく SHA-1 を使った RFC 6238 に従います。コードは入力するその瞬間に計算されるため、常に現在のコードになります。
- シークレットは 1 回の実行にのみ属します。プロファイルと一緒に保存されることはなく、実行後も保持されません。次の実行でも改めて送信してください(または、ログイン済みのプロファイルで次の実行を行い、ログインを省略してください)。
モデルに見えるもの
Jet の開始前に、タスク内の各 {{name}} は CCSECRET_password_k3x9qa のようなランダムなプレースホルダーに置き換えられ、プレースホルダーは書かれたとおりに入力すること、という一文がタスクに追加されます。モデルが受け取るのはそれだけです。Jet がプレースホルダーを入力すると、その瞬間にサーバー上のブラウザ層が本当の値、または現在の TOTP コードに差し替えます。ただし、ページのホストがシークレットの domains のいずれか、またはそのサブドメインである場合に限ります(iframe 内のフィールドでは、フレームのホストも対象です)。それ以外のホストでは、そのステップは needs_input(「secret password is not allowed on other.example」)で止まり、何も入力されません。
返ってくるものはすべて同じように除去されます。detail、markdown、各ステップの text、output の JSON、イベントでは、シークレットの値、現在の TOTP コード、プレースホルダーがすべて {{name}} と表示されます。そのため、ページにシークレット(たとえばログイン後のメールアドレス)が表示され、スキーマでそれを求めた場合、得られるのはアドレスではなく {{email}} です。
セキュリティモデル
何が何を守り、どこに限界があるか:
- API キーはアカウントそのものです。API キーがあれば、あなたの残高でブラウザを起動し、プロファイルを使い、実行を読むことができます。サーバー上に保管し、ブラウザや配布するアプリには決して入れないでください。
- プロファイルは非公開で、暗号化されています。各プロファイルは暗号化して保存され(AES-256-GCM、顧客ごとの鍵)、開かれるのは当社のサーバー上だけです。インポートをマージするとき、保持内容を数えるとき、そしてそのプロファイルでセッションを実行するサーバー上に限られます。別の顧客の同名のプロファイルは別のプロファイルです。Cookie の値を返すエンドポイントはありません(もちろん、そのプロファイル上のセッションは CDP 経由で自身の Cookie を読み取れます)。
- Cookie 同期でアップロードされるのは選んだものだけです。自分のプロファイルにインポートできるのは本人だけで、上記の制限(5000 Cookie、3.5 MB)内に限られ、起動中または実行中のセッションが保存先にしているプロファイルには決してインポートできません。ドメインの選択はあなたの側で行われます。
clearcote cloud profile syncとprofiles.sync()は、--all-domains/all_domains=Trueを渡さない限り、Cookie をまるごとアップロードすることを拒否します。 - シークレットは実行開始まで封印されています。同じ方法で暗号化され、実行の設定の中に保存されます。開かれるのは、サーバーが実行を引き受けたときだけです。そのサーバーに一度だけ渡され、その時点で保存された設定は消去されます。サーバー上ではメモリ内にのみ置かれ、標準入力経由で Jet プロセスに渡されます。環境変数、コマンドライン、ログ、イベントに入ることは決してありません。サーバーが実行を引き受けた時点で開けなくなっていた場合、実行は
failedで終了し、session.endReasonsecrets_unreadableになります。 - モデルがシークレットを受け取ることはありません。モデルが扱うのはプレースホルダーで、本当の値は許可したホストでのみ入力されます。ページがエージェントをそそのかしてパスワードを別の場所に入力させようとしても(プロンプトインジェクション)、返るのは拒否されたステップで、パスワードではありません。
- 出力は除去されます。実行が返す、または保存するすべてのものにおいて、値、TOTP コード、プレースホルダーは
{{name}}に置き換えられます。 - Jet はサーバー自身の認証情報から切り離されて動作します。各実行は、明示的で最小限の環境を持つ独立したプロセスです。サーバーの鍵やプロキシの認証情報が、そのプロセスやブラウザに渡されることはありません。ブラウザにはホスト型の保護がそのまま適用されます。ローカルファイルもプライベートネットワークも使えません。
そして、これでは守れないもの:
- ログイン先のサイトは値を受け取ります。それが目的なので、
domainsは慎重に選んでください。 - ページが値を表示することがあります。通常のフィールドに値を入力すると、ページにはその値が表示されます。Jet はモデルがページを読む前に入力した値をプレースホルダーに戻しますが、それは入力したとおり(または URL エンコードされた形)で表示されている箇所だけです。整形し直したり一部を隠したりと、変えて表示するページは捕捉できません。パスワードフィールドが読まれることはありません。
- 録画には画面が映ります。通常のフィールドの値は動画に映ります。記録に残したくないログインでは
recordをオフのままにしてください。 - タスクは秘密ではありません。タスクは実行と一緒に保存され、ダッシュボードと実行一覧に表示されます。タスク自体に値を書かず、必ず
{{name}}を使ってください。 - リンクは鍵です。引き継ぎリンクや操作用リンクを持っている人は誰でも、期限が切れるまでログイン済みのブラウザを操作できます。対応すべき本人にだけ送ってください。