Octocrawl

Octocrawl

一个链接，网页数据即刻就绪。
为 AI Agent 和 RAG 提供网页中的 Markdown 和数据。
比原始 HTML 占用更少的 token。每条结果都会记录读取方式。

网站 · 文档 · 连接 MCP · 博客 · 更新日志

---

抓取网页。爬取网站。将网页内容转化为可用数据。

Octocrawl 是一款面向 AI Agent、RAG 和研究用途的开源网页抓取与爬取工具包。收集文档以构建知识库，提取产品详情以供比较，或将网页表格和列表转化为数据进行分析。每个页面都附有来源记录。

在浏览器中试用页面，或通过托管 MCP 或 REST API 连接你的 Agent。试用托管服务无需安装，也无需 API 密钥。

Octocrawl 能做什么？

能力	你可以获得什么
抓取页面	获取适用于大模型上下文的可读 Markdown，以及 HTML、链接、图片 URL 和页面元数据。可在浏览器通道中请求截图。
发现网站页面	从站点地图和页面链接中发现 URL，并按搜索词筛选，找到所需页面。
抓取网站或版块	从起始 URL 沿链接抓取并收集每个页面的内容，并支持路径筛选、深度限制和页面数量限制。
批量抓取 URL	提交一批 URL，随着结果到达逐步获取，并保留每个 URL 的处理结果，包括失败情况。
提取结构化数据	将表格和重复条目提取为 JSON 和 CSV；也可传入 JSON Schema，提取产品名称、价格和页面标签等支持的字段。提取指南。
读取动态页面 · 本地操作	在提取内容前渲染 JavaScript、点击控件、滚动页面、加载更多条目并翻页。浏览器操作。
读取 PDF 报告	提取 PDF 的文本层，并附带用于引用的页码标记。CSV、JSON 和纯文本 URL 也会返回其文本。文件支持。
按计划重新访问来源 · 本地工作进程	运行监视器，并将事件发送到 HTTPS 端点，失败时会重试。监视器设置。

托管版 Octocrawl 提供抓取和发现页面功能；拥有账户后，还可使用网站抓取和批量任务（每次抓取最多 500 个页面，每批最多 1,000 个 URL）。无密钥请求使用 HTTP；账户密钥可启用浏览器通道。对于更大型的任务、页面操作和监视器，请在本地运行；设置和可自托管选项请参阅运行 Octocrawl。网页预览是单页试用版，每天可处理 5 个页面，最多支持 20 个命名字段。

为什么选择 Octocrawl？

• 在你的 Agent 中使用网页数据。 通过 MCP 连接 Claude Code、Cursor、OpenCode 或 Codex，也可以使用 REST、TypeScript、Python 和 Vercel AI SDK 构建。
• 默认无需模型即可提取结构化字段。 从页面中读取支持的值，并提供字段证据和明确的缺失值。模型回退为可选功能。
• 了解抓取何时未达预期。 检查功能会标记挑战页面、内容错误、事实缺失、内容截断和内容过少的情况。被拦截和失败的结果会附带原因；已获取的错误页面会保留其状态和 Markdown。结果状态。
• 追溯结果来源。 每个页面都包含一份证据记录，记录其 URL、获取时间、状态和提取证据。未观察到的值会保留为 null。
• 按需运行。 使用托管服务、通过 npx 运行，或使用 Docker Compose 自托管。服务端采用 AGPL-3.0 许可证；客户端库采用 MIT 许可证。

如果 Octocrawl 对你的工作有所帮助，请为仓库点亮星标。

快速开始

将你的 Agent 连接到托管版 Octocrawl。无需密钥即可开始（Claude Code、Cursor、OpenCode 和 Codex 的操作步骤）：

claude mcp add --transport http octocrawl https://mcp.octocrawl.dev/mcp

没有密钥时，每天可通过 HTTP 读取 20 个页面。要读取更多页面，请登录并创建密钥：账户每月可获得 1,000 个积分，并可使用浏览器通道。密钥放在标头中，绝不放在 URL 中：

claude mcp add --transport http octocrawl https://mcp.octocrawl.dev/mcp --header "Authorization: Bearer oc_…"

也可以在自己的电脑上运行。需要 Node.js 22.13+ 或 24+：

