面向智能体与 LLM

Clearcote 的组织方式让自动化工具也能像人一样轻松地浏览、集成和参与贡献。

把整个项目交给你的智能体

一键复制全部文档——所有文档页面会被合并成一个可直接用作提示词的文本块。粘贴到 Claude、Codex 或 Cursor 中，即可获得完整的项目上下文。

查看 /llms-full.txt ↗

机器可读摘要

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

json

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 149 (v0.1.0-pre.22), licensed build 153.0.8010.36-r28",
  "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"
}

最简集成步骤

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

python

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。

python

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 环境变量。

bash

# 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。