本地或云端:同一个 SDK
在你的机器上启动 Clearcote 的同一个 launch(),也能在我们的服务器上启动它。传入 cloud=True(Python)或 cloud: true(Node),或设置 CLEARCOTE_CLOUD=1,你拿回的仍是同样的 Playwright Browser,只是连接到了一个托管浏览器。脚本的其余部分保持不变。
在云端运行脚本
你需要 SDK 0.34.0 或更高版本,以及在“API keys”页面创建的 API 密钥。把密钥放进 CLEARCOTE_API_KEY,然后:
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在这个调用背后,SDK 用 POST /api/v1/browsers 创建一个会话,通过 CDP 连接上去,并像本地启动那样设置好 humanize。请在 browser.contexts[0] 中打开页面:它带有会话的 Profile。browser.new_page() 也能用,但会打开一个不含该 Profile Cookie 的独立上下文(SDK 仍会为它关闭 Playwright 的模拟视口,与本地一致)。
浏览器背后的托管会话,在 Python 中是 browser.cloud_session,在 Node 中是 cloudSessionOf(browser)(也可用 browser.cloudSession):即创建时的响应,包含 id、worker 和 expiresAt,但去掉了一次性的 connectUrl。用这个 id 配合 Cloud 客户端,即可进行人工交接,以及使用录像与事件。
用环境变量切换
调用中不写 cloud 时由环境决定,因此同一个脚本无需改代码,就能在笔记本上本地运行、在生产环境中跑在云端。
| 变量 | 含义 |
|---|---|
CLEARCOTE_CLOUD | 1、true 或 yes:不带 cloud 参数的 launch() 会启动云端浏览器。其他值或未设置:启动本地浏览器。 |
CLEARCOTE_API_KEY | 你的 cc_live_… 密钥。每次云端调用都需要。 |
CLEARCOTE_API_URL | 要访问的 API。默认 https://www.clearcotelabs.com;仅在使用开发用控制平面时才需要修改。必须是 https://;普通的 http:// 只接受本机地址(localhost、127.0.0.1、::1),这样密钥绝不会以未加密的形式经过网络。 |
export CLEARCOTE_API_KEY=cc_live_...
python scrape.py # a local browser
CLEARCOTE_CLOUD=1 python scrape.py # the same script on a hosted browser显式参数始终优先:无论 CLEARCOTE_CLOUD 是什么,cloud=False / cloud: false 都会在本地启动。
选项
在云端模式下,launch() 接受 POST /api/v1/browsers 的选项。Node 直接使用 API 的名称;Python 使用 snake_case,由 SDK 负责转换名称。每个选项的完整规则见托管浏览器参考。
| Python | Node 与 API | 含义 |
|---|---|---|
identity | identity | 每个账号一个标签:相同的设备,以及只要该 IP 在线就保持相同的住宅 IP。 |
fingerprint | fingerprint | 设备种子(seed)。相同的种子得到相同的设备配置。 |
light_stealth | lightStealth | 默认 true。 |
platform | platform | windows、macos、linux 或 android。 |
brand | brand | Chrome、Edge、Opera 或 Vivaldi。 |
timezone | timezone | IANA 名称,例如 Europe/Berlin。 |
locale, accept_language | locale | Accept-Language,例如 de-DE,de。accept_language(Node:acceptLanguage)是别名。 |
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 | 时区和语言跟随出口 IP。 |
proxy | proxy | "managed"(默认)、{ server, username, password },或 http://user:pass@host:8080 这样的 URL,SDK 会替你拆成该对象。 |
country | country | 托管住宅代理池中的出口国家。 |
state | state | 托管代理池中的出口州或地区。需要 country。 |
city | city | 托管代理池中的出口城市。需要 state。 |
proxy_session | proxySession | 固定(sticky)标签:之后用同一个标签会拿回同一个出口 IP。 |
timeout_sec | timeoutSec | 会话时长的硬性上限,单位为秒。 |
idle_timeout_sec | idleTimeoutSec | 超过这么久没有 CDP 命令就结束会话。 |
max_gb | maxGb | 流量达到这个量后停止会话。 |
headless | headless | 默认 true。设为 false(真实窗口)时,页面报告的是服务器自身的显示器,而不是身份的屏幕尺寸。 |
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 | 断开连接后让浏览器继续运行。 |
version | version | 运行指定版本的 Clearcote。 |
profile | profile | 云端 Profile:"name" 表示加载它,{ name, persist: true } 表示加载后还会保存回去。 |
url | url | 在你拿到浏览器之前,先在第一个标签页中打开。 |
adblock | adblock | 在加载之前拒绝已知的广告和跟踪主机。 |
solve_sliders | solveSliders | 默认 true:自动为你拖动滑块验证。设为 false 可关闭;SDK 0.35.0 及更早版本不接受该名称(对它们始终开启)。 |
solve_checkboxes | solveCheckboxes | 默认 true:自动为你点击“verify you are human”复选框。设为 false 可关闭;SDK 0.36.2 及更早版本不接受该名称(对它们始终开启)。 |
solve_press_hold | solvePressHold | 默认 true:自动为你按住“press and hold”验证按钮,直到其报告完成。设为 false 可关闭;SDK 0.49.0 及更早版本不接受该名称(对它们始终开启)。 |
challenge_service | challengeService | 默认关闭。true,或 { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur }(Python 也接受 max_solves、max_spend_eur、api_key):免费操作处理不了的验证会交给验证求解服务,使用你的密钥或我们的密钥。需要 SDK 0.38.0 或更高版本。 |
record | record | 将会话录制为 MP4。 |
note | note | 你给会话起的标签。 |
worker | worker | 在与之前某个会话相同的服务器上启动。 |
humanize | humanize | 未设置或 True(SDK 0.44.0+):由 SDK 自己的 humanize 处理鼠标、键盘和滚动,与本地启动相同,服务器端的则关闭。False:都不用。0.44.0 之前,未设置时交给托管浏览器处理,它只模拟鼠标移动。 |
show_cursor | showCursor | 显示一个跟随鼠标的红点,便于观察或调试。与 humanize 一样在 SDK 端实现。 |
api_key, api_url | apiKey, apiUrl | 本次启动使用的账号和 API 服务器。默认取 CLEARCOTE_API_KEY 和 CLEARCOTE_API_URL。不会作为选项发送。 |
timeout, slow_mo | timeout, slowMo | Playwright 自身针对 CDP 连接的选项,单位为毫秒。不会发送给 API。 |
哪些不变,哪些不同
不变的:
- 你拿到的是 Playwright 对象。
launch()返回Browser,launch_persistent_context()返回BrowserContext,同步或异步都与本地完全一样。 - 拟人化输入默认开启。从 SDK 0.44.0 起,云端启动会在 SDK 中进行拟人化,与本地使用
humanize=True启动一样:鼠标沿着类似人的轨迹移动,按键逐个输入,滚动按滚轮刻度进行,按坐标的点击由引擎自己回放。每一步都要经过网络,因此比普通输入慢;如需简单快速的输入,请传入humanize=False。无论哪种情况,启动时都会关闭托管浏览器自带的鼠标移动,确保只有一方在移动光标。不通过 SDK 连接的客户端保留托管浏览器自带的拟人化:它在服务器上移动鼠标,每次点击按住与真人按压相当的时长,并把大幅滚动拆成完整的滚轮刻度。 - 同一个引擎。托管会话运行的就是 SDK 下载的那些 Clearcote 版本,所以身份画像(persona)选项在两边含义相同,
version固定的也是同一个构建。
不同的:
- 仅限本地的选项会被拒绝。
executable_path、args、user_data_dir、extensions、ignore_default_args以及其他只对你本机上的二进制文件有意义的选项,在 Python 中会抛出ValueError("<name> is not available for cloud browsers")(Node 中是带相同消息的错误),而不是被忽略。 - 用 Profile 代替文件夹。云端浏览器在你的磁盘上没有文件夹。要在多次运行之间保留 Cookie 和网站存储,请使用一个有名称的云端 Profile(见下文)。
profile指的是云端 Profile。在本地,profile用于选择一个采集的设备配置("auto")。在云端模式下,它指定一个已保存的云端 Profile:Cookie、localStorage 和 IndexedDB。- 托管默认值。云端会话从托管默认值开始:Windows 身份画像、开启
lightStealth、跟随出口 IP 的种子、时区和语言、Google Chrome 自带的 Widevine 模块、拟人化的鼠标移动,以及住宅出口 IP(除非你传入自己的proxy)。 - 关闭。
browser.close()会断开连接,客户端离开后会话即结束;为保险起见,SDK 还会通过 API 停止它。使用keep_alive/keepAlive时,浏览器会继续运行,直到你停止它或达到某个限制。 - 托管限制。不支持
file://、扩展和私有网络,下载要通过连接获取(见“下载文件”),且page.on("console")不会有输出。参见限制。 - 计费。云端浏览器与其他托管会话一样计费,按 GB 流量从你的预付余额中扣除。本地浏览器除许可证外不产生任何费用。
基于云端 Profile 的持久上下文
带 cloud=True 的 launch_persistent_context() 接受的是 Profile 名称而不是文件夹。它返回一个以 profile: { name, persist: true } 启动的云端会话的第一个上下文:会话会加载该 Profile,关闭上下文时会结束会话,并把 Cookie 和网站存储保存回去。
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"同时传入 user_data_dir 和 cloud=True 会抛出 ValueError,并提示你改用 profile=。同一时间只能有一个会话保存到某个 Profile。要用你已有的 Cookie 创建 Profile,请使用 Cookie 同步。
Cloud 客户端
API 的其他所有功能都有对应的客户端:会话、智能体任务、Profile 和 Webhook。它读取 CLEARCOTE_API_KEY 和 CLEARCOTE_API_URL,也可以作为参数传入。Python 客户端只用标准库;AsyncCloud 为 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)| 命名空间 | 方法 |
|---|---|
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) |
每个方法都原样返回端点的 JSON:Python 中是 dict,Node 中是普通对象。列表类调用返回的是 API 的对象,例如 { balanceEur, sessions } 或 { runs },而不是一个裸列表。SDK 自己等待的时长(timeout、poll)在两种语言中都以秒为单位。
Node 提供同样的 camelCase 方法(handoffDone、waitHandoff、importCookies、recordingUrl、downloadRecording),可选参数放在一个对象里:live(id, { control })、events(id, { after, limit })、runs.create(task, { url, schema, country, … })、importCookies(name, cookies, { mode })、webhooks.create(url, { events })。调用失败时会抛出 CloudError,带有 HTTP status(无法连接 API 时为 0)、API 的 code 及其 message;错误码列在“错误”中。等待超过其 timeout 时则抛出 CloudTimeoutError,其 last 保存 SDK 最后读到的状态;任务或人工交接会在服务器上继续进行。无效选项会在发送任何内容之前抛出错误:Python 中是 ValueError,Node 中是 Error。SDK 还导出了用于 Webhook 签名的 verify_webhook / verifyWebhook。
clearcote cloud 命令
SDK 自带的 clearcote 命令(pip install clearcote 或 npx clearcote)有一个 cloud 命令组,对应同一个 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>每个命令都接受 --json,用来输出 API 的原始响应而不是摘要。run 会等待结果,只有任务状态为 succeeded 时才以 0 退出(否则为 1,用法错误为 2),因此可以用在 shell 脚本里。不带 -o 时,recording 保存到 <id>.mp4。运行 clearcote cloud --help 查看所有参数。
每个命令都有单独的页面:智能体任务、录像与事件、Profile 同步和 Webhook。
MCP:为你的 AI 助手提供云端浏览器
MCP 服务器也有同样的开关。在其 env 中设置 CLEARCOTE_CLOUD=1 和 CLEARCOTE_API_KEY 后,它的工具所驱动的共享浏览器就是云端浏览器。设置了 API 密钥后,它还会多一个 run_task 工具,可以把整个任务交给一次智能体任务执行,并返回结果 JSON。
{
"mcpServers": {
"clearcote": {
"command": "npx",
"args": ["-y", "clearcote-mcp"],
"env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
}
}
}