Dành cho agent & LLM

Clearcote được tổ chức sao cho các công cụ tự động có thể điều hướng, tích hợp và đóng góp dễ dàng như con người.

Bản tóm tắt cho máy đọc

Bản tóm tắt dự án ngắn gọn, dạng plaintext, nằm tại /llms.txt, còn toàn bộ tài liệu được gộp thành một file sẵn sàng làm prompt nằm tại /llms-full.txt. Repository cũng kèm file AGENTS.md mô tả cấu trúc và quy ước dành cho người đóng góp.

{
  "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"
}

Công thức tích hợp tối giản

1. Cài SDK (pip install clearcote / npm i clearcote) — SDK sẽ tải và xác minh trình duyệt.
2. Suy ra một seed fingerprint tất định từ danh tính mà bạn đang đại diện.
3. Khi chạy sau proxy, truyền geoip=True để múi giờ, ngôn ngữ và WebRTC khớp với điểm exit.
4. Với các framework cần URL CDP (browser-use, Stagehand, Crawl4AI), hãy dùng serve() hoặc clearcote serve thay thế.

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")

Điều khiển trực tiếp binary của bản build mở bằng executablePath cũng được, nhưng bản build có giấy phép chỉ khởi chạy qua SDK, và khởi chạy thô sẽ mất các giá trị mặc định của SDK — xem Playwright & Puppeteer. Để có danh tính với độ chân thực cao hơn, hãy khởi chạy một profile thật đã thu thập thay vì dùng seed: launch(profile="auto") chọn một profile phù hợp với máy này từ thư viện profile (bản build có giấy phép), hoặc truyền fingerprint_profile="profile.json" (Node: fingerprintProfile). Đừng kết hợp profile với seed fingerprint.

AI agent trong trình duyệt

Clearcote đi kèm một AI agent tùy chọn, chỉ chạy khi bạn bật, có thể tự động điều khiển một trang thật. Agent quan sát trang đang mở, hỏi một LLM do người dùng cấu hình xem bước tiếp theo là gì, rồi hành động thông qua framework Actor của Chrome bằng các input event thật, được tin cậy (trusted) thay vì script được chèn vào. Agent tắt theo mặc định (không hoạt động trừ khi bạn cung cấp agent key hoặc các switch của agent) và dùng key của chính bạn: trỏ nó tới bất kỳ endpoint nào tương thích OpenAI / OpenRouter. Các trường mật khẩu được che đi trước khi bất cứ thứ gì được gửi tới model. Hãy dùng launch_agent() (một persistent context) — đó là cách được hỗ trợ.

Từ SDK, launch_agent (Node: launchAgent) trả về một BrowserContext persistent, và run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) điều khiển nó, trả về { success, finalText, steps, stepsJson }. Truyền thư mục profile làm đối số đầu tiên (userDataDir trong Node) để dùng lại một profile; nếu không, mỗi lần gọi sẽ tạo một thư mục profile tạm mới và thư mục này không bị xóa khi đóng. Chỉ hỗ trợ 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"])

Các tùy chọn khởi chạy agent ánh xạ trực tiếp tới các switch của binary: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model), và agent_typing / agentTyping. Một task sẽ chạy khi agent đã có URL (mặc định là OpenRouter), key và model. Agent yêu cầu model trả lời bằng JSON dưới dạng plain text, nên endpoint không cần hỗ trợ tool-call; agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) được chấp nhận nhưng hiện chưa có tác dụng.

agent_typing / agentTyping điều chỉnh nhịp gõ phím của agent: human (mặc định) gõ với thời gian keydown/keyup riêng cho từng phím và vẫn gõ từng phím một với đoạn text dài, fast là nhịp nhanh của engine, còn instant nhập toàn bộ trong một lần. Chế độ mặc định tránh hai dấu hiệu lộ khi gõ phím — nhịp gõ đều hoàn hảo kiểu máy móc, và đoạn text dài được dán vào tức thì (không phát sinh keystroke event nào).

CLI clearcote-agent

Cùng agent đó cũng có dưới dạng CLI để chạy nhanh và dễ đưa vào script. Truyền một goal để chạy một lần, hoặc vào REPL tương tác. Key của model lấy từ --key hoặc từ biến môi trường $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

Các tùy chọn CLI gồm --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone và --json. Nếu truyền vào --url một host trần (không kèm scheme), host đó sẽ được nâng lên HTTPS.

Tìm thông tin ở đâu

• Cờ fingerprint — tài liệu tham chiếu đầy đủ về các switch (cũng thân thiện với máy đọc).
• Playwright & Puppeteer — các mẫu khởi chạy dạng drop-in.
• Ví dụ — công thức copy-paste cho SDK, profile, proxy, canvas bridge, CI và agent.
• AI agent trong trình duyệt — tự động điều khiển trang (phải tự bật) và CLI clearcote-agent.
• MCP server — điều khiển Clearcote từ Claude Desktop, Cursor hoặc Cline.
• Triển khai — clearcote serve: một URL CDP, mỗi kết nối một danh tính riêng.
• Khuyến nghị — nên bật những thiết lập nào, và nên để nguyên những thiết lập nào.
• Xác minh — kiểm tra binary trước khi chạy.
• Repository mã nguồn — patch, pipeline build, AGENTS.md.

Xây dựng danh tính tất định: suy ra seed từ một id ổn định (tenant, tài khoản, task) để cùng một actor luôn nhận cùng một dấu vân tay trình duyệt — dễ tái tạo và dễ debug.