面向智能体与 LLM

Clearcote 的组织方式让自动化工具也能像人一样轻松地浏览、集成和参与贡献。要替别人安装 Clearcote？请按照安装手册逐步操作。

面向编程智能体的安装手册

如果你是受托为他人配置 Clearcote 的 AI 编程智能体（Claude Code、Codex、Cursor、Windsurf、Cline 等），请按顺序完成下面的步骤：已安装（installed）、已设置许可证（licence_set）、运行正常（running）、已验证（verified）。每个步骤都有一项检查，只有检查通过，该步骤才算完成。把进度记录在一个文件里，这样无论是新的会话，还是第二天回来的用户，都能从第一个未完成的步骤继续，而不必从头开始。同一份安装手册也是位于 /setup.md 的一个 Markdown 文件，也就是首页提供、供粘贴给智能体的地址；它是权威版本，本节与它的标题一一对应。

规则

• 每条命令都由你自己运行，并阅读它的输出。某个步骤失败时，停下来并报告。告诉用户哪个步骤失败了、你运行的命令以及确切的报错行，再给出下表中的解决办法。未经询问，不要擅自变通处理失败的检查（跳过验证、固定旧版构建、切换构建）。
• 只从官方来源安装：PyPI、npm 或 NuGet 上的 clearcote 包，PyPI 和 npm 上的 clearcote-mcp，Docker 镜像 teamflatearth/clearcote，以及 clearcotelabs/clearcote-browser 的发布版本。SDK 会自行下载浏览器并校验其 SHA-256：切勿从其他任何地方获取浏览器构建，也切勿关闭这项校验。
• 切勿让用户把许可证密钥或 API 密钥粘贴到对话中，也切勿打印、记录到日志或提交（commit）任何密钥。如果用户还是粘贴了，不要复述它，不要把它写进你创建的任何文件，并建议用户在“Licenses”页面轮换该密钥。
• 链接过期或失效时，不要去找副本。SDK 使用的下载链接有效期很短，每次运行都会重新申请，所以请重新运行命令，而不是复用某个 URL。对于其他链接（登录链接、设备码、控制台页面、用户转发的链接），请回到它的来源，或者请用户提供新链接。切勿退而使用镜像、缓存副本或非官方的包。
• 安装到用户的项目中（项目的虚拟环境、package.json 或 .csproj），而不是全局安装，除非用户另有要求。修改项目之外的配置（例如 MCP 客户端的配置）之前，以及启动任何会产生费用的东西（托管浏览器按 GB 计费）之前，都要先询问用户。
• “完成”指已确认确切的浏览器版本，而不是某个包装好了。

维护进度文件

在项目根目录写入 clearcote-setup.json（其中不含任何机密信息），并在每次检查后更新它。route 取值为 python、node、dotnet、mcp 或 docker；build 取值为 open（无密钥）或 licensed（GitHub 免费版或 Pro）；blocked 记录你正在等待什么。

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

每次会话开始时，先读取该文件，再从第一个未完成的步骤继续。你所依赖的任何先前步骤，都要重新运行它的检查，因为在两次会话之间，密钥可能过期，缓存也可能被清除。

第 0 步：选择路线和构建

向用户询问一次，并记录答案。

• 路线。用于用户自己的代码：选用与项目语言对应的 SDK，即 Python 3.8+、Node 20+ 或 .NET 8（如果还没有项目，建议使用 Python）。供你这个智能体自己浏览网页：使用 MCP 服务器（Python 3.10+）。作为现有框架的 CDP 端点：使用 Docker 镜像。
• 构建。开源版构建无需密钥，也无需注册：基于 Chromium 150，开源（BSD-3），足以起步。最新构建基于 Chromium 154，需要许可证密钥：凭 GitHub 免费使用，同一时间运行一个浏览器；或者选择 Pro，最多同时运行 250 个浏览器。

浏览器支持 Windows x64 和 Linux x64，Docker 镜像同样是 x64。如果是 macOS 或 ARM 机器，请停下来并如实告知；托管浏览器是无需本地浏览器的方案。

第 1 步：已安装

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

检查方法：clearcote version（Node：npx clearcote version）输出 0.45.0 或更高版本。对于 Docker，docker image ls teamflatearth/clearcote 会列出该镜像。

