エージェント & LLM 向け

Clearcote は、自動化ツールでも人間と同じように簡単に内容をたどり、組み込み、コントリビュートできるように構成されています。

プロジェクト全体をエージェントに渡す

ワンクリックでドキュメントをコピーできます。すべてのドキュメントページを、そのままプロンプトに使える 1 つのブロックにまとめたものです。Claude、Codex、Cursor に貼り付ければ、プロジェクト全体のコンテキストを渡せます。

機械可読なサマリー

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

json

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 149 (v0.1.0-pre.22), licensed build 153.0.8010.36-r28",
  "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"
}

最小限の組み込みレシピ

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

python

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 のみ対応です。

python

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 から取得します。

bash

# 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（テナント、アカウント、タスク）から導出すれば、同じアクターには常に同じブラウザフィンガープリントが割り当てられ、再現もデバッグも容易になります。