nokk

---

安装

pip install nokk                    # Python: the prebuilt binary is in the wheel
npm install @koloss777/nokk         # Node: run it with `npx nokk`
docker run --rm -p 9222:9222 ghcr.io/koloss777/nokk:latest

无需下载浏览器。提供 Linux（x86_64、ARM64）、Apple Silicon 上的 macOS 和 Windows x64 预构建版本；其他平台可从源码构建。

快速开始

# Load a page behind Cloudflare, clear the challenge, print what is behind it
nokk --load https://www.scrapingcourse.com/cloudflare-challenge --solve-challenge 30 \
     --eval "document.querySelector('h2').textContent.trim()"

# Or run the CDP server and drive it from any client
nokk --port 9222 --auto-solve   # ws://127.0.0.1:9222/devtools/browser/nokk

import nokk
from playwright.sync_api import sync_playwright

with nokk.launch(auto_solve=True) as server, sync_playwright() as pw:
    page = pw.chromium.connect_over_cdp(server.ws_endpoint).new_page()
    page.goto("https://www.scrapingcourse.com/cloudflare-challenge")
    print(page.title())

对于 AI Agent，运行 uvx nokk-mcp 可将其作为 MCP 服务运行。 Puppeteer、Node、会话和 Cloudflare 选项见下文。

为什么选择 nokk

Puppeteer 和 Playwright 驱动真正的 Chromium，反机器人系统会通过 navigator.webdriver、CDP 痕迹和无头 TLS 握手识别它。nokk 从 TLS 握手到 JavaScript 环境 都力求表现得像 Chrome，而且完全没有渲染引擎。

	nokk 0.1.35	Chrome 151（Puppeteer / Playwright）
启动至 CDP 响应	~0.05 s	~0.2 s
空闲内存（PSS）	~60 MB，1 个进程	~330 MB，12–14 个进程
Cloudflare 验证，中位耗时	12.4 s	12.4 s
最慢验证耗时	15.6 s	27.8 s
每次验证的 CPU 耗时	6.4 s	9.5 s
每次验证的峰值内存	~570 MB	~720 MB
验证成功数	24/24	24/24
TLS 指纹（JA3/JA4）	与 Chrome 151 匹配	Chrome
截图、PDF、布局	无	有
CDP 覆盖范围	常用路径	完整

_{数据测于 nokk 0.1.35、8 核 Linux 机器，时间为 2026 年 10 月。Cloudflare 一行的数据：8 个生产网站 × 3 次运行， 通过同一个代理；nokk 使用 --until-clearance，Chrome 由一个点击复选框的测试程序驱动；只有网站随后携带 Cookie 成功打开时，才算验证成功。}

以下需求不适合使用 nokk： 截图、PDF、布局或绘制，或完整的 Playwright/CDP 功能面。nokk 的设计本身就不包含渲染引擎，其 CDP 覆盖范围 仅涵盖 Puppeteer 和 Playwright 用于导航和脚本执行的路径。

在公开页面上的实测

在一台 8 核 Linux 机器上（2026 年 10 月），使用命令行对每个页面运行 3 次，参数为 --solve-challenge 30，且不使用代理。耗时是从进程启动到打印结果的整条命令所用的时间。你可以用 tools/cf-check.sh 自行运行。

页面	挑战	已解决	中位数	最慢
chess.com/login	实时网站上的不可见 Turnstile 小组件	3/3	7 s	9 s
scrapingcourse.com/cloudflare-challenge	托管式插页	3/3	5 s	7 s
peet.ws/turnstile-test/managed.html	托管式小组件	3/3	7 s	8 s
peet.ws/turnstile-test/non-interactive.html	非交互式小组件	3/3	3 s	4 s
nopecha.com/demo/cloudflare	带复选框的交互式插页	3/3	10 s	11 s

在 Cloudflare 保护的生产网站上，结果见上文的对比：8 个网站，24 次中全部 24 次通过。这里不列出这些网站的名称。

用法

命令行

nokk --fetch https://tls.browserleaks.com/json                   # Chrome TLS + HTTP/2 fingerprint
nokk --load https://example.com --eval 'document.title'          # run the page, query the DOM
nokk --load https://quotes.toscrape.com --dump-requests          # every request the page makes
nokk --load https://target --proxy socks5://host:1080            # through a proxy
nokk --port 9222 --rotate-fingerprint --geoip-timezone           # CDP server, a machine per context

默认情况下会丢弃广告、分析和跟踪器请求；使用 --allow-trackers 则会加载它们。 绝不会屏蔽反机器人服务商，因为它们必须运行才能发放令牌。

Puppeteer

import puppeteer from 'puppeteer';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/nokk',   // nokk --port 9222
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());

Node 和 Python

两个软件包都附带预构建的二进制文件，并会为你启动 CDP 服务。

const server = await require("@koloss777/nokk").launch({ autoSolve: true });
// server.wsEndpoint -> puppeteer.connect / chromium.connectOverCDP

with nokk.launch(auto_solve=True) as server:   # or: await nokk.launch_async()
    ...  # server.ws_endpoint -> connect_over_cdp

crawl4ai、Scrapy、Playwright MCP 和其他 CDP 工具

任何通过 CDP 驱动 Chrome 的工具都可以驱动 nokk。crawl4ai 使用自带的 Chromium 被 Cloudflare 拦截后，可以通过 nokk 访问拦截页之后的页面： BrowserConfig(browser_mode="custom", cdp_url=server.ws_endpoint)。Scrapy （scrapy-playwright 的 PLAYWRIGHT_CDP_URL）和 Playwright MCP（--cdp-endpoint） 也可以用同样的方式工作。请参阅 docs/integrations.md。

