Local hoặc cloud: một SDK
Cùng một launch() khởi động Clearcote trên máy của bạn cũng khởi động nó trên server của chúng tôi. Truyền cloud=True (Python) hoặc cloud: true (Node), hoặc đặt CLEARCOTE_CLOUD=1, và bạn nhận lại đúng Browser của Playwright như trước, được kết nối tới một trình duyệt hosted. Phần còn lại của script giữ nguyên.
Chạy script trên cloud
Bạn cần SDK 0.34.0 trở lên và một API key từ trang API keys. Đặt key vào CLEARCOTE_API_KEY, rồi:
from clearcote import launch
browser = launch(cloud=True, fingerprint="acct-1", country="de")
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
browser.close() # ends the cloud sessionĐằng sau lời gọi, SDK tạo một phiên bằng POST /api/v1/browsers, kết nối tới nó qua CDP và thiết lập humanize giống như khi khởi chạy local. Hãy mở trang trong browser.contexts[0]: context này mang profile của phiên. browser.new_page() cũng dùng được, nhưng mở một context riêng không có cookie của profile (SDK vẫn tắt viewport giả lập của Playwright cho nó, như khi chạy local).
Phiên hosted đằng sau trình duyệt nằm ở browser.cloud_session trong Python và cloudSessionOf(browser) trong Node (cũng có browser.cloudSession): đó là phản hồi khi tạo phiên, với id, worker và expiresAt, trừ connectUrl chỉ dùng một lần. Dùng id với Cloud client cho bàn giao và bản ghi hình & sự kiện.
Chuyển đổi bằng biến môi trường
Bỏ cloud khỏi lời gọi thì môi trường sẽ quyết định, nhờ vậy cùng một script chạy local trên laptop của bạn và chạy trên cloud ở môi trường production mà không phải sửa code.
| Biến | Ý nghĩa |
|---|---|
CLEARCOTE_CLOUD | 1, true hoặc yes: một launch() không có tham số cloud sẽ khởi động trình duyệt cloud. Giá trị khác, hoặc không đặt: một trình duyệt local. |
CLEARCOTE_API_KEY | Key cc_live_… của bạn. Cần cho mọi lời gọi cloud. |
CLEARCOTE_API_URL | API để giao tiếp. Mặc định https://www.clearcotelabs.com; chỉ đổi khi dùng một control plane cho phát triển. Phải là https://; http:// thường chỉ được chấp nhận cho chính máy này (localhost, 127.0.0.1, ::1), để key không bao giờ đi qua mạng mà không được mã hóa. |
export CLEARCOTE_API_KEY=cc_live_...
python scrape.py # a local browser
CLEARCOTE_CLOUD=1 python scrape.py # the same script on a hosted browserTham số tường minh luôn thắng: cloud=False / cloud: false khởi chạy local bất kể CLEARCOTE_CLOUD nói gì.
Tùy chọn
Ở chế độ cloud, launch() nhận các tùy chọn của POST /api/v1/browsers. Node dùng nguyên tên của API; Python dùng snake_case, và SDK đổi tên giúp bạn. Quy tắc đầy đủ của từng tùy chọn có trong tài liệu tham khảo Trình duyệt hosted.
| Python | Node và API | Ý nghĩa |
|---|---|---|
identity | identity | Một nhãn cho mỗi tài khoản: cùng thiết bị và cùng IP dân cư chừng nào IP đó còn online. |
fingerprint | fingerprint | Seed của thiết bị. Cùng seed cho ra cùng device profile. |
light_stealth | lightStealth | Mặc định true. |
platform | platform | windows, macos, linux hoặc android. |
brand | brand | Chrome, Edge, Opera hoặc Vivaldi. |
timezone | timezone | Tên IANA, ví dụ Europe/Berlin. |
locale, accept_language | locale | Accept-Language, ví dụ de-DE,de. accept_language (Node: acceptLanguage) là tên gọi khác. |
geoIdentity | geoIdentity | Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event. |
geoip | geoip | Múi giờ và ngôn ngữ đi theo IP đầu ra. |
proxy | proxy | "managed" (mặc định), { server, username, password }, hoặc một URL như http://user:pass@host:8080, SDK sẽ tách nó thành object đó giúp bạn. |
country | country | Quốc gia đầu ra trong pool dân cư được quản lý. |
state | state | Bang hoặc vùng đầu ra trong pool được quản lý. Cần country. |
city | city | Thành phố đầu ra trong pool được quản lý. Cần state. |
proxy_session | proxySession | Nhãn sticky: cùng nhãn sẽ nhận lại cùng IP đầu ra về sau. |
timeout_sec | timeoutSec | Giới hạn cứng cho độ dài phiên, tính bằng giây. |
idle_timeout_sec | idleTimeoutSec | Kết thúc phiên sau khoảng thời gian này mà không có lệnh CDP nào. |
max_gb | maxGb | Dừng phiên sau lượng lưu lượng này. |
headless | headless | Mặc định true. Với false (một cửa sổ thật), trang báo cáo màn hình của chính server, không phải kích thước màn hình của danh tính. |
humanize | humanize | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input". |
keep_alive | keepAlive | Giữ trình duyệt chạy sau khi bạn ngắt kết nối. |
version | version | Chạy một bản phát hành Clearcote cụ thể. |
profile | profile | Một cloud profile: "name" để tải nó, { name, persist: true } để lưu ngược lại vào đó. |
url | url | Được mở ở tab đầu tiên trước khi bạn nhận được trình duyệt. |
adblock | adblock | Từ chối các host quảng cáo và tracker đã biết trước khi chúng tải. |
solve_sliders | solveSliders | Mặc định true: các thử thách “slide to verify” được kéo giúp bạn. false tắt việc này; SDK 0.35.0 trở về trước từ chối tên này (với chúng tính năng luôn bật). |
solve_checkboxes | solveCheckboxes | Mặc định true: các ô “verify you are human” được click giúp bạn. false tắt việc này; SDK 0.36.2 trở về trước từ chối tên này (với chúng tính năng luôn bật). |
solve_press_hold | solvePressHold | Mặc định true: các nút xác minh “press and hold” được giữ giúp bạn cho đến khi chúng báo xong. false tắt việc này; SDK 0.49.0 trở về trước từ chối tên này (với chúng tính năng luôn bật). |
challenge_service | challengeService | Mặc định tắt. true, hoặc { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur } (Python cũng nhận max_solves, max_spend_eur, api_key): những thử thách mà các thao tác miễn phí không xử lý được sẽ được gửi tới một dịch vụ giải, bằng key của bạn hoặc của chúng tôi. Cần SDK 0.38.0 trở lên. |
record | record | Ghi hình phiên thành MP4. |
note | note | Nhãn của bạn cho phiên. |
worker | worker | Khởi động trên cùng server với một phiên trước đó. |
humanize | humanize | Không đặt hoặc True (SDK 0.44.0+): humanize của chính SDK cho chuột, bàn phím và cuộn, như khi khởi chạy local, còn của server thì tắt. False: không dùng cái nào. Trước 0.44.0, không đặt nghĩa là để trình duyệt hosted lo, và nó chỉ di chuyển chuột. |
show_cursor | showCursor | Hiện một chấm đỏ đi theo chuột, để theo dõi hoặc debug. Chạy ở phía SDK, giống humanize. |
api_key, api_url | apiKey, apiUrl | Tài khoản và API server cho lần khởi chạy này. Mặc định CLEARCOTE_API_KEY và CLEARCOTE_API_URL. Không bao giờ được gửi đi như tùy chọn. |
timeout, slow_mo | timeout, slowMo | Các tùy chọn riêng của Playwright cho kết nối CDP, tính bằng mili giây. Không gửi tới API. |
Điều gì giữ nguyên, điều gì khác
Giữ nguyên:
- Bạn nhận được một object Playwright.
launch()trả về mộtBrowservàlaunch_persistent_context()trả về mộtBrowserContext, đồng bộ hoặc bất đồng bộ, y hệt như khi chạy local. - Nhập liệu giống người được bật mặc định. Từ SDK 0.44.0, khởi chạy trên cloud sẽ humanize ngay trong SDK, như khởi chạy local với
humanize=True: chuột di chuyển theo đường đi giống người, phím được gõ từng phím một, cuộn theo từng nấc con lăn, và các cú click theo tọa độ do chính engine phát lại. Mỗi bước đều đi qua mạng, nên cách này chậm hơn nhập liệu thông thường; truyềnhumanize=Falseđể có nhập liệu đơn giản, nhanh. Dù theo cách nào, lần khởi chạy cũng tắt chuyển động chuột riêng của trình duyệt hosted, để chỉ một bên di chuyển con trỏ. Các client kết nối không qua SDK vẫn giữ chuyển động của trình duyệt hosted: nó di chuyển chuột trên server, giữ mỗi cú click trong khoảng thời gian nhấn của người thật và chia các lần cuộn lớn thành những nấc con lăn trọn vẹn. - Cùng một engine. Các phiên hosted chạy đúng những bản phát hành Clearcote mà SDK tải về, nên các tùy chọn persona có cùng ý nghĩa ở cả hai nơi, và
versionghim cùng một bản build.
Khác biệt:
- Tùy chọn chỉ dành cho local bị từ chối.
executable_path,args,user_data_dir,extensions,ignore_default_argsvà các tùy chọn khác chỉ có ý nghĩa với một binary trên máy bạn sẽ ném raValueError("<name> is not available for cloud browsers")trong Python (một lỗi với cùng thông báo trong Node) thay vì bị bỏ qua. - Profile thay cho thư mục. Trình duyệt cloud không có thư mục nào trên ổ đĩa của bạn. Để giữ cookie và bộ nhớ trang web giữa các lần chạy, hãy dùng một cloud profile có tên (xem bên dưới).
profilenghĩa là một cloud profile. Khi chạy local,profilechọn một device profile đã thu thập ("auto"). Ở chế độ cloud, nó đặt tên cho một cloud profile đã lưu: cookie, localStorage và IndexedDB.- Mặc định của bản hosted. Một phiên cloud bắt đầu từ các mặc định của bản hosted: một persona Windows,
lightStealthbật, một seed, múi giờ và ngôn ngữ đi theo IP đầu ra, module Widevine mà Google Chrome có, chuyển động chuột giống người, và một IP đầu ra dân cư trừ khi bạn truyềnproxycủa riêng mình. - Đóng.
browser.close()ngắt kết nối, và phiên kết thúc khi client của nó rời đi; SDK cũng dừng phiên qua API để chắc chắn. Vớikeep_alive/keepAlive, trình duyệt sẽ tiếp tục chạy, cho đến khi bạn dừng nó hoặc một giới hạn dừng nó. - Giới hạn của bản hosted. Không có
file://, không extension, không mạng riêng, file tải xuống được lấy qua kết nối (xem Download file), vàpage.on("console")không phát ra gì. Xem các giới hạn. - Tính phí. Trình duyệt cloud được tính phí như mọi phiên hosted, theo GB lưu lượng, trừ vào số dư trả trước của bạn. Trình duyệt local không tốn gì ngoài giấy phép của bạn.
Context bền vững trên một cloud profile
launch_persistent_context() với cloud=True nhận tên profile thay vì thư mục. Nó trả về context đầu tiên của một phiên cloud được khởi động với profile: { name, persist: true }: phiên tải profile, và việc đóng context sẽ kết thúc phiên và lưu cookie cùng bộ nhớ trang web ngược lại vào profile.
from clearcote import launch_persistent_context
ctx = launch_persistent_context(cloud=True, profile="shop-account", country="de")
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://shop.example.com/account")
ctx.close() # ends the session and saves "shop-account"Truyền user_data_dir cùng với cloud=True sẽ ném ra một ValueError chỉ bạn sang profile=. Mỗi lúc chỉ một phiên được lưu vào một profile. Để tạo profile từ cookie bạn đã có, hãy dùng đồng bộ cookie.
Cloud client
Mọi thứ khác mà API làm đều có client: phiên, lượt chạy agent, profile và webhook. Nó đọc CLEARCOTE_API_KEY và CLEARCOTE_API_URL, hoặc nhận chúng làm tham số. Client Python chỉ dùng thư viện chuẩn; AsyncCloud có cùng các method cho asyncio.
from clearcote.cloud import Cloud, CloudError
cloud = Cloud() # or Cloud(api_key="cc_live_...", base_url="https://www.clearcotelabs.com")
session = cloud.browsers.create(country="de", record=True)
print(session["id"], session["connectUrl"])
try:
cloud.browsers.stop(session["id"])
except CloudError as e:
print(e.status, e.code, e.message)| Namespace | Method |
|---|---|
browsers | create(**options), get(id), list(status=None, note=None, limit=None, before=None), stop(id), live(id, control=False), share(id, control=None, minutes=None, recording=None), handoff(id, reason=None, timeout_sec=None), handoff_done(id), wait_handoff(id, timeout=None, poll=2.0), events(id, after=0, limit=None), recording_url(id), download_recording(id, path) |
runs | create(task, url=None, schema=None, secrets=None, wait=True, timeout=None, poll=1.5, on_update=None, **options), get(id), list(limit=None, before=None), cancel(id), wait(id, timeout=None, poll=1.5, on_update=None) |
profiles | list(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …) |
webhooks | create(url, events=None, description=None), list(), delete(id), test(id) |
Mỗi method trả về nguyên JSON của endpoint: một dict trong Python, một object thuần trong Node. Các lời gọi liệt kê trả về object của API, ví dụ { balanceEur, sessions } hoặc { runs }, chứ không phải một danh sách trơn. Các khoảng thời gian do chính SDK chờ (timeout, poll) tính bằng giây trong cả hai ngôn ngữ.
Node có cùng các method ở dạng camelCase (handoffDone, waitHandoff, importCookies, recordingUrl, downloadRecording), với các tham số tùy chọn gom trong một object: live(id, { control }), events(id, { after, limit }), runs.create(task, { url, schema, country, … }), importCookies(name, cookies, { mode }), webhooks.create(url, { events }). Một lời gọi thất bại sẽ ném ra CloudError với status HTTP (0 khi không kết nối được tới API), code của API và message của nó; các mã được liệt kê trong Lỗi. Một lần chờ vượt quá timeout của nó sẽ ném ra CloudTimeoutError thay vào đó, với last chứa trạng thái cuối cùng SDK đọc được; lượt chạy hoặc việc bàn giao vẫn tiếp tục trên server. Một tùy chọn sai sẽ ném ra ValueError trong Python (một Error trong Node) trước khi gửi bất cứ thứ gì. SDK cũng export verify_webhook / verifyWebhook cho chữ ký webhook.
Lệnh clearcote cloud
Lệnh clearcote đi kèm SDK (pip install clearcote, hoặc npx clearcote) có một nhóm cloud cho cùng API đó:
# an agent run: prints the result when it finishes
clearcote cloud run "Find the price of the cheapest plan" --url https://example.com/pricing \
[--schema schema.json] [--secret name=value]... [--secret-domain name=host]... [--handoff] [--record] [--json]
# sessions
clearcote cloud sessions
clearcote cloud stop <id>
clearcote cloud events <id>
clearcote cloud recording <id> -o session.mp4
# copy cookies into a cloud profile (--domain or --all-domains is required)
clearcote cloud profile sync <name> (--from-profile DIR | --from-cdp URL | --from-file state.json | --login URL) \
(--domain example.com... | --all-domains) [--replace]
# webhooks
clearcote cloud webhooks add https://example.com/hooks/clearcote [--event run.finished]...
clearcote cloud webhooks list
clearcote cloud webhooks rm <id>
clearcote cloud webhooks test <id>Mọi lệnh đều nhận --json để in phản hồi của API thay vì bản tóm tắt. run chờ kết quả và chỉ thoát với 0 khi lượt chạy ở trạng thái succeeded (1 trong trường hợp khác, 2 khi dùng sai lệnh), nên dùng được trong shell script. Không có -o, recording lưu vào <id>.mp4. Chạy clearcote cloud --help để xem mọi flag.
Mỗi lệnh có trang riêng: lượt chạy, bản ghi hình & sự kiện, đồng bộ profile và webhook.
MCP: trình duyệt cloud cho trợ lý AI của bạn
MCP server có cùng công tắc này. Với CLEARCOTE_CLOUD=1 và CLEARCOTE_API_KEY trong env của nó, trình duyệt dùng chung mà các tool của nó điều khiển sẽ là trình duyệt cloud. Khi có đặt API key, nó còn có thêm tool run_task giao trọn một tác vụ cho một lượt chạy agent và trả về JSON kết quả.
{
"mcpServers": {
"clearcote": {
"command": "npx",
"args": ["-y", "clearcote-mcp"],
"env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
}
}
}