エージェント & LLM 向け

Clearcote は、自動化ツールでも人間と同じように簡単に内容をたどり、組み込み、コントリビュートできるように構成されています。誰かのために Clearcote をセットアップする場合は、セットアップ手順書に従ってください。

コーディングエージェント向けセットアップ手順書

Claude Code、Codex、Cursor、Windsurf、Cline などの AI コーディングエージェントとして Clearcote のセットアップを頼まれた場合は、次のステップを順番に進めてください：インストール済み（installed）、ライセンス設定済み（licence set）、起動済み（running）、検証済み（verified）。各ステップにはチェックがあり、そのチェックに合格して初めてステップは完了です。進捗はファイルに記録してください。そうすれば、新しいセッションでも、翌日に戻ってきたユーザーでも、最初からやり直さずに、完了していない最初のステップから再開できます。この手順書は /setup.md に 1 つの Markdown ファイルとしても置いてあり、ホームページでエージェントに貼り付けるよう案内しているのはこのアドレスです。そちらが正本で、このセクションは見出しごとにその内容に沿っています。

ルール

• コマンドはすべて自分で実行し、その出力を読んでください。ステップが失敗したら、作業を止めて報告してください。どのステップが失敗したか、実行したコマンド、エラー行そのものをユーザーに伝え、続けて下の表にある対処法を示します。確認を取らずに、失敗したチェックを別のやり方で済ませないでください（検証を省く、古いビルドに固定する、ビルドを切り替えるなど）。
• インストールは公式の配布元からのみ行ってください：PyPI、npm、NuGet の clearcote パッケージ、PyPI と npm の clearcote-mcp、Docker イメージ teamflatearth/clearcote、そして clearcotelabs/clearcote-browser のリリースです。ブラウザは SDK 自身がダウンロードして SHA-256 を確認します。ブラウザのビルドをほかの場所から取得することも、このチェックを無効にすることも決してしないでください。
• ライセンスキーや API キーをチャットに貼り付けるよう、ユーザーに求めないでください。キーを出力すること、ログに残すこと、コミットすることも決してしないでください。それでも貼り付けられた場合は、キーを繰り返し表示せず、自分が作成するどのファイルにも書き込まず、「Licenses」ページでキーをローテーションするよう提案してください。
• リンクが期限切れ、またはリンク切れのときは、コピーを探さないでください。SDK が使うダウンロードリンクは有効期間が短く、SDK は実行のたびに新しいリンクを取得します。URL を使い回さずに、コマンドを再実行してください。それ以外のリンク（サインイン、デバイスコード、ダッシュボードのページ、ユーザーから転送されたリンクなど）は、取得元に戻るか、新しいリンクをユーザーに頼んでください。ミラー、キャッシュされたコピー、非公式パッケージで代用することは決してしないでください。
• ユーザーのプロジェクトにインストールしてください（プロジェクトの virtualenv、package.json、.csproj）。ユーザーから別の指示がない限り、グローバルにはインストールしません。プロジェクト外の設定（たとえば MCP クライアントの設定）を編集する前と、費用が発生するものを開始する前（ホスト型ブラウザは GB 単位の課金です）には、確認を取ってください。
• 完了とは、ブラウザの正確なバージョンを確認できた状態を指します。パッケージがインストールされただけでは完了ではありません。

進捗ファイルを残す

プロジェクトのルートに clearcote-setup.json を作成し（シークレットは含みません）、チェックのたびに更新します。route は python、node、dotnet、mcp、docker のいずれか、build は open（キーなし）か licensed（「GitHub で無料」または Pro）です。blocked には、何を待っているかを記録します。

{
  "route": "python",
  "build": "licensed",
  "steps": {
    "installed":   { "done": true,  "checked": "2026-10-06T10:12:00Z", "evidence": "clearcote SDK 0.45.0" },
    "licence_set": { "done": false },
    "running":     { "done": false },
    "verified":    { "done": false, "browser_version": null }
  },
  "blocked": { "step": "licence_set", "waiting_for": "user approves the device sign-in" }
}

セッションの開始時にはこのファイルを読み、完了していない最初のステップから続けます。セッションの間にキーの期限が切れたり、キャッシュが消去されたりすることがあるため、前提とする以前のステップのチェックは再実行してください。

ステップ 0：ルートとビルドを選ぶ

ユーザーに一度だけ尋ね、回答を記録します。