npx octocrawl scrape https://example.com --markdown
pip install 'octocrawl-client[pandas]'   # the Python client of a running API (npx octocrawl serve); [pandas] for to_pandas()
npm install @octocrawl/sdk        # the TypeScript client; @octocrawl/mcp is the MCP server
npm install @octocrawl/ai-sdk     # scrape and map as Vercel AI SDK tools, on hosted Octocrawl by default

首先通过 HTTP 读取页面。对于只能在浏览器中显示的页面，请先使用 npx playwright install chromium 安装一次 Chromium；在此之前，这类页面会返回 browser_not_installed 警告，并指出要运行的命令。

要让 Agent 使用所有工具且不受每日限制，请在本地运行 API，并将 MCP 服务连接到该 API：

npx octocrawl serve                                  # keep it running: the API on 127.0.0.1:8787
claude mcp add octocrawl -- npx -y @octocrawl/mcp    # the published stdio server, a client of that API

托管服务提供抓取和映射功能，账户还可使用爬取和批量作业。本地服务还提供更大型的作业、Amazon.sg 商品工具和 Monitor 工具。要自行向其他机器提供服务，npx octocrawl serve --hosted --token <token> 会像托管服务一样拒绝私有地址、忽略 robots 规则的请求和已保存的登录信息。运行 Octocrawl 涵盖这三种方式；Docker Compose 可在你自己的服务器上运行服务。帮你安装 Octocrawl 的 Agent（例如 Cline）可以参考 llms-install.md。

失败时的表现

下面的测试页面会返回 HTTP 200，但显示的是 Cloudflare 检查，而不是页面内容（fixture block-challenge-200）。只信任状态代码的爬虫会将其视为成功。Octocrawl 会先尝试普通 HTTP，再尝试浏览器，并报告页面遭到拦截，同时说明后续该怎么做：

npx octocrawl scrape http://127.0.0.1:8799/block/challenge-200

{
  "status": "blocked",
  "blockReason": "cloudflare_challenge",
  "channelsTried": ["http", "browser_local"],
  "markdown": null,
  "snapshot": { "httpStatus": 200, "artifacts": [] },
  "usage": { "wallMs": 1079, "bytesWire": null, "externalCostUsd": 0 },
  "agentHints": [
    "127.0.0.1 gates automated access on the lanes tried (http, browser_local); … a proxy or session you own is the supported route, or, on your own machine, getting through the check yourself in your own Chrome: handoff: true on a scrape (octocrawl scrape --handoff) …"
  ],
  "evidenceRecord": { "schemaVersion": "w2l.evidence/1", "status": "blocked", "reason": "cloudflare_challenge", "lane": "browser_local", "…": "…" }
}

这是 octocrawl 0.4.1 的实际输出，经过截断（…）和取整，使用的服务器是仓库中的 fixture 服务（FIXTURE_PORT=8799 node --import tsx packages/fixtures/src/cli.ts）。bytesWire: null 表示未测量网络传输字节数；artifacts: [] 表示未生成截图或 DOM 快照。

文档

网站文档位于 octocrawl.dev/docs，涵盖 4 个客户端的 MCP 设置、任务指南和限制。文档由 apps/public-web/content 构建。

完整参考文档位于 docs/：

主题	页面
octocrawl 命令	命令行
托管、本地和可自托管的服务、端口、令牌、代理、robots.txt	运行 Octocrawl
抓取选项及结果包含的内容	抓取选项和结果
多个 URL、整个网站、站点地图、Webhook	批次、爬取和站点地图
根据 JSON Schema 提取结构化数据	JSON 提取
PDF、CSV、XLSX、ZIP 和 JSON URL	文件
登录、增强访问、交接、使用自己的 Chrome	访问
定期重新读取和 HTTPS 事件	监视器
从 Firecrawl 迁移	Firecrawl 兼容层

博客上有真实运行过程的演练：使用 MCP 和 Claude Code 抓取网页、用于 RAG 的网页抓取、查找网站上的所有页面、在自己的 Chrome 中抓取需要登录的网站、无需大模型即可提取结构化数据、抓取 URL 列表并保留所有失败记录。