.NET 本身没有 clearcote 命令。先检查 dotnet list package 是否列出 Clearcote，然后把第 1 至第 3 步中的每条 clearcote 命令都改用 npx -y clearcote <command>（Node 20+）或 pipx run clearcote <command>（Python 3.8+）的形式运行。这不会给项目添加任何东西，而且该命令与 .NET SDK 使用同一个浏览器缓存和许可证文件（~/.clearcote/license.key）。如果机器上既没有 Node 也没有 Python，请用户安装其中之一：没有这个命令，就无法确认浏览器版本，也就无法验证这次安装。

第 2 步：已设置许可证

如果使用开源版构建，把这一步标记为完成，证据写 open build, no key。如果使用最新构建，密钥直接到达用户的机器，不经过你：

• 如果 clearcote --help 中列有 clearcote login --device，就运行 clearcote login --device（Node：npx clearcote login --device）。它会输出一个链接和一个简短的代码。用户在自己的浏览器中打开该链接，登录并批准（免费密钥需要注册至少 30 天的 GitHub 账号），然后 SDK 把密钥保存到 ~/.clearcote/license.key，全程不显示密钥。
• 否则，由用户在“Licenses”页面领取密钥，并在自己的终端中运行 clearcote login（Node：npx clearcote login），把密钥粘贴到那里：密钥只显示在用户自己的屏幕上，不会出现在对话中。把这些步骤告诉用户，然后等用户说已完成。用户也可以改为自己设置 CLEARCOTE_LICENSE_KEY，写在 shell 配置文件、CI 密钥、MCP 客户端配置的 env 块或 Docker 环境中（这样 docker run -e CLEARCOTE_LICENSE_KEY 会把它传入容器，而值不会出现在命令中）。

切勿自己运行 clearcote login <key>：密钥会留在你的对话记录和 shell 历史中。也不要打开 ~/.clearcote/license.key。检查方法：clearcote info --quick 的 Licence 行会显示一个已遮蔽的密钥，并标注 from file 或 from env，你只需要看到这些。none (free build) 表示没有找到密钥。只设置在某个 MCP 客户端配置或容器中的密钥，在你的 shell 里是看不到的；请确认变量名存在，但不要打印它的值。

第 3 步：运行正常

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

（Node：npx clearcote install 和 npx clearcote info。）检查方法：clearcote info 输出 Launch test ok 及浏览器版本（使用 --json 时：launch.ok 为 true，launch.version 是版本号，binary.tag 是构建）。使用免费密钥时，这会短暂占用唯一的浏览器席位，所以请先关闭其他所有 Clearcote 浏览器。然后按路线继续：

• SDK：运行第一个脚本，clearcote_hello.py 或 clearcote_hello.mjs。检查方法：它输出 Example Domain 和一个 Chrome 的 user agent，然后退出。在 .NET 上，请使用 Playwright & Puppeteer 页面中的 C# 标签页。fingerprint 种子就是身份：同一个种子每次都给出同一台设备，所以每个账号使用一个种子。
• MCP 服务器：按MCP 服务器页面所示，在客户端中注册命令 clearcote-mcp（先询问用户；如果它在虚拟环境中，请填写完整路径）。重启客户端，然后对 https://example.com 调用它的 navigate 工具；它会返回最终 URL 和页面标题。
• Docker：启动一个容器，然后读取它的日志和端点，如下所示。

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

第 4 步：已验证

把第 3 步的输出与用户应有的构建进行对比。在 Docker 中，构建标签是日志行里引擎路径的一部分。

如果 Pro 套餐固定了旧版构建，则会显示该构建。如果这不是用户选择的构建，请停下来告诉用户。版本一致时，把 verified 标记为完成并记下版本号，然后告诉用户：所选路线、SDK 版本、运行的是哪个构建及其确切的浏览器版本、第一个脚本在哪里以及如何运行、密钥保存在哪里（文件或环境变量，绝不包括密钥本身），以及文档。

步骤失败时

可选项（仅在用户需要时）

• 代理。传入 Playwright 代理和 geoip=True，让时区和语言跟随代理的出口 IP。参见代理与 geoip。
• 通过 MCP 给你这个智能体自己用的浏览器（如果之前选的不是这条路线）：pip install -U clearcote-mcp（Python 3.10+），然后按第 3 步注册。使用最新构建时，服务器会找到第 2 步保存的密钥，或者由用户自己把 CLEARCOTE_LICENSE_KEY 添加到该服务器的 env 中。
• 没有可以运行它的机器。托管浏览器只需一次 API 调用，就能在 Clearcote 的服务器上启动同一款浏览器。它需要 API 密钥，并按 GB 计费，所以请先询问用户。

机器可读摘要