• ルート。ユーザー自身のコードで使う場合は、プロジェクトの言語の SDK です（Python 3.8+、Node 20+、.NET 8。まだプロジェクトがなければ Python を勧めてください）。エージェントであるあなたがブラウジングに使う場合は、MCP サーバーです（Python 3.10+）。既存のフレームワーク用の CDP エンドポイントとして使う場合は、Docker イメージです。
• ビルド。オープンビルドはキーもサインアップも不要です。Chromium 150 ベースのオープンソース（BSD-3）で、使い始めるには十分です。最新ビルドは Chromium 154 ベースで、ライセンスキーを使います。同時に 1 ブラウザまでなら GitHub で無料、Pro なら同時に最大 250 ブラウザまで使えます。

ブラウザは Windows x64 と Linux x64 で動作し、Docker イメージも x64 です。macOS や ARM マシンの場合は、作業を止めてその旨を伝えてください。ローカルのブラウザが不要な選択肢はホスト型ブラウザです。

ステップ 1：インストール済み

pip install -U clearcote                  # Python, inside the project's virtualenv
npm install clearcote                     # Node
dotnet add package Clearcote              # .NET (see below for the checks)
pip install -U clearcote clearcote-mcp    # MCP server: Python 3.10+, no mcp pin needed
docker pull teamflatearth/clearcote       # Docker

チェック：clearcote version（Node では npx clearcote version）が 0.45.0 以降のバージョンを出力します。Docker の場合は、docker image ls teamflatearth/clearcote にイメージが表示されます。

.NET には独自の clearcote コマンドがありません。dotnet list package の一覧に Clearcote が表示されることを確認したうえで、ステップ 1〜3 の clearcote コマンドはすべて npx -y clearcote <command>（Node 20+）または pipx run clearcote <command>（Python 3.8+）として実行してください。これでプロジェクトに何かが追加されることはなく、コマンドは .NET SDK と同じブラウザキャッシュとライセンスファイル（~/.clearcote/license.key）を使います。マシンに Node も Python もない場合は、どちらかをインストールするようユーザーに依頼してください。このコマンドがないとブラウザのバージョンを確認できないため、セットアップを検証できません。

ステップ 2：ライセンス設定済み

オープンビルドの場合は、evidence（証跡）として open build, no key を記録し、このステップを完了にします。最新ビルドの場合、キーはあなたを経由せずにユーザーのマシンに届きます：

• clearcote --help に clearcote login --device が表示される場合は、clearcote login --device（Node では npx clearcote login --device）を実行します。リンクと短いコードが表示されます。ユーザーが自分のブラウザでそのリンクを開き、サインインして承認すると（無料キーには作成から 30 日以上経った GitHub アカウントが必要です）、SDK はキーを表示せずに ~/.clearcote/license.key に保存します。
• それ以外の場合は、ユーザーが「Licenses」ページでキーを取得し、自分のターミナルで clearcote login（Node では npx clearcote login）を実行して、そこにキーを貼り付けます。キーはユーザーの画面に表示されるだけで、チャットには出ません。この手順をユーザーに伝え、完了したと言われるまで待ってください。代わりに、ユーザー自身が CLEARCOTE_LICENSE_KEY を設定することもできます。設定場所はシェルのプロファイル、CI のシークレット、MCP クライアント設定の env ブロック、または Docker の環境です（その場合は docker run -e CLEARCOTE_LICENSE_KEY で、コマンドに値を出さずにキーを渡せます）。

clearcote login <key> を自分で実行することは決してしないでください。キーがあなたのトランスクリプトとシェルの履歴に残ってしまいます。~/.clearcote/license.key を開くこともしないでください。チェック：clearcote info --quick の Licence 行に、マスクされたキーと from file または from env が表示されれば、確認はそれで十分です。none (free build) は、キーが見つからなかったことを意味します。MCP クライアントの設定やコンテナの中だけで設定されたキーは、あなたのシェルからは見えません。値を出力せずに、変数名が存在することを確認してください。

ステップ 3：起動済み

clearcote install    # downloads and verifies the build the key allows
clearcote info       # starts the browser once, headless

（Node では npx clearcote install と npx clearcote info。）チェック：clearcote info が、ブラウザのバージョンとともに Launch test ok を出力します（--json を付けた場合は launch.ok が true になり、launch.version にバージョン、binary.tag にビルドが入ります）。無料キーでは、これで 1 つしかないブラウザ枠を一時的に使うため、先にほかの Clearcote ブラウザを閉じてください。続いて、ルートに応じて次のことを行います：

