WEBCLAW

English | 简体中文

webclaw

将网站转换为整洁的 Markdown、JSON 和适用于大模型的上下文。
_{为 AI Agent 和 RAG 管道提供 CLI、MCP 服务、REST API 和 SDK。}

大多数网页抓取工具给 Agent 的输出都不理想，无非是以下两种：

• 被拦截的页面、登录墙或空白应用外壳
• 充斥着导航、脚本、样式、广告和重复模板内容的原始 HTML

webclaw.io 是 webclaw 提供的托管网页提取 API。此仓库包含开源 CLI、MCP 服务、提取引擎和可自托管的服务。

webclaw 可将 URL 转换为工具能够实际使用的整洁内容。

webclaw https://example.com --format markdown

# Example Domain

This domain is for use in illustrative examples in documents.

You may use this domain in literature without prior coordination or asking for permission.

可在终端中使用，通过 MCP 将其接入 Claude/Cursor，从应用中调用托管 API，或自托管 OSS 服务。

安装

Agent 配置

将 webclaw 连接到 Claude Code、Claude Desktop、Cursor、Windsurf、OpenCode、Codex CLI 及其他兼容 MCP 的工具，最快的方法：

npx create-webclaw

安装程序会检测受支持的客户端，并为你配置 MCP 服务。

Homebrew

brew tap 0xMassi/webclaw
brew install webclaw

预编译二进制文件

从 GitHub Releases 下载 macOS、Linux 和 Windows 的二进制文件。

Windows（x64）

预构建 ZIP 是最简单的安装方式，无需 Rust。在 v0.6.22 发布页面 下载 webclaw-v0.6.22-x86_64-pc-windows-msvc.zip。在文件资源管理器中解压， 在包含 webclaw.exe 的解压文件夹中打开 PowerShell，然后运行：

.\webclaw.exe --version
.\webclaw.exe https://example.com --format markdown

PowerShell 要求为当前目录中的程序添加 .\ 前缀。只有在想从 其他文件夹运行 webclaw 时，才需要将该目录添加到用户 PATH。如果 Windows 提示缺少 Visual C++ 运行时 DLL，请安装 适用于 x64 的 Microsoft Visual C++ Redistributable。该 ZIP 包含 x64 二进制文件； 原生安装检查不支持 Windows ARM64。

如需在 Windows 上从源代码构建，请安装 Rust，并使用 x86_64-pc-windows-msvc 工具链、包含 使用 C++ 的桌面开发和 Windows SDK 的 Visual Studio Build Tools、 Git、CMake 3.22 或更新版本、LLVM（包括 libclang.dll）以及 NASM。安装后，打开一个新的 Visual Studio Developer PowerShell。 确保 CMake 和 NASM 位于 PATH 中；如果 bindgen 无法找到 LLVM，请将 LIBCLANG_PATH 设置为 LLVM 的 bin 目录，例如：

$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
cargo install --git https://github.com/0xMassi/webclaw.git --tag v0.6.22 --locked webclaw-cli
webclaw --version

Cargo 包名为 webclaw-cli；可执行文件为 webclaw。这些包 通过 Git 而非 crates.io 安装。首次从源代码构建可能需要几分钟。Windows CI 工作流会在预装构建工具的托管运行器上检查 Git 安装和已发布的 ZIP， 但不能模拟一台全新 PC。 Linux 容器（包括 macOS 上的 Docker）无法验证 Windows 支持。

Docker

docker run --rm ghcr.io/0xmassi/webclaw https://example.com

Cargo

cargo install --git https://github.com/0xMassi/webclaw.git --tag v0.6.22 --locked webclaw-cli
cargo install --git https://github.com/0xMassi/webclaw.git --tag v0.6.22 --locked webclaw-mcp

如果从源代码构建时因缺少原生构建工具而失败，请安装平台所需的前置组件：

Python

python/ 目录会构建一个 Python 包，其中捆绑了 webclaw 二进制文件，并通过 Python 调用它：scrape、select、tables、find_text、similar、crawl、map 和 screenshot，无需 API 密钥，也没有 Python 依赖。

cd python && uv build --wheel && pip install dist/webclaw_cli-*.whl

import webclaw_cli as wc

md = wc.scrape("https://example.com", "llm")
titles = wc.select("https://books.toscrape.com", css="h3 a::attr(title)")
for page in wc.crawl("https://quotes.toscrape.com", max_pages=10):
    print(page["url"])

请参阅 python/README.md，了解所有函数和选项。

快速入门

抓取单个页面

webclaw https://stripe.com --format markdown

返回针对大模型优化的文本

webclaw https://docs.anthropic.com --format llm

仅保留主要内容

webclaw https://example.com/blog/post --only-main-content

包含或排除选择器

webclaw https://example.com \
  --include "article, main, .content" \
  --exclude "nav, footer, .sidebar, .ad"

使用 CSS 选择器或 XPath 选取值

webclaw https://books.toscrape.com --select "h3 a::attr(href)"
webclaw https://books.toscrape.com --select "article.product_pod" \
  --field "title=h3 a::attr(title)" --field price=.price_color

--select 会打印选择器匹配内容的 JSON 数组：每个元素的文本，或者当选择器以 ::attr(NAME) 或 ::html 结尾时返回属性或元素的 HTML。href 和 src 中的链接会转换为绝对地址。使用 --field NAME=SELECTOR 时，每个匹配项都会变成一个 JSON 对象，其字段在该匹配项内部运行，并取第一个值或 null。需要 JavaScript 的页面会先渲染，再进行提取。

webclaw https://books.toscrape.com --xpath "//li[@class='next']/a/@href"
webclaw https://books.toscrape.com --xpath "//article[@class='product_pod']" \
  --field "title=.//h3/a/@title" --field "price=.//p[@class='price_color']"

--xpath 则接受 XPath 1.0 表达式，并基于同一个已解析页面执行：元素和文本节点返回其文本，属性返回其值，而 count() 或 string() 这类表达式返回单个值。使用 --xpath 时，每个 --field 都是从匹配项开始计算的表达式，通常以 . 开头。MCP select 工具使用 xpath 替代 selector。