面向 AI Agent（MCP）

nokk 作为 Model Context Protocol 服务运行，因此 Claude Desktop 或 Claude Code 之类的 Agent 可以通过具有指纹的引擎浏览网页。使用 uv 时，无需预先安装任何内容：

{ "mcpServers": { "nokk": { "command": "uvx", "args": ["nokk-mcp", "--rotate-fingerprint"] } } }

不使用 uv：运行 pip install "nokk[mcp]"，然后设置 "command": "python", "args": ["-m", "nokk.mcp"]。 工具：open、read_text、read_html、click、fill、evaluate、links、solve_challenge、 challenge_state、reset。

Cloudflare 挑战

nokk 可以自动通过 Turnstile：不可见小组件、托管式插页，以及交互式 验证您是人类 复选框。无需针对每个网站单独配置。如果小组件需要点击，engine 会像真人一样点击。

• --solve-challenge N 设置时间预算；如果门禁仍未解除，--fail-on-challenge 会以 3 退出。
• --until-clearance 会在获得新的 cf_clearance 后停止，不再加载门禁后面的繁重页面。
• --auto-solve 会对每次通过 CDP 调用的 page.goto() 执行同样的操作；Nokk.solveChallenge 则可按需执行。
• 可以导入来自真实浏览器的 cf_clearance，因为 nokk 的 JA4 与 Chrome 151 匹配。

详细信息、CDP 方法和事件请参阅：docs/cloudflare.md。

持久化会话

--session-store ./sessions 会将每个命名会话的 Cookie jar（包括 cf_clearance）保存到磁盘，并在新进程中重新加载。只需预热一次会话，即可重复使用，无需每次运行都解决挑战。请参阅 docs/sessions.md。

轮换指纹

--rotate-fingerprint 会为每个浏览器上下文配置一套彼此一致的机器特征：TLS 模拟、User-Agent、客户端提示、平台、屏幕和 WebGL 信息彼此匹配。--geoip-timezone 会让时区和语言与代理出口 IP 相匹配。请参阅 docs/fingerprints.md。

构建版本

构建版本	新增内容	提供方式
light（默认）	包含以上所有功能；canvas 和 WebGL 像素为合成生成	pip、npm、ghcr.io/koloss777/nokk:latest、nokk-*.tar.gz
render	真实的 canvas 2D 和 WebGL 光栅化，峰值内存约多 100 MB	:render 镜像、nokk-render-*.tar.gz、--features render,webgl

预构建版本支持 Linux x86_64 和 ARM64、搭载 Apple Silicon 的 macOS，以及 Windows x64；render 构建版本支持 Linux x86_64。Docker 变体、压缩包和从源代码构建的说明见 docs/install.md。

工作原理

这是一个由多个小型 crate 组成的 Cargo 工作区：V8 隔离区池、基于 BoringSSL 且带有 Chrome 指纹的 HTTP 客户端、html5ever DOM、隐身层和 CDP 服务。并发方式是每个线程运行一个隔离区，每个隔离区包含多个上下文；所有 IO 都通过 tokio 在隔离区线程之外执行；JS 指纹始终与 TLS 指纹一致。更多信息请参阅 docs/architecture.md。

项目状态

Alpha。 引擎已具备真实的端到端功能：V8 会针对解析后的 DOM 执行页面 JS，带指纹的传输层可以通过 Cloudflare 的 TLS/HTTP 检查；引擎能够在真实网站上解决 Turnstile 挑战，包括隐形、托管和交互式挑战；Puppeteer 和 Playwright 可通过 CDP 连接，以打开页面、导航和执行求值。

尚未完成的部分，以及目前需要注意的边界：

• JS 指纹强化仍在进行中。 许多强化措施已经就位，包括原生 toString 屏蔽、隐藏 Object.getOwnPropertyNames 无法访问的内部属性、将 navigator/screen 实现为真实的原型实例、与 IP 一致的时区、按上下文轮换且保持一致的指纹、 Web Workers、使用 Chrome 像素和采样的 canvas/WebGL/WebGPU/音频、 Trusted Types 和 CSP。nokk 目前可以解决 Cloudflare 的挑战；通过逐项与 Chrome 对比来找出剩余的可识别特征；但它尚未 达到 CreepJS 等专用指纹检测套件的匹配水平。请参阅 路线图。
• CDP 覆盖的是常见使用路径，并非整个协议。Puppeteer 和 Playwright 可通过 CDP 连接；导航、evaluate、$ / $eval / $$eval、title()、url()、 新建页面和 CDP 会话均已测试；较少使用的域尚未实现。
• 按上下文隔离 Cookie 和按会话持久化均可用（每个浏览器上下文 都有独立的 Cookie jar；具名会话可在多次运行之间持久保存）；按主机 / 按代理 / 全局的 连接数限制尚未实施（第 7 阶段）。
• 不提供渲染功能——截图、PDF 以及布局/绘制均有意不在范围内。

请参阅 ROADMAP.md，了解分阶段计划和具体的强化待办事项。

贡献

欢迎提交问题和 PR；路线图中的强化待办事项是很好的起点。 提交更改前：

cargo fmt
cargo clippy --all-targets
cargo test

许可证

你可以选择依据 MIT 或 Apache-2.0 许可使用本项目。

除非你明确另有说明，否则你为纳入本作品而提交的任何贡献（定义见 Apache-2.0 许可证），都应依上述条款采用双重许可，且不附加任何条款或条件。

---