• SDK：最初のスクリプト clearcote_hello.py または clearcote_hello.mjs を実行します。チェック：Example Domain と Chrome のユーザーエージェントが出力され、スクリプトが終了します。.NET では、Playwright & Puppeteer の C# タブを使ってください。fingerprint シードがアイデンティティです。同じシードなら毎回同じデバイスになるので、アカウントごとに 1 つのシードを使ってください。
• MCP サーバー：MCP サーバーのページにあるとおり、コマンド clearcote-mcp をクライアントに登録します（先に確認を取り、virtualenv 内にある場合はフルパスを指定します）。クライアントを再起動し、navigate ツールを https://example.com に対して呼び出します。最終的な URL とページタイトルが返ります。
• Docker：下のように、コンテナを起動してログとエンドポイントを確認します。

import clearcote

browser = clearcote.launch(fingerprint="first-run")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
print(page.evaluate("navigator.userAgent"))
browser.close()

ステップ 4：検証済み

ステップ 3 の出力を、ユーザーが使うべきビルドと照らし合わせます。Docker では、ビルドタグはログ行のエンジンパスの一部に含まれています。

古いビルドを固定している Pro プランでは、代わりにそのビルドが表示されます。それがユーザーの選んだビルドでなければ、作業を止めてユーザーに伝えてください。バージョンが一致したら、verified をバージョンとともに完了にし、ユーザーに次のことを伝えます：ルート、SDK のバージョン、実行されているビルドとそのブラウザの正確なバージョン、最初のスクリプトの場所と実行方法、キーの保存場所（ファイルか環境変数か。キーそのものは決して伝えません）、そしてドキュメント。

ステップが失敗したとき

オプション（ユーザーが望む場合のみ）

• プロキシ。Playwright のプロキシと geoip=True を渡すと、タイムゾーンと言語がプロキシの出口 IP に合わせられます。プロキシと geoipを参照してください。
• MCP 経由で、エージェントであるあなた自身が使うブラウザ（それがルートでなかった場合）：pip install -U clearcote-mcp（Python 3.10+）を実行し、ステップ 3 と同じように登録します。最新ビルドの場合、サーバーはステップ 2 で保存されたキーを見つけます。または、ユーザー自身がそのサーバーの env に CLEARCOTE_LICENSE_KEY を追加します。
• 実行するマシンがない場合。ホスト型ブラウザなら、1 回の API 呼び出しで、同じブラウザを Clearcote のサーバー上で起動できます。API キーが必要で、GB 単位で課金されるため、先に確認を取ってください。

機械可読なサマリー

簡潔なプレーンテキストのプロジェクト概要は /llms.txt に、ドキュメント全体をプロンプト用に 1 ファイルにまとめたものは /llms-full.txt にあります。リポジトリには、コントリビューター向けに構成と規約を説明した AGENTS.md も含まれています。

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 150 (v0.1.0-pre.23), licensed build 154.0.8037.57-r36",
  "identity_model": "engine-level, coherent seed persona + per-site render noise",
  "automation": "SDK (npm/PyPI/NuGet package clearcote) returning Playwright objects; CDP endpoint for Puppeteer and others",
  "platforms": ["windows-x64", "linux-x64"],
  "license": "BSD-3-Clause (open build + SDKs); the licensed build adds unpublished patches",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "open build: GPG-signed SHA256SUMS + pinned key; every SDK download: SHA-256",
  "control_via": "SDK options, or chromium command-line switches (args) on the open build"
}

最小限の組み込みレシピ

1. SDK をインストールします（pip install clearcote / npm i clearcote）。ブラウザのダウンロードと検証は SDK が行います。
2. 操作の主体となるアイデンティティから、決定的な fingerprint シードを導出します。
3. プロキシを使う場合は geoip=True を渡し、タイムゾーン、言語、WebRTC をプロキシの出口に合わせます。
4. CDP URL を必要とするフレームワーク（browser-use、Stagehand、Crawl4AI）では、代わりに serve() または clearcote serve を使います。

from clearcote import launch

task_id = "1234"
SEED = "agent:" + task_id          # stable, reproducible identity per task