研究人员可参阅这两份指南，了解真实运行过程：从 URL 列表生成包含证据的 CSV和在论文中引用网页数据。

如需了解 Monitor → 结果 → HTTPS 事件 → 重启工作流，请参阅入门指南。

参与代码开发

你需要 Node.js 22.13+ 或 24+ 和 npm。PDF 引擎 pdf.js 需要 22.13 或更高版本。

git clone https://github.com/77777R7/Octocrawl.git
cd Octocrawl
npm ci
npx playwright install chromium
npm run typecheck
npm test
npm run scrape -- https://example.com --markdown
npm run crawl -- https://example.com --max-pages 20

各软件包从此代码仓库发布。每周，Install check 工作流都会在 macOS、Windows 和 Linux 上从空缓存运行 npx 命令。

名称：Octocrawl 和 w2l

产品名称为 Octocrawl。它早期的工作名称是 W2L（Web-to-LLM）。

部分标识符仍沿用旧名称。它们会保留，直到某次变更有意将其重命名，因为重命名会破坏现有设置和记录：

• 环境变量，例如 W2L_API_PORT 和 W2L_TASK_ROOT；
• 数据目录 .w2l/；
• 内部工作区软件包 @w2l/* 和检出目录中的 w2l 命令（npm run w2l）；
• SDK 类 W2L 和 W2LError；
• Evidence Record 版本 w2l.evidence/1；
• 研究身份标识 w2l-research，网站的 robots.txt 可使用此名称。

已发布的软件包均已使用新名称：octocrawl、@octocrawl/* 和 octocrawl-client。完整列表见 AGENTS.md。

基准测试

针对纯 HTTP 基线运行 fixture 套件：

npm run bench

纯 HTTP 基线故意设置了较高的假成功率。它没有内容提取、挑战检测或重定向处理功能。基准测试展示了预期输出，以及吞吐量和崩溃恢复运行结果。

代码仓库结构

packages/
  contracts/       TypeScript types and ground-truth schema (MIT)
  fixtures/        HTTP server with 56 ground-truth test cases
  http-core/       robots.txt parser (ReDoS-resistant)
  extract-tf/      Content extraction, HTML → Markdown, PDF text
  runtime/         TaskStore, frontier, bounded crawl orchestrator
  bench/           Benchmark runner, ladder CLI (w2l-ladder), scoring
  cli/             octocrawl: scrape, crawl, batch, map, serve (AGPL)
  api/             REST server (AGPL)
  sdk/             TypeScript client (MIT)
  ai-sdk/          scrape and map as Vercel AI SDK tools (MIT)
  mcp/             stdio and restricted Streamable HTTP MCP server (AGPL)
  public-preview/  Server for the public preview at octocrawl.dev

apps/public-web/   The octocrawl.dev site and its docs pages
python/            Python client octocrawl-client (MIT)
examples/          Runnable Monitor + Delivery workflow and webhook receiver
docs/              Reference, guides, ADRs and dated records (index: docs/README.md)
ROADMAP.md         The current phase and what is paused
CHANGELOG.md       Release notes

路线图

ROADMAP.md 从当前阶段的摘要开始。更早的里程碑检查清单见 docs/roadmap/milestones.md。

贡献

我们使用 Developer Certificate of Origin (DCO)，而非 CLA。每次提交都需要一行 Signed-off-by：

git commit -s -m "Your commit message"

有关详情（包括如何编写文档），请参阅 CONTRIBUTING.md。

许可证

服务端代码、CLI（@octocrawl/cli、octocrawl）和 MCP 服务（@octocrawl/mcp）：AGPL-3.0
客户端库：MIT：TypeScript SDK（@octocrawl/sdk，其中包含工作区的 @w2l/contracts，同样采用 MIT 许可证）、AI SDK 工具（@octocrawl/ai-sdk，其中包含该 SDK）以及 Python 客户端（octocrawl-client）

有关其理由，请参阅 PHASE1_ENGINEERING_NOTES.md §1.3。

为什么选择 AGPL？

AGPL 要求以网络服务形式部署的修改继续保持开源。任何人都可以分叉、修改并托管 Octocrawl，只要共享这些修改即可。真正的差异化因素是名称（商标）和托管服务，而非许可证限制。