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 đang cài đặt Clearcote cho người khác? Hãy làm theo quy trình cài đặt.

Quy trình cài đặt (runbook) cho coding agent

Nếu bạn là một AI coding agent (Claude Code, Codex, Cursor, Windsurf, Cline và các công cụ tương tự) được nhờ thiết lập Clearcote cho ai đó, hãy lần lượt làm theo các bước dưới đây: đã cài đặt (installed), đã đặt khóa giấy phép (licence set), đang chạy (running), đã xác minh (verified). Mỗi bước có một bước kiểm tra, và một bước chỉ hoàn tất khi bước kiểm tra của nó đạt. Hãy lưu tiến độ vào một file, để một session mới, hoặc một người dùng quay lại vào ngày mai, sẽ tiếp tục từ bước đầu tiên chưa hoàn tất thay vì bắt đầu lại từ đầu. Chính quy trình này cũng có dưới dạng một file markdown duy nhất tại /setup.md, địa chỉ mà trang chủ đưa cho bạn để dán vào agent; đó là bản gốc (canonical), và phần này đi theo nó đúng từng tiêu đề.

Quy tắc

• Tự chạy mọi lệnh và đọc output của nó. Nếu một bước thất bại, hãy dừng lại và báo cáo. Cho người dùng biết bước nào thất bại, lệnh bạn đã chạy và dòng lỗi chính xác, sau đó là cách khắc phục trong bảng bên dưới. Đừng tự ý tìm cách workaround một bước kiểm tra thất bại (bỏ qua bước xác minh, ghim một bản build cũ hơn, đổi sang bản build khác) khi chưa hỏi người dùng.
• Chỉ cài từ các nguồn chính thức: package clearcote trên PyPI, npm hoặc NuGet, clearcote-mcp trên PyPI và npm, Docker image teamflatearth/clearcote, và các bản phát hành của clearcotelabs/clearcote-browser. SDK tự tải trình duyệt và kiểm tra SHA-256 của nó: không bao giờ tải bản build trình duyệt từ bất kỳ nơi nào khác, và không bao giờ tắt bước kiểm tra đó.
• Không bao giờ yêu cầu người dùng dán khóa giấy phép hoặc API key vào cuộc trò chuyện, và không bao giờ in, ghi log hay commit một khóa nào. Nếu người dùng vẫn dán khóa vào, đừng nhắc lại nó, đừng ghi nó vào bất kỳ file nào bạn tạo, và đề nghị họ thay khóa mới (rotate) trên trang Licenses.
• Khi một link đã hết hạn hoặc không còn hoạt động, đừng đi tìm bản sao. Các link tải xuống mà SDK dùng chỉ có hiệu lực trong thời gian ngắn và SDK xin một link mới ở mỗi lần chạy, nên hãy chạy lại lệnh thay vì dùng lại một URL. Với mọi link khác (link đăng nhập, một device code, một trang dashboard, link mà người dùng chuyển tiếp), hãy quay lại nơi đã cung cấp nó, hoặc xin người dùng một link mới. Không bao giờ chuyển sang dùng mirror, bản sao trong cache hay một package không chính thức.
• Cài vào dự án của người dùng (virtualenv, package.json hoặc .csproj của dự án), không cài global, trừ khi người dùng yêu cầu khác. Hãy hỏi trước khi sửa cấu hình nằm ngoài dự án (ví dụ cấu hình của một MCP client) và trước khi khởi động bất cứ thứ gì tốn tiền (trình duyệt hosted tính phí theo GB).
• Hoàn tất nghĩa là đã xác nhận đúng phiên bản trình duyệt, chứ không chỉ là một package đã được cài.

Lưu một file tiến độ

Tạo file clearcote-setup.json ở thư mục gốc của dự án (file này không chứa bí mật nào) và cập nhật nó sau mỗi bước kiểm tra. route là python, node, dotnet, mcp hoặc docker; build là open (không cần khóa) hoặc licensed (Miễn phí với GitHub hoặc Pro); blocked ghi lại điều bạn đang chờ.

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

Khi bắt đầu một session, hãy đọc file này và tiếp tục từ bước đầu tiên chưa hoàn tất. Chạy lại bước kiểm tra của mọi bước trước đó mà bạn dựa vào, vì giữa các session, khóa có thể hết hạn và cache có thể bị xóa.

Bước 0: chọn cách tích hợp (route) và bản build

Hỏi người dùng một lần và ghi lại câu trả lời.

• Cách tích hợp (route). Cho code của chính họ: SDK theo ngôn ngữ của dự án, Python 3.8+, Node 20+ hoặc .NET 8 (nếu chưa có dự án, hãy đề xuất Python). Cho chính bạn, agent, dùng để duyệt web: MCP server (Python 3.10+). Làm CDP endpoint cho một framework có sẵn: Docker image.
• Bản build. Bản build mở không cần khóa và không cần đăng ký: Chromium 150, mã nguồn mở (BSD-3), đủ tốt để bắt đầu. Bản build mới nhất là Chromium 154, cần khóa giấy phép: miễn phí với GitHub cho mỗi lúc một trình duyệt, hoặc Pro cho tối đa 250 trình duyệt cùng lúc.

Trình duyệt chạy trên Windows x64 và Linux x64, và Docker image cũng là x64. Trên macOS hoặc máy ARM, hãy dừng lại và nói rõ điều đó; trình duyệt hosted là lựa chọn không cần trình duyệt chạy local.

Bước 1: đã cài đặt

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

Cách kiểm tra: clearcote version (Node: npx clearcote version) in ra 0.45.0 hoặc mới hơn. Với Docker, docker image ls teamflatearth/clearcote liệt kê image.