browser = launch(fingerprint=SEED, geoip=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

executablePath でオープンビルドのバイナリを直接操作することもできますが、ライセンスビルドは SDK 経由でしか起動せず、直接起動すると SDK のデフォルト設定が失われます（Playwright & Puppeteer を参照）。より忠実度の高いアイデンティティが必要なら、シードの代わりに実機からキャプチャしたプロファイルで起動します。launch(profile="auto") はプロファイルライブラリ（ライセンスビルド）からこのマシンに合うものを選びます。または fingerprint_profile="profile.json"（Node では fingerprintProfile）を渡します。プロファイルと fingerprint シードは併用しないでください。

ブラウザ内 AI エージェント

Clearcote には、実際のページを自律的に操作する AI エージェントがオプション（オプトイン）で付属しています。エージェントは表示中のページを把握し、ユーザーが設定した LLM に次に何をすべきかを問い合わせ、注入したスクリプトではなく、Chrome の Actor フレームワークを通じて本物の信頼済み（trusted）入力イベントで操作します。デフォルトでは無効で（エージェントキーかエージェント用のスイッチを指定しない限り動作しません）、キーは各自で用意します。OpenAI 互換 / OpenRouter の任意のエンドポイントを指定できます。モデルに何かを送信する前に、パスワード欄はマスクされます。launch_agent()（永続コンテキスト）を使ってください。これがサポートされている方法です。

SDK では、launch_agent（Node では launchAgent）が永続的な BrowserContext を返し、run_agent_task(page, goal, max_steps=...)（Node では runAgentTask）がそれを操作して { success, finalText, steps, stepsJson } を返します。1 つのプロファイルを使い回すには、第 1 引数（Node では userDataDir）にプロファイルディレクトリを渡します。渡さない場合は、呼び出しごとに新しい一時プロファイルフォルダが作られ、終了時にも削除されません。Python & Node のみ対応です。

import os
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext.
ctx = launch_agent(
    agent_llm_key=os.environ["OPENROUTER_API_KEY"],   # required: the SDK does not read env vars (the CLI does)
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

エージェントの起動オプションは、バイナリのスイッチに直接対応しています。agent_llm_url / agentLlmUrl（--agent-llm-url）、agent_llm_key / agentLlmKey（--agent-llm-key）、agent_model / agentModel（--agent-model）、そして agent_typing / agentTyping です。エージェントに URL（デフォルトは OpenRouter）、キー、モデルがそろえばタスクが実行されます。エージェントはモデルにプレーンテキストの JSON で返答するよう求めるため、エンドポイントがツール呼び出しに対応している必要はありません。agent_tool_mode / agentToolMode（--agent-tool-mode、CLI では --tool-mode）は受け付けますが、現時点では効果がありません。

agent_typing / agentTyping は、エージェントのキー入力のリズムを調整します。human（デフォルト）はキーごとの keydown/keyup のタイミングで入力し、長いテキストも 1 キーずつ入力します。fast はエンジンの高速なリズム、instant は一括入力です。デフォルト設定は、入力における 2 つの手がかりを避けます。機械的に完全に均一なタイミングと、長いテキストが一瞬で貼り付けられること（キー入力イベントが一切発生しない）です。

clearcote-agent CLI

同じエージェントを CLI としても使えるので、スクリプトから手軽に実行できます。1 回限りのゴールを渡すことも、対話型の REPL に入ることもできます。モデルのキーは --key、または環境変数 $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY から取得します。

# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

CLI のオプションには --llm-url、--model、--max-steps、--profile、--headless、--executable、--fingerprint、--proxy、--timezone、--json などがあります。--url にホスト名だけを渡すと、HTTPS の URL として扱われます。

参照先

• フィンガープリントのフラグ：スイッチの完全なリファレンス（機械でも扱いやすい形式）。
• Playwright & Puppeteer：そのまま置き換えられる起動パターン。
• サンプル：SDK、プロファイル、プロキシ、canvas bridge、CI、エージェントの、そのままコピーして使えるレシピ。
• ブラウザ内 AI エージェント：オプトインの自律的なページ操作と clearcote-agent CLI。
• MCP サーバー：Claude Desktop、Cursor、Cline から Clearcote を操作。
• デプロイ：clearcote serve で、1 つの CDP URL から接続ごとに別々のアイデンティティを提供。
• 推奨設定：有効にすべき設定と、触らずにおくべき設定。
• 検証：実行する前にバイナリを確認。
• ソースリポジトリ：パッチ、ビルドパイプライン、AGENTS.md。

アイデンティティは決定的に作りましょう。シードを安定した ID（テナント、アカウント、タスク）から導出すれば、同じアクターには常に同じブラウザフィンガープリントが割り当てられ、再現もデバッグも容易になります。