简洁的纯文本项目摘要位于 /llms.txt，合并成单个提示词文件的完整文档位于 /llms-full.txt。仓库中还附带一份 AGENTS.md，为贡献者说明项目结构和约定。

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

最简集成步骤

1. 安装 SDK（pip install clearcote / npm i clearcote）——它会下载并校验浏览器。
2. 根据你所代表的身份，派生一个确定性的 fingerprint 种子。
3. 使用代理时，传入 geoip=True，让时区、语言和 WebRTC 与代理出口保持一致。
4. 对于需要 CDP URL 的框架（browser-use、Stagehand、Crawl4AI），请改用 serve() 或 clearcote serve。

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

也可以用 executablePath 直接驱动开源版构建的二进制文件，但授权版构建只能通过 SDK 启动，而且直接启动会丢掉 SDK 的默认设置——参见 Playwright & Puppeteer。如果需要保真度更高的身份，可以改为启动一个真实采集的配置文件，而不是使用种子：launch(profile="auto") 会从配置文件库（授权版构建）中挑选一个适合当前机器的配置文件，或者传入 fingerprint_profile="profile.json"（Node：fingerprintProfile）。不要把配置文件和 fingerprint 种子一起使用。

浏览器内置 AI 智能体

Clearcote 附带一个可选的、需要主动开启的 AI 智能体，能自主驱动真实页面。它感知实时页面，询问由用户配置的 LLM 下一步该做什么，然后通过 Chrome 的 Actor 框架用真实、可信的输入事件执行操作，而不是注入脚本。它默认关闭（除非你提供智能体密钥或智能体相关开关，否则不会激活），并且需要你自带密钥：可以指向任意兼容 OpenAI / OpenRouter 的端点。密码字段在发送给模型之前会被遮蔽。请使用 launch_agent()（持久化上下文）——这是受支持的用法。

在 SDK 中，launch_agent（Node：launchAgent）返回一个持久化的 BrowserContext，run_agent_task(page, goal, max_steps=...)（Node：runAgentTask）负责驱动它，并返回 { success, finalText, steps, stepsJson }。把一个 profile 目录作为第一个参数传入（Node 中为 userDataDir），即可复用同一个 profile；不传的话，每次调用都会新建一个临时 profile 文件夹，关闭时也不会删除。仅支持 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"])

智能体的启动选项直接映射到二进制开关：agent_llm_url / agentLlmUrl（--agent-llm-url）、agent_llm_key / agentLlmKey（--agent-llm-key）、agent_model / agentModel（--agent-model），以及 agent_typing / agentTyping。智能体有了 URL（默认为 OpenRouter）、密钥和模型之后，任务即可运行。智能体要求模型以纯文本形式回复 JSON，因此端点不需要支持工具调用；agent_tool_mode / agentToolMode（--agent-tool-mode，CLI 中为 --tool-mode）可以传入，但目前不起作用。

agent_typing / agentTyping 用于调整智能体的击键节奏：human（默认）为每个按键生成 keydown/keyup 时序，长文本也会逐键输入；fast 是引擎的快速节奏；instant 则一次性输入。默认设置避开了两种输入破绽——机器般分毫不差的均匀时序，以及长文本被瞬间粘贴（不会产生任何击键事件）。

clearcote-agent CLI

同一个智能体也以 CLI 形式提供，便于快速、可脚本化地运行。可以传入一个一次性目标，也可以进入交互式 REPL。模型密钥来自 --key，或者 $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

CLI 选项包括 --llm-url、--model、--max-steps、--profile、--headless、--executable、--fingerprint、--proxy、--timezone 和 --json。传给 --url 的裸主机名会自动升级为 HTTPS。

相关文档

• 指纹参数：完整的开关参考（也便于机器读取）。
• Playwright & Puppeteer：即插即用的启动方式。
• 示例：可直接复制粘贴的 SDK、配置文件、代理、canvas bridge、CI 和智能体示例。
• 浏览器内置 AI 智能体：可选的自主页面驱动，以及 clearcote-agent CLI。
• MCP 服务器：从 Claude Desktop、Cursor 或 Cline 驱动 Clearcote。
• 部署：clearcote serve——一个 CDP URL，每个连接各用一个独立身份。
• 推荐设置：哪些设置该开启，哪些应保持不动。
• 验证：运行之前先确认二进制文件。
• 源码仓库：补丁、构建流水线、AGENTS.md。

构建确定性的身份：从稳定的 ID（租户、账号、任务）派生种子，让同一个执行者始终得到相同的浏览器指纹——可复现，也便于调试。