.NET không có lệnh clearcote riêng. Hãy kiểm tra rằng dotnet list package có liệt kê Clearcote, rồi chạy mọi lệnh clearcote ở các bước 1 đến 3 dưới dạng npx -y clearcote <command> (Node 20+) hoặc pipx run clearcote <command> (Python 3.8+). Cách này không thêm gì vào dự án, và lệnh dùng chung cache trình duyệt và file giấy phép (~/.clearcote/license.key) với SDK .NET. Nếu máy không có cả Node lẫn Python, hãy đề nghị người dùng cài một trong hai: không có lệnh này thì không thể xác nhận phiên bản trình duyệt, nên cũng không thể xác minh việc cài đặt.

Bước 2: đã đặt khóa giấy phép

Với bản build mở, đánh dấu bước này là hoàn tất với evidence open build, no key. Với bản build mới nhất, khóa đi tới máy của người dùng mà không qua tay bạn:

• Nếu clearcote --help có liệt kê clearcote login --device, hãy chạy clearcote login --device (Node: npx clearcote login --device). Lệnh này in ra một link và một mã ngắn. Người dùng mở link trong trình duyệt của chính họ, đăng nhập và phê duyệt (khóa miễn phí cần tài khoản GitHub đã tạo ít nhất 30 ngày), và SDK lưu khóa vào ~/.clearcote/license.key mà không hiển thị nó.
• Nếu không, người dùng nhận một khóa trên trang Licenses và chạy clearcote login (Node: npx clearcote login) trong terminal của chính họ, rồi dán khóa vào đó: khóa chỉ hiện trên màn hình của họ, không bao giờ xuất hiện trong cuộc trò chuyện. Hãy đưa cho họ các bước đó và chờ đến khi họ báo đã xong. Họ cũng có thể tự đặt CLEARCOTE_LICENSE_KEY thay cho cách trên, trong shell profile, CI secrets, khối env trong cấu hình MCP client, hoặc môi trường Docker của họ (khi đó docker run -e CLEARCOTE_LICENSE_KEY truyền biến vào mà giá trị không xuất hiện trong lệnh).

Không bao giờ tự chạy clearcote login <key>: khóa sẽ lọt vào transcript của bạn và lịch sử shell. Cũng đừng mở file ~/.clearcote/license.key. Cách kiểm tra: clearcote info --quick hiển thị dòng Licence gồm khóa đã được che và from file hoặc from env, và đó là tất cả những gì bạn cần thấy. none (free build) nghĩa là không tìm thấy khóa nào. Khóa chỉ được đặt trong cấu hình của một MCP client hoặc trong container thì shell của bạn không nhìn thấy; hãy kiểm tra rằng tên biến có ở đó mà không in giá trị của nó ra.

Bước 3: đang chạy

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

(Node: npx clearcote install và npx clearcote info.) Cách kiểm tra: clearcote info in ra Launch test ok kèm phiên bản trình duyệt (với --json: launch.ok là true, launch.version chứa phiên bản và binary.tag chứa bản build). Với khóa miễn phí, việc này chiếm suất trình duyệt duy nhất trong chốc lát, nên hãy đóng mọi trình duyệt Clearcote khác trước. Sau đó, tùy theo route:

• SDK: chạy một script đầu tiên, clearcote_hello.py hoặc clearcote_hello.mjs. Cách kiểm tra: script in ra Example Domain và một user agent của Chrome, rồi thoát. Trên .NET, dùng tab C# của trang Playwright & Puppeteer. Seed fingerprint chính là danh tính: cùng một seed luôn cho cùng một thiết bị, nên hãy dùng mỗi tài khoản một seed.
• MCP server: đăng ký lệnh clearcote-mcp với client (hỏi trước; ghi đường dẫn đầy đủ nếu nó nằm trong virtualenv), như hướng dẫn ở trang MCP server. Khởi động lại client và gọi tool navigate của nó tới https://example.com; tool trả về URL cuối cùng và tiêu đề trang.
• Docker: khởi động một container rồi đọc log và endpoint của nó, như bên dưới.

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

Bước 4: đã xác minh

So sánh những gì bước 3 in ra với bản build mà người dùng cần có. Trong Docker, build tag là một phần của đường dẫn engine trong dòng log.

Gói Pro đang ghim một bản build cũ hơn sẽ báo bản build đó. Nếu đó không phải bản build người dùng đã chọn, hãy dừng lại và báo cho họ. Khi phiên bản khớp, hãy đặt verified thành hoàn tất kèm phiên bản, và cho người dùng biết: route, phiên bản SDK, bản build nào đang chạy và phiên bản trình duyệt chính xác của nó, script đầu tiên nằm ở đâu và cách chạy nó, nơi lưu khóa (file hay biến môi trường, không bao giờ nêu chính khóa đó), và tài liệu.

Khi một bước thất bại

Tùy chọn, chỉ khi người dùng muốn

• Một proxy. Truyền một proxy Playwright và geoip=True, để múi giờ và ngôn ngữ khớp theo IP đầu ra của proxy. Xem Proxy & geoip.
• Một trình duyệt cho chính bạn, agent, qua MCP, nếu đó chưa phải route đã chọn: pip install -U clearcote-mcp (Python 3.10+), rồi đăng ký nó như ở bước 3. Với bản build mới nhất, server tìm thấy khóa đã lưu ở bước 2, hoặc người dùng tự thêm CLEARCOTE_LICENSE_KEY vào env của server đó.
• Không có máy để chạy. Trình duyệt hosted khởi động cùng trình duyệt đó trên server của Clearcote chỉ với một lệnh gọi API. Chúng cần API key và tính phí theo GB, nên hãy hỏi trước.

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

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.