将数据表格作为 JSON

webclaw "https://en.wikipedia.org/wiki/List_of_S%26P_500_companies" --tables

--tables 会将页面的数据表格打印为 JSON 数组，每个表格都包含其 caption（如果有）、headers 和单元格文本组成的 rows。跨越多行或多列的单元格会在每个对应位置重复文本，因此每行都包含与列数相同的值。多层表头会按列合并，并以 / 分隔，例如 Population / % of world。MCP select 工具使用 tables: true 代替选择器。

表头行包括 <thead> 中的行以及开头仅包含 <th> 的行；如果开头某行只有一个单元格且跨越整张表，则将其作为标题。以下表格会被跳过，视为页面布局：

• 标记了 role="presentation" 或 role="none" 的表格；
• 文本列少于两列的表格；
• 没有表头行且仅有一行主体内容、嵌套了另一张表、仅包含链接，或在多于一个单元格的行中包含段落、列表或其他区块的表格。

带有 hidden、内联 display:none 或 <template> 的隐藏文本会被排除。由样式表隐藏的文本会保留，因为页面不会应用样式。单元格最多保留前 64 KB 的文本；超大型表格会被截断，并标记 "truncated": true。页面上的表格总量达到 64 MB 后，后续表格会被排除。

按文本查找元素，或查找与示例相似的所有元素

webclaw https://books.toscrape.com --find-text "tipping the"
webclaw https://books.toscrape.com --find-regex '^£5\d\.\d\d$'
webclaw https://books.toscrape.com --find-text "Tipping the Velvet" --similar

--find-text 会将页面正文中可见文本包含指定文本的元素（不区分大小写）打印为 {"selector", "text"} 对象。每个匹配项都是包含该文本的最深层元素，因此即使文本被内联标签拆分，也能匹配；其 selector 是该元素从最近的、具有唯一 ID 的祖先开始，或从根元素开始的路径。该路径只会选中该元素；但如果页面嵌套深度超过 64 层且没有这样的 ID，则只保留最后 64 步，因此可能选中多个元素。--exact 会匹配完整文本，--case-sensitive 会区分字母大小写，--find-regex 则接受正则表达式。

--similar 会将 --find-text、--find-regex、--select 或 --xpath 选中的第一个元素作为示例，并返回页面上所有与之相似的元素，例如列表、网格或表格中的其他项目，同时提供一个能选中所有这些元素的 CSS 选择器。如果示例选择器以 ::attr(NAME) 或 ::text 结尾，或者 XPath 选中的是文本节点或属性节点，则包含该节点的元素将作为示例：

{
  "selector": "article.product_pod > h3 > a",
  "matches": [
    { "selector": "html > body > ... > li:nth-of-type(1) > article > h3 > a", "text": "A Light in the ..." },
    ...
  ]
}

使用该选择器配合 --select，或添加 --field 以直接获取记录；使用 --similar 时，字段为 CSS 选择器，输出格式为 {"selector", "records"}。如果字段位于项目内部，请将项目本身选为示例（例如 --select "article.product_pod" --similar）。MCP select 工具以相同方式接受 text 或 regex（以及 exact 和 case_sensitive），并接受 similar。每次调用只能使用一种选择方式：--select、--xpath、--tables、--find-text 或 --find-regex（在 MCP 中为 selector、xpath、tables、text 或 regex）；--similar 和 --field 不适用于表格。

只保留能回答问题的内容

webclaw "https://en.wikipedia.org/wiki/Rust_(programming_language)" -f llm \
  --query "Who began the language as a personal project?"

--query（以及 MCP scrape 工具中的 query）会根据问题为每个段落、列表、表格和代码块评分，并在各自标题下保留得分最高的内容，让 Agent 读取答案，而不是通读整个页面。如果没有任何区块与问题共享词语，则页面会原样返回。

用于检索的分块

webclaw https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html --chunk 256
webclaw https://quotes.toscrape.com --crawl --depth 1 --chunk 512 --chunk-overlap 50

--chunk 会将页面打印为适用于搜索索引或 RAG 管道的分块，每行一个 JSON 对象（使用 -f json 时为一个 JSON 数组）：url、index、heading_path（分块起始位置生效的标题，按从外到内排列）、tokens 以及分块的 Markdown text。分块由完整的段落、列表、表格和代码块构成，长度不会超过给定的 token 数量太多。若某个块太大，无法放入一个分块，则会先按换行符切分，再按句末切分，然后在词语之间切分；对于字符之间没有空格的文本也会进行切分。每个片段都会重新打开代码块，表格则会重复表头行。Token 数量是未使用分词器进行估算的。在基准测试页面（包含散文、文档、代码、表格和九种语言）中，十分之九的分块在 cl100k 中的计数为估算值的 0.77 到 1.12 倍，在 o200k 中为 0.72 到 0.97 倍；按 cl100k tokens 计算，4.5% 的分块超出了要求的大小，按 o200k tokens 计算则为 0.5%。--chunk-overlap 会在每个分块末尾重复至多指定数量的 token，并将其放在下一个分块的开头。对于多个 URL 或 --crawl，每个页面都会单独分块。MCP scrape 工具接受 chunk 和 chunk_overlap，并以 JSON 数组形式返回分块；crawl 也接受这两个参数，并返回包含爬取数量、失败页面和分块的对象。

将链接转换为编号引用

webclaw https://en.wikipedia.org/wiki/Web_scraping --citations

