示例

常见 Clearcote 工作流的示例代码，可直接复制粘贴。先从最贴合你需求的最小示例开始，确有需要时再添加选项。

示例同时给出 Python、Node 和 .NET SDK 的写法（pip install clearcote / npm install clearcote / dotnet add package Clearcote）。.NET SDK 覆盖了核心工作流——启动、持久化 context、serve、代理、geoip（Geoip = true）和 canvas bridge；拟人化输入通过显式调用 HumanClickAsync / HumanTypeAsync 实现，而不是一个启动参数。已保存的 Profile、Widevine 和浏览器内 agent 目前仅支持 Python & Node。

除非设置了许可证密钥，否则每个示例运行的都是开源版构建；设置密钥后（clearcote login、CLEARCOTE_LICENSE_KEY 或 license_key=），同样的代码会运行最新的授权版构建。GitHub 免费版同一时间只能运行一个浏览器。有一点常常让人意外：引擎从不转发 console 事件或页面错误事件，因此 page.on("console") 按设计收不到任何内容——请在页面内收集输出，再用 page.evaluate() 读回。

1. 从 SDK 启动经过校验的浏览器

SDK 会在首次使用时下载浏览器并做 SHA-256 校验——默认是开源版构建，设置了密钥时则是最新的授权版构建。它返回的是普通的 Playwright 对象，因此其余自动化代码的写法都和你熟悉的一样。（从 0.23 起，同步 Python 和 Node 中的 launch() 运行在一个一次性 Profile 上，new_context() 返回的也是同一个 Profile；如果你需要相互隔离的 context，请传入 ephemeral_profile=False / ephemeralProfile: false。）

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. 为任意框架提供隐匿的 CDP 端点

serve() 会把 Clearcote 作为常驻的 CDP 端点运行，并返回一个 cdp_url。它直接启动浏览器二进制文件——不带 --enable-automation——任何 Playwright、Puppeteer、browser-use、Crawl4AI 或 Stagehand 客户端都能通过 CDP 接入，无需改动代码。在 contexts[0] 中打开页面即可使用所提供的 Profile；在浏览器上调用 new_page() 则会创建一个单独的、隔离的 context。如果是 AI agent，把 Claude / Cursor / Cline 指向 clearcote-mcp 服务器即可（pip install clearcote-mcp，或 npx -y clearcote-mcp，后者需要 Python 3.10+）。在 shell 中，clearcote serve 会运行同样的端点，还能为每个连接分配各自的身份——参见部署。

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. 每个账号一个稳定的身份

使用确定性的种子（seed）和持久化的用户数据目录。种子让浏览器身份保持稳定；Profile 目录则保存 cookie、本地存储、权限和会话状态。

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. 让时区、语言、位置和 WebRTC 与代理保持一致

启用 geoip 后，Clearcote 会经由代理查出代理的出口 IP，并根据 GeoIP 数据库（首次使用时下载，约 50 MB）填充尚未设置的时区、语言、位置和 WebRTC 地址。这样就不必为每个代理手动匹配时区。如果在 CLEARCOTE_GEOIP_TIMEOUT_SECONDS（默认 20）内无法解析出地区，启动会以 GeoipError 中止，而不会沿用本机的时钟和语言启动；如果仍要启动，请同时设置 timezone 和 accept_language。在 .NET 中，请设置 Geoip = true。

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. 保存并复用命名 Profile

如果你需要一个可供多个脚本共享的命名身份画像（persona），已保存的 Profile 就很有用。不要把机密信息提交到源码管理中：Profile 文件是明文存储的。

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. 只在需要的地方使用 canvas bridge

bridge 模式可以按可注册域名限定作用范围。下面的示例只在列出的源上桥接 canvas/WebGL 读回，其他地方一律使用本地渲染。把 GPU 字符串设为渲染端 GPU 的值（即 bridge 服务器打印出的 renderer），这样报告的 GPU 就与桥接得到的像素相符。启用 bridge 后，渲染进程会在没有 Chromium 沙箱的情况下运行（无论哪种模式，SDK 都会为整个浏览器加上 --no-sandbox），因此只在需要它的会话中启用 bridge。

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

请先启动 bridge 主机。服务器命令、网络方面的建议以及回退行为，参见 Canvas bridge。

7. 用 Widevine 播放 DRM 视频

Clearcote 自带 EME 的底层支持，但从不附带 Google 的专有 CDM。widevine 会从 Google 的组件服务器获取一次 Widevine CDM，校验后写入 Profile 并启用——这样 requestMediaKeySystemAccess('com.widevine.alpha') 就能正常 resolve，DRM 流也能播放，就像真实的 Chrome 一样。

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

按设计需主动开启——安装包从不分发 Google 的 CDM，一次性的获取由你自己触发（缓存在 ~/.clearcote/WidevineCdm 下）。在同步 Python 中可配合 launch() 和 launch_persistent_context() 使用；在 Node 中请像上面那样使用 launchPersistentContext()（launch() 的 TypeScript 类型目前还没有声明 widevine）。不适用于 Python 异步版的 launch()（它是无痕模式），也不适用于 .NET。安全级别为软件级（L3）。一个自称 Google Chrome 却无法响应 Widevine 查询的浏览器，任何页面都能读出这一点，这正是要开启它的原因。参见 Widevine & DRM。

8. 在 CI 中预取浏览器

在测试套件开始之前预热经过校验的浏览器缓存。这样一来，问题会在并行任务开始之前就尽早暴露。没有密钥时获取的是开源版构建；设置了 CLEARCOTE_LICENSE_KEY 时获取的则是授权版构建。GitHub 免费版的密钥同一时间只能运行一个浏览器，因此请串行执行浏览器测试，或者使用 Pro。

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. 运行 agent 任务并保留执行轨迹

浏览器内 agent 需要主动开启。给它提供一个持久化的 Profile 目录、一个兼容 OpenAI 的端点/密钥，以及有上限的步数，这样每次运行都可复现、可审查。

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. 不用 SDK，直接使用 Playwright

SDK 用起来最顺手，但开源版构建本身就是一个普通的 Chromium 二进制文件，可以直接从 Playwright 或 Puppeteer 启动。授权版构建则离不开 SDK——SDK 持有引擎在启动时校验的许可证令牌。下面额外添加的参数，就是 SDK 原本会替你加上的默认参数。

javascript

import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

先让示例保持精简。只有当你的目标工作流确实需要时，再加入 Profile 导入、canvas bridge、agent 模式或手动 GPU 覆盖。