--citations 会将所有链接和图片 URL 从 Markdown 中移出，并在末尾以 Markdown 脚注形式列出：[Data scraping](https://...) 会变为 Data scraping[^1]，图片会变为 ![alt][^2]，页面末尾则会添加 ## Links，并为每个 URL 添加一行 [^1]: https://...。编号按 URL 首次出现的顺序排列，同一 URL 重复出现时沿用其首次编号；如果页面已有编号脚注，则从其后开始编号。对于多个 URL 或 --crawl，合并打印的页面会沿用同一编号，因此整个输出中的每个编号都对应一个 URL；使用 --output-dir、-f json 或 jsonl 时，每个页面会单独编号。

有些内容会保持原样：代码块和行内代码、引用式链接（[text][id]）、自动链接（<https://...>）以及原始 HTML 链接。指向同一页面某处的链接（#section）和 javascript: 链接会保留文本，但移除 URL。被引用的图片不再是 Markdown 渲染器识别的图片（GitHub 会将 ![alt] 显示为文本）；其 URL 会列在清单中。使用 -f markdown 时，页面的 ## Structured Data 块会放在清单之后。

在实时抓取的 63 个基准测试页面中，清单之前的正文 token 数约为纯 Markdown 的一半，包含清单在内的完整输出总 token 数则减少了 10.7%。总节省量主要来自链接较多的页面，例如 Wikipedia 条目：节省最多的 5 个页面占总节省量的 68%，页面节省量的中位数为 2.5%，63 个页面中有 18 个略微变长。使用与不使用该功能时，关键事实保持不变。此功能适用于通过简短且稳定的 ID 引用来源，或从文本中移除 URL；不适合作为通用的 token 缩减方法。

该功能适用于 -f markdown，以及 -f json 和 jsonl 中的 Markdown 内容，可用于单个 URL、多个 URL 或 --crawl。与 --chunk 以及不打印页面 Markdown 的模式（-f text、llm 或 html、--select、--map、--brand、--diff-with、--watch、LLM 模式等）同时使用时会被拒绝。MCP scrape、crawl 和 batch 工具接受 citations: true；webclaw_core::to_citations（或用于跨页面延续编号的 to_citations_after）可对任意 Markdown 执行相同操作。

重用已抓取的页面

webclaw https://example.com --cache          # fetch once, answer later runs from disk

--cache 会将每个成功获取的页面保存在 ~/.cache/webclaw（或 WEBCLAW_CACHE_DIR）中，且只有你能读取；之后使用相同浏览器配置和请求头获取相同 URL 时，会直接从缓存读取，不发起网络请求。爬取和批量操作会逐页使用缓存。缓存条目永不过期；删除目录即可刷新缓存。错误响应、验证页面和 Set-Cookie 请求头绝不会被存储。缓存仅保存 HTTP 响应：仍需 JavaScript 的页面会继续在浏览器中渲染，并由浏览器通过网络加载脚本。

保存网页存档

webclaw https://example.com --warc page.warc.gz
webclaw https://docs.example.com --crawl --depth 2 --warc site.warc.gz > site.md

--warc FILE 会将 webclaw 获取的每个 HTTP 响应及其对应请求保存在 WARC 文件中。WARC 是 ISO 28500 定义的网页存档格式，网页存档和回放工具都可以读取。输出仍会写入原定位置；存档文件会写在输出文件旁边。以 .gz 结尾的文件名会逐条压缩记录，与 .warc.gz 文件相同。此选项适用于单个 URL、多个 URL、--crawl（包括 robots.txt 和重定向响应）以及 --map（包括它尝试过的网站地图）。记录会在收到时写入，因此即使你中途停止爬取，已获取的页面也会全部保留。如果文件已存在，内容会追加而不会覆盖：每次运行都会以自己的 warcinfo 记录开头，由多次运行生成的 WARC 文件仍是有效的 WARC 文件。如果文件末尾停在某条记录中间（例如运行在写入期间停止时留下的文件），则会拒绝向其中写入，因为截断后添加的记录将无法读取；此时请为 --warc 指定新文件。每条记录都包含其内容的 SHA-1 摘要。

响应会以 webclaw HTTP 客户端接收时的解码状态保存：压缩的正文会以解压后的形式存储，不包含 Content-Encoding、Content-Length 和 Transfer-Encoding 请求头；HTTP/2 响应则会获得 HTTP/1.1 状态行。每次运行的 warcinfo 记录都会说明这一点，且每条记录都指向该记录。回放工具可以正常读取这类记录，但载荷摘要针对的是解码后的正文，因此在去重时，它们与其他存档工具以压缩状态保存的同一页面副本的摘要不会匹配。请求记录会列出 webclaw 发送的请求头，包括 -H 和 --cookie 的值，因此请像保护这些值一样妥善保管文件；运行期间网站设置的 Cookie 不会列出。每个重定向都会有自己的响应和请求记录，包括重定向响应，无论是否在爬取过程中；与未使用 --warc 时一样，你传入的 Cookie 和凭据不会发送到其他网站。浏览器渲染的页面不会被写入存档，因此 --warc 不允许与 --render always、--actions 和 --scroll 同时使用；使用 --render auto 时，之后会被渲染页面的 HTTP 响应仍会保存。此选项也不允许与 --cache 同时使用，因为缓存响应不会访问网络；--cloud 也不支持与其同时使用。使用 --save-mhtml 保存渲染后的页面。

渲染 JavaScript 页面

启用 browser 特性构建（cargo build --release --features browser）后，当普通 HTTP 响应中几乎没有内容时，webclaw 会在本地 Chrome 中渲染页面：

webclaw https://hn.algolia.com                    # --render auto: HTTP first, Chrome only when needed
webclaw https://example.com --render always --wait-for "#app li"
webclaw https://example.com --cdp-url ws://localhost:9222/devtools/browser/<id>   # use a running browser

如果页面加载了脚本，且 HTTP 响应几乎没有文本，或者只有少量文本并带有空的应用根节点或“请启用 JavaScript”提示，auto 就会触发渲染；只有渲染结果内容更多时，才会保留该结果。

webclaw 启动的浏览器会将自身标识为普通 Chrome：每个页面、框架和工作线程都会发送并读取你所用 Chrome 的 User-Agent，不带无头 Chrome 添加的“Headless”，因此会与 Chrome 发送的客户端提示相匹配。有些网站会向无头浏览器提供错误页面或预渲染页面。通过 --cdp-url 连接的浏览器会保留自己的 User-Agent。

webclaw 启动的浏览器可以访问渲染后页面中的内容：

• 页面、其框架或工作线程发出的 HTTP 请求（包括重定向）都不会到达私有、环回或链路本地地址；
• 到这些地址的 WebSocket 连接会被拒绝，但会先建立 TCP 连接。使用代理时，除环回地址外，所有 WebSocket 连接都会通过代理，因此安全性取决于代理；
• 已关闭推测性预取和预连接；
• WebRTC 不会发送 UDP，但通过 TCP 连接的 TURN 服务仍可能连接到本地端口；
• 不使用代理时，如果页面文档来自私有地址，渲染就会失败，因此 DNS 重绑定无法返回本地内容。不过，请求本身仍会发出，且不会检查弹出窗口。

使用代理时，代理会自行解析主机名，并且不会进行文档检查，因此 HTTP 的安全性也取决于代理。不会检查服务工作线程。使用 --cdp-url 连接的浏览器会逐页检查，其他标签页不受影响，但 webclaw 在该浏览器中渲染的页面，其框架、工作线程、WebSocket、WebRTC 和推测性预取都不在检查范围内。

--block images,fonts,media 会在页面渲染内容时跳过这些资源。样式表始终会加载，因为许多应用会按需获取 CSS，没有它们就无法正常运行。脚本及其获取的数据仍会加载，因此大多数页面的文本都能保留，同时下载量减少约 40%。如果某个页面只有在字体或图像加载后才会显示部分文本（通过 document.fonts.load()、FontFace.load()、图像的 onload 或 decode()），屏蔽这些资源就会导致这些文本消失。我们测试过的真实网站中没有发现这种页面，但你可以在自己的页面上对比使用和不使用 --block 的结果。渲染速度不会明显加快，因为 webclaw 本来就会在文本稳定后停止等待，所以除非你明确要求，否则不会启用屏蔽。截图和 PDF 始终会加载所有资源。MCP 的 scrape 和 crawl 工具接受相同的 block 列表。

--screenshot page.png 会保存渲染页面中 1280x720 的视口，--full-page 会保存整页，文件名以 .jpg 结尾时则会生成 JPEG。MCP 的 screenshot 工具会将同一张图像返回给 Agent。

--save-pdf page.pdf（或使用 - 输出到 stdout）会通过浏览器的打印引擎将渲染后的页面输出为 PDF：包含所有页面、网站的打印样式和 Chrome 的默认页边距，但不包含某些浏览器添加的无障碍标签。--paper a4 可将默认的 US Letter 纸张改为 A4，--landscape 可将纸张横向放置，--print-background 会保留背景颜色和图像，--scale 0.8 可缩放内容（范围为 0.1 到 2）。它也接受与其他渲染操作相同的 --wait-for、--actions 和 --scroll，加载和打印都必须在 --timeout 限定的时间内完成。Chrome 会对整页进行布局后再打印，因此打印很长的页面（例如将完整的 Web 标准放在一页上）时，可能会占用数 GB 的内存。该标志不是 --pdf，因为 --pdf-mode 指的是读取获取到的 PDF，而不是生成 PDF。MCP 的 screenshot 工具会使用 format: "pdf" 返回同一份 PDF，作为大小不超过 10 MiB 的 application/pdf 资源，并以相同方式接受 paper、print_background 和 actions。

--save-mhtml page.mhtml（或使用 - 输出到 stdout）会将渲染后的页面保存为 MHTML，也就是“另存为单个文件”生成的单文件网页存档：包含脚本运行后的页面，以及它加载的图像、样式和框架。Chrome 可以离线打开该文件，但不会运行其中的脚本。它也接受与其他渲染操作相同的 --wait-for、--actions 和 --scroll。只有滚动到图像后才会加载的图像，只有在保存前已加载时才会包含在文件中，因此对于包含此类图像的页面，请添加 --scroll。Chrome 会一次性移交整个文件，因此写入时文件会完整保存在内存中：仅含单页 HTML 标准的 18.6 MB 存档，比同一页面的截图多占用约 100 MB。MCP 的 screenshot 工具会使用 format: "mhtml" 返回同一文件，作为大小不超过 10 MiB 的 multipart/related 资源。 --solve 可以通过 Cloudflare 挑战页面，也就是显示“Just a moment...”或“Performing security verification”的页面。网页返回此类页面时，webclaw 会在 Chrome 中打开它，等待挑战通过；如果页面要求点击复选框，也会点击，然后读取跳转到的页面，整个过程都在 --timeout 范围内。如果经过四分之三的超时时间后挑战仍未通过，命令会失败，并将其作为错误报告。在同一网站的后续页面中，无论是爬取还是批处理，都会重新通过普通 HTTP 请求，并携带 Chrome 获取的 clearance cookie（仅限 cf_clearance，绝不包含网站的其他 cookie）和 Chrome 的 User-Agent。我们测试的网站中，约有一半会让 Cloudflare 接受来自同一 IP 地址的该 cookie；如果不接受，webclaw 就会再次解决挑战。webclaw 渲染的页面中如果包含 Turnstile 复选框（例如注册表单中的复选框），也会被点击，以便页面操作可以提交表单；对于原本不会渲染的页面，请添加 --render always。webclaw 最多等待 10 秒以获取此类小组件的令牌，然后按原样读取页面。clearance 与 Chrome 的 User-Agent 绑定，因此 --solve 需要使用 --browser chrome（默认值）、chrome-macos 或 edge。通过 -H 传入的标头仍会用于页面的其他请求，但不会用于文档请求，因为重写文档请求会导致挑战失败。使用 --cdp-url 连接的浏览器会保留自己的 User-Agent。MCP scrape 工具接受 solve: true。

webclaw https://www.scrapingcourse.com/cloudflare-challenge --solve
webclaw https://gitlab.com/users/sign_in https://gitlab.com/explore --solve   # solves once, then plain HTTP

爬取、批处理、--watch 和 MCP 服务采用相同的渲染方式，并共用一个浏览器；只有在页面需要渲染时才会启动浏览器。webclaw 会按网站统计：如果至少三次渲染都表明渲染能增加内容（五次中至少四次如此），就会渲染该网站所有会运行脚本的页面；如果渲染不再增加内容（五次中最多一次如此），就会停止渲染该网站的页面。

读取前点击、输入和滚动

使用 browser 构建版本时，--actions 会在页面加载完成后、webclaw 读取页面之前，按与托管 API 的 actions 相同的格式在浏览器中执行步骤，因此无限滚动、“加载更多”按钮、分页按钮、表单或运行缓慢的脚本背后的内容都会出现在输出中。单独使用 --scroll 会一直滚动到底部，直到页面不再增长，最多滚动 20 次（如需更多次，可使用 --scroll=50）。

webclaw https://quotes.toscrape.com/scroll --scroll
webclaw https://github.com/topics/rust --actions '[{"type": "click", "selector": "button.ajax-pagination-btn", "repeat": 3}]'
webclaw https://quotes.toscrape.com/login --actions '[{"type": "type", "selector": "#username", "value": "me"}, {"type": "type", "selector": "#password", "value": "secret"}, {"type": "press", "key": "Enter"}]'
webclaw https://example.com --actions @steps.json

点击、按键或滚动后，webclaw 会等待页面及网站自身的请求停止活动，最长等待 5 秒，然后再执行下一步。网站可能会在请求完成后，通过定时器稍后绘制内容；遇到这种情况，可为其添加 waitForSelector 步骤。需要元素的步骤最多等待 10 秒，浏览器无法解析的选择器会立即导致失败。步骤打开的警告框、确认框和提示框会被关闭，打开的标签页或窗口也会被关闭。步骤有独立的时间预算，时长与 --timeout 相同，且不计入页面加载时间。第一个失败或超时的步骤会导致命令失败，并在错误中指出该步骤；如果 repeat 尚未完成就超时，也会导致失败，而不会返回部分页面内容。对于很长的信息流，请使用 --timeout。所有 executeJavascript 步骤的返回值总大小上限为 1 MiB。步骤会在与页面相同的浏览器中运行，并接受与页面自身脚本相同的检查；如果某个步骤导航到私有地址或环回地址，或导航到解析为此类地址的名称，命令就会失败。

--actions 只接受一个 URL；即使使用 --render auto，也会渲染页面。使用 -f json 或 -f jsonl 时，js_results 会包含在输出中；否则会输出到 stderr。--raw-html 会在执行步骤后打印页面。MCP 的 scrape 和 screenshot 工具接受与 actions 相同的列表，并在内容之后返回 js_results。本地扩展包括 click 的 nth、all 和 repeat，以及 scroll 的 selector、repeat 和滚动到底部功能。托管版的 screenshot 步骤不会执行，因为 --screenshot 会完成此操作。

在多次运行之间保持登录状态

使用 browser 构建版本时，--browser-profile DIR 会将浏览器的 Cookie、本地存储和 IndexedDB 保存在 DIR 中，这样登录一次后，下次运行仍会保持登录状态：

webclaw https://quotes.toscrape.com/login --browser-profile ~/.webclaw-profile \
  --actions '[{"type": "type", "selector": "#username", "value": "me"}, {"type": "type", "selector": "#password", "value": "secret"}, {"type": "click", "selector": "input[type=submit]"}]'
webclaw https://quotes.toscrape.com/ --browser-profile ~/.webclaw-profile        # a later run, still logged in
webclaw https://example.com/account --browser-profile ~/.webclaw-profile --cookie "session=..."   # or bring a session cookie in once

使用配置文件时，webclaw 读取的每个网页（包括爬取和批量处理时）都会在浏览器中加载，并使用配置文件中的 Cookie。此前会先发送普通 HTTP 请求，以区分网页与 PDF、订阅源及其他文件；这些文件仍通过 HTTP 获取。因此，每个网页都会通过浏览器加载：在我们的基准测试中，不使用配置文件时，爬取 50 个页面耗时 3.6 秒；使用全新配置文件时耗时 12.4 秒；使用已预热的配置文件时耗时 8.0 秒。--raw-html 会输出浏览器处理后的页面内容。如果页面在浏览器中加载失败，webclaw 会发出警告并保留 HTTP 结果。如果配置文件无法打开（因为正在使用、遭到拒绝（见下文）或偏好设置无法读取），则会在第一个页面加载前停止运行并报错，爬取也不例外；MCP 工具会返回此错误。在爬取过程中，浏览器遇到的重定向会像通过 HTTP 获取时一样，在跟随之前检查 robots.txt 和爬取范围。

会话 Cookie 也会保留：即使保留了配置文件，Chrome 关闭时也会丢弃会话 Cookie，而大多数网站会通过其中一个 Cookie 保持登录状态。所有页面共享配置文件中的 Cookie。运行开始时，--cookie 和 --cookie-file 中的 Cookie 会保存到配置文件中，但仅适用于命令行中的 URL（或 --urls-file 中的 URL），即使当时没有页面需要使用浏览器也是如此；使用配置文件时，浏览器不会发送自身 Cookie 以外的任何 Cookie。MCP scrape 工具会将其 cookies 保存到配置文件中，供传入的 URL 使用，这些 Cookie 会保留到之后的调用中。不使用 --browser-profile 时，默认情况下，每次运行都会从空配置文件开始；使用 Cookie 渲染的页面会拥有独立的浏览器上下文，因此不同页面或不同运行之间不会保留任何内容。

如果目录不存在，webclaw 会创建该目录；在 Unix 上，该目录仅对你可读，并会被标记为 webclaw 所有。如果目录既非空，也不是由 webclaw 创建的（例如你用于浏览网页的 Chrome 配置文件），webclaw 会拒绝使用；符号链接也会被拒绝，在 Unix 上，其他用户可写的目录同样会被拒绝。每次运行前，webclaw 都会清除上一次运行留下的标签页和网站注册的 Service Worker，并在配置文件偏好设置中关闭预取，同时保留其他设置。配置文件中保存了你的登录信息，因此请像对待密码一样保护它。上述关于渲染后的页面可访问内容的检查，同样适用于配置文件。

每个配置文件同一时间只能运行一个 webclaw：如果配置文件正在使用，第二次运行会停止并报错，指出占用它的进程，而不会再次打开配置文件，以免造成损坏。使用 Ctrl-C 或 SIGTERM 停止 webclaw 时，会先关闭浏览器；使用 kill -9 后，请停止错误信息中指出的 Chrome。--browser-profile 不能与 --cdp-url 同时使用；MCP 服务通过 WEBCLAW_BROWSER_PROFILE 获取目录。

在我们的基准测试中，使用已预热配置文件时，单次运行渲染一个页面耗时 1.7 秒，使用全新配置文件时耗时 2.1 秒；运行六次后，配置文件在磁盘上约占 9 MB。

捕获页面加载的 JSON

单页应用会以 JSON 格式获取数据，并据此构建页面。使用 browser 构建时，--capture-network 会渲染页面，并将加载的响应作为 JSON 数组打印出来，而不是输出页面，这样你就能获得网站自身 API 返回的 JSON：

webclaw https://quotes.toscrape.com/scroll --capture-network                  # every XHR and fetch response
webclaw https://github.com/rust-lang/cargo --capture-network=latest-commit
webclaw https://quotes.toscrape.com/scroll --scroll --capture-network=/api/quotes
webclaw https://example.com --capture-network --capture-types all             # documents, scripts, images too

每个响应都包含其 url、method、status、resource_type、mime_type、页面设置的 request_headers，以及文本响应（JSON、HTML、JavaScript、XML、纯文本）的 body。二进制响应体不会包含在内。模式是 URL 必须匹配的正则表达式，写在等号后面。除非 --capture-types 指定其他类型，否则只保留 xhr 和 fetch 响应；该参数接受以逗号分隔的浏览器资源类型列表，或 all。最多保留 100 个响应，每个响应体最多截取至 1 MB，所有响应体合计最多 5 MB；被截取的响应体会设置 truncated。

除非传入 --capture-credentials，否则名称标示凭据的请求标头（Authorization、API 密钥、令牌、会话、签名）会被省略；名称含义相同的 URL 查询参数（如 access_token 或 key）会被读取为 REDACTED。Cookie 是页面发送请求后由浏览器添加的，因此不会出现在其中。响应体会按网站发送的原样保留，因此网站在 JSON 中返回的令牌仍会出现在输出中；分享前请检查内容。

捕获渲染会等待所有可能保留的请求完成，且连续 1 秒没有新请求开始；最长等待时间为 --timeout 的三分之一，然后读取响应。页面在此之后发起的请求不会被捕获；使用 --wait-for 或 wait 步骤可以捕获这些请求。使用 --actions 或 --scroll 时，会先执行这些步骤，因此它们触发的响应也会被捕获。如果渲染失败或超时，命令会失败且不会打印任何响应。

捕获功能只能看到浏览器获准加载的内容：被上述地址检查或 --block 拦截的请求不会产生响应，来自私有地址的响应也会被省略。跨站框架或专用 Worker 自行发出的请求不会被捕获。如果页面将数据直接嵌入 HTML 中，就不会调用 API，因此没有内容可捕获：请读取页面本身，或使用 --capture-types document 保留其文档。MCP scrape 工具接受与 capture_network、capture_types 和 capture_credentials 相同的选项；为适配模型上下文，每个响应体最多截取至 100 KB，所有响应体合计最多 1 MB。响应会在内容之后返回；若设置 format: "json"，则会放在 network 下。

抓取文档站点

webclaw https://docs.rust-lang.org --crawl --depth 2 --max-pages 50

--delay（默认 100 ms）是向同一主机发出的两次页面请求之间的最短间隔，由所有 --concurrency 个工作线程共享，因此提高并发数也不会让同一站点每隔不到一个 --delay 就开始一次页面请求。robots.txt 和站点地图请求完成后，抓取器会再等待一个 --delay 才请求第一个页面。遵循 robots.txt 时，每次重定向跳转也算一次请求；使用 --ignore-robots 时，重定向会在一次抓取中跟随，跳转之间不设间隔。--delay 0 会关闭请求间隔。抓取器会遵循站点的 robots.txt：跳过不允许访问的 URL，并遵守 Crawl-delay；如果它比 --delay 长，则用它代替 --delay。传入 --ignore-robots 可关闭此行为。遵循 robots.txt 时，每次重定向都会在跟随前检查其是否符合 robots.txt 和抓取范围；如果重定向到的是仅添加了斜杠或更改了协议的同一页面，则会抓取一次，而不是直接舍弃。同一路径在 http:// 和 https:// 下，无论是否带尾部斜杠，都算作同一页面；指向起始 URL 主机、但使用另一种协议的链接，会按起始 URL 的协议抓取。

对于长时间抓取，可将页面以 JSON 行流式输出，并为抓取过程创建检查点，以便崩溃或终止后从停止处恢复。检查点不会记录上次请求该站点的时间，因此快速重启后，首次请求与上一次运行中的最后一次请求之间可能不足 --delay：

webclaw https://docs.rust-lang.org --crawl --max-pages 0 -f jsonl --crawl-state crawl.json >> pages.jsonl

为抓取指定一个问题后，它会优先获取最可能回答该问题的链接，而不是逐层抓取：

webclaw https://docs.python.org/3/ --crawl --depth 4 --max-pages 25 \
  --query "How do I sort a list of dictionaries by a key?"

每个链接的评分取决于问题中的词语在其文本、URL 路径和周围段落或列表项中的出现情况，以及链接所在页面回答问题的程度；许多页面都共有的词语权重较低。随后，每个页面只保留能回答问题的部分，并附带一个 0 到 1 的 relevance 值；输出会按页面匹配度从高到低排列（使用 -f jsonl 时则按抓取顺序流式输出）。--max-pages 是抓取预算。使用相同的 --query 恢复 --crawl-state 时，会保留抓取顺序。MCP crawl 工具接受相同的 query，最多 1,000 个字符。

添加 --stop-when-answered 后，一旦看起来已找到答案，抓取就会在预算用尽前结束：当评分至少为 0.8 的页面已抓取完成，且之后抓取的 8 个页面评分都不高于它时，就不会再启动新页面。已经开始抓取的页面仍会完成。在我们的基准测试中，对于该规则所针对的 60 个问题，预算为 50 页时，平均抓取了 32 页，而不是 50 页；对于 48 个留出问题，平均抓取了 39 页，但有一个完整抓取能找到的答案未能找到：一个包含问题中所有词语、却没有回答问题的页面较早获得了 1.0 分。选择该规则时也参考了这些留出问题。在规则确定后编写的、涉及另外四个站点的 48 个问题中，它保留了完整抓取找到的全部 40 个答案，抓取了 44 页而不是 50 页，减少约 10%：这 48 次抓取中只有 10 次有页面获得 0.8 分。因此，在大多数站点上，预计只能节省少量抓取量。如果没有页面获得 0.8 分，抓取会持续到预算用尽；其他语言的问题很少能达到 0.8 分。MCP crawl 工具接受与 query 配合使用的 stop_when_answered: true；webclaw-fetch 中的 CrawlConfig::stop_when_answered 也有相同作用。

评分基于词语匹配，因此最适用于英文问题；使用其他语言的问题需要更晚才会找到对应页面（基准测试中的日语、法语、西班牙语和中文问题：截至第 10 页找到 16 个问题中的 3 个答案，中位数为 18 页；在权重未针对其进行调优的站点上，英文问题则是 48 个问题中找到 33 个答案，中位数为 6 页）。问题中只有前 32 个不同的词语会参与评分。

列出网站的 URL

webclaw https://docs.python.org/3/ --map
webclaw https://docs.python.org/3/ --map --map-source sitemap,cc --path-prefix /3/library \
  --query "cancel an asyncio task" --map-limit 20

--map 会列出网站的 URL，而不提取其内容：每行一个，或使用 -f json 输出 JSON 数组。它会读取网站的 robots.txt 中声明的站点地图（或常见的站点地图路径）；如果其中的 URL 少于 200 个，还会通过一次短暂爬取补充找到的链接（使用 --no-map-crawl 可通过 --map-pages 关闭）。每个页面只列出一次：仅在 http/https、www.、尾部斜杠、片段或跟踪参数（utm_*、ref、fbclid、gclid）上有所不同的 URL 会被视为同一个 URL。--crawl 会将页面的 www. 和裸域名 URL 分开处理。

--map-source sitemap,cc 还会查询公共的 Common Crawl 索引，获取其最新一次爬取中捕获的该网站页面，从而找到站点地图未列出、且短暂爬取无法触及的页面。--map-source cc 则只查询索引。只保留该网站自身主机（有或没有 www.）上返回状态码 200 且内容为 HTML 的页面，并移除其跟踪参数；使用 --map-all-captures 可保留重定向、错误和其他文件。如果站点地图已提供 --map-limit 指定数量的 URL，且没有 --query，就不会查询索引。

该索引是免费的共享服务，因此 webclaw 每次只发送一个请求，间隔一秒；遇到繁忙响应时会重试两次，并将整个查询的时限设为 2 分钟。查询通常需要 10 到 60 秒，有时也会不可用；如果索引停止响应，webclaw 会发出警告并列出截至当时找到的 URL，只有一个也没找到时才会失败。请注意：

• 最多读取 10 页索引结果（约 150,000 个捕获记录）。索引按 URL 排序，因此对于大型网站，这只是其中一段按字母顺序排列的内容，并非样本；--query 也只会对这段内容排序。
• 一次爬取不会捕获所有页面。在最新集合中，小型网站可能只有几十条捕获记录；你知道存在的页面也可能缺失。

--path-prefix、--include-paths 和 --exclude-paths 会像筛选爬取结果一样筛选列表，备用爬取也会在这些路径范围内消耗页面数。--query 会根据 URL 路径中的词语，按匹配度从高到低列出 URL；较少出现在该网站路径中的词权重更高，并将完整词语匹配排在查询词仅作为前缀的较长词之前（例如，查询词为 “auto” 时，auto.html 排在 autovacuum.html 之前）。它不会读取任何页面，因此只有当 URL 名称能体现主题时才有帮助：查询 “cancel an asyncio task” 时，asyncio-task.html 会排在 docs.python.org URL 中的首位。--map-limit 会在排序后保留前 N 个结果。MCP map 工具接受 source、limit 和 query。

在我们的基准测试中，针对 10 个网站（包括文档、新闻、商店和博客，其中一半没有站点地图），--map-source sitemap,cc 在网站自身主机上找到了 44,122 个 URL，而普通 --map 找到了 17,026 个；抽样结果中有 96% 返回状态码 200 且内容为 HTML。尽管如此，在我们测量当天，索引仍有 4 个网站查询失败。请参阅基准测试。

工作流示例

• 将 HTML 转换为 Markdown，用于 RAG
• 兼容 Firecrawl 的 API
• MCP 网页抓取
• 通过 ColdProxy 使用代理爬取
• Cloudflare 诊断

提取品牌素材

webclaw https://github.com --brand

随时间比较页面

webclaw https://example.com/pricing --format json > pricing-old.json
webclaw https://example.com/pricing --diff-with pricing-old.json

MCP 服务端

webclaw 随附一个供 AI Agent 使用的 MCP 服务。

无需安装——将任意 MCP 客户端指向 npx 启动器：

{
  "mcpServers": {
    "webclaw": {
      "command": "npx",
      "args": ["-y", "@webclaw/mcp"]
    }
  }
}

也可以运行 npx create-webclaw，自动检测你的 AI 工具并为你写入配置。

通过 HTTP

若要让多个 Agent 共用一个服务，或从另一台机器访问它，请通过流式 HTTP 提供服务：

WEBCLAW_MCP_TOKEN=$(openssl rand -hex 16) webclaw-mcp --http 127.0.0.1:8000

客户端连接到 http://127.0.0.1:8000/mcp 并发送 Authorization: Bearer <token>：

{
  "mcpServers": {
    "webclaw": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

如果未提供令牌，服务会拒绝通过 HTTP 启动，因为任何能访问它的人都可以让机器获取任意 URL；使用 --no-auth 则会开放服务。使用环回地址时，服务还会拒绝 Host 标头中指向其他主机的请求，从而阻止网页发起 DNS 重绑定攻击。

接下来，可以向你的 Agent 提出这样的问题：

Scrape these competitor pricing pages and summarize the differences.

Crawl this documentation site and prepare clean context for a RAG index.

Extract the brand colors, fonts, and logos from this company website.

用作 Agent 技能

只需运行一条命令，即可将 webclaw 添加到 Claude Code、Cursor、Windsurf 和其他 MCP Agent：

npx skills add 0xMassi/webclaw-skill

你的 Agent 就能将抓取、爬取、映射、提取、摘要、对比、品牌分析和搜索作为原生工具使用。大多数网站都能在本地提取，无需 API 密钥。设置 WEBCLAW_API_KEY，即可处理受机器人防护的网站和使用 JavaScript 渲染的页面。

可在 skills.sh 上找到它。

工具

SDK

npm install @webclaw/sdk
pip install webclaw
go get github.com/0xMassi/webclaw-go

import { Webclaw } from "@webclaw/sdk";

const client = new Webclaw({ apiKey: process.env.WEBCLAW_API_KEY! });

const page = await client.scrape({
  url: "https://example.com",
  formats: ["markdown"],
  only_main_content: true,
});

console.log(page.markdown);

from webclaw import Webclaw

client = Webclaw(api_key="wc_your_key")

page = client.scrape(
    "https://example.com",
    formats=["markdown"],
    only_main_content=True,
)

print(page.markdown)

curl -X POST https://api.webclaw.io/v1/scrape \
  -H "Authorization: Bearer $WEBCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "only_main_content": true
  }'

输出格式

本地优先，按需使用托管服务

CLI 和 MCP 服务的核心提取功能可在本地运行，无需账户。

需要以下功能时，请使用 webclaw.io 上的托管 API：

• 无需管理基础设施即可访问受保护的网站
• JavaScript 渲染
• 异步爬取和研究任务
• 网络搜索
• 监控和生产环境用量跟踪
• 用于应用程序代码的 SDK

export WEBCLAW_API_KEY=wc_your_key

webclaw https://example.com --cloud

可构建的应用

架构

webclaw/
  crates/
    webclaw-core     HTML to markdown, text, JSON, and LLM-ready output
    webclaw-fetch    Fetching, crawling, batching, and mapping
    webclaw-llm      Local and hosted LLM provider support
    webclaw-pdf      PDF text extraction
    webclaw-mcp      MCP server for AI agents
    webclaw-cli      Command-line interface

webclaw-core 是纯粹的提取逻辑：不执行网络 I/O，接口精简，并且可脱离抓取层独立使用。

配置

贡献

目前最有帮助的贡献是实用且小规模的改进：

• 为真实的 Agent 和 RAG 工作流添加示例
• 改进 SDK 代码片段
• 报告提取效果不佳的网页
• 为复杂 HTML 添加失败测试样例
• 改进面向 MCP 客户端和本地设置的文档
• 在更多 Linux/macOS 环境中测试 CLI

以下是一些适合入门的地方：

• 适合新手的议题
• 提交错误报告
• 发起讨论

如果某个网页的提取效果很差，请提供：

URL:
Command or API request:
Expected output:
Actual output:
Format used: markdown / llm / text / json / html
CLI, MCP, SDK, or API:

发布日志前，请移除其中的密钥、Cookie、私有令牌和客户数据。

战略合作伙伴

  <a href="https://serpapi.com/use-cases/web-search-api?utm_source=webclaw">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="./assets/sponsors/serpapi-white.png"
      />
      <img src="./assets/sponsors/serpapi.png" alt="SerpApi" width="720" />
    </picture>
  </a>
</td>

基础设施合作伙伴

ColdProxy 是 webclaw 的基础设施合作伙伴，为公开数据收集、区域测试、监控和网页抓取工作流提供覆盖 195 多个国家/地区的住宅 IPv4、住宅 IPv6 和数据中心 IPv6 代理基础设施。直接访问网站，了解 ColdProxy的最新套餐和优惠。 使用代码 webclaw8Off，首次付款可享 8% 折扣。 查看使用代理进行抓取指南， 了解如何将 ColdProxy 接入 webclaw。

工作室合作伙伴

	NodeMaven：面向网页抓取和自动化的高效代理服务商，提供市场上品质最高的 IP。 为什么选择 NodeMaven？ ZIP 定位 99.9% 正常运行时间 IP 筛选：所有代理的欺诈评分均 <97% 无需 KYC 验证 独特的免费工具：代理带宽检查器、Meta 标签检查器、IP 查询等！ 面向 Webclaw 用户的专属优惠码： WEBCLAW35 - 移动代理和住宅代理优惠 35% WEBCLAW40 - ISP（静态）代理优惠 40%
	MangoProxy 在 200 多个地点提供住宅、ISP、数据中心和移动代理，拥有超过 9,000 万个 IP 的资源池，支持 HTTP 和 SOCKS5，稳定性高，适用于大规模网页抓取和数据收集。 在 mangoproxy.com 使用优惠码 0XMASSI，即可享受 ISP（静态）代理 8% 优惠。
	Thordata：面向开发者的优质住宅代理。借助干净的住宅 IP 和稳定的代理基础设施，构建可靠的爬虫、AI Agent 和自动化工作流。 为什么选择 Thordata？ 覆盖 195 多个 GEO，拥有超过 1 亿个 IP 并发连接数不受限制 99.99% 正常运行时间，连接稳定 轮换会话 + 粘性会话 Webclaw 专属优惠：免费试用 3 天 WEBCLAW - 优惠 10%

社区插件

可与 AI Agent 平台集成的第三方插件：

构建了 webclaw 集成？提交 PR，将其添加到这里。

贡献者

感谢所有通过问题反馈、示例、文档、错误报告和拉取请求改进 webclaw 的人。

Star History

License

AGPL-3.0-only