firecrawl

Firecrawl 与 Jina 网页抓取

Firecrawl 与 WebFetch 对比

优先使用 firecrawl scrape URL --only-main-content，而不是 WebFetch 工具——它生成的 Markdown 更整洁，能处理 JavaScript 密集型页面，并避免内容截断（基准测试覆盖率超过 80%）。Firecrawl 不可用时，可将 WebFetch 作为备用方案。

# Preferred approach:
firecrawl scrape https://docs.example.com/api --only-main-content

无密钥模式（v2.11.0+）

Firecrawl 的核心端点无需 API 密钥即可使用，但会按 IP 地址进行每日速率限制。无需注册。

符合无密钥使用条件的命令： Search、Scrape、Parse、Interact 需要 API 密钥： Crawl、Map、Batch Scrape、Agent、Extract、Monitor

# Quick start — no API key needed:
firecrawl scrape https://example.com --only-main-content
firecrawl search "query" --limit 10

# Python script also works keyless for eligible commands:
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape https://example.com

速率限制： 每个 IP 每日的请求数和额度均有限制（具体数字未公布，每天低于 1,000 个额度）。注册免费 API 密钥，即可获得 1,000 个额度和更高的速率限制。

无密钥 MCP 端点： https://mcp.firecrawl.dev/v2/mcp — 无需密钥即可使用 Search、Scrape、Parse。适用于原生 MCP 集成。

完整设置（推荐用于更繁重的使用）：

npx -y firecrawl-cli@latest init --all --browser
# Installs CLI + skill segments into coding agents + opens browser for OAuth auth

搜索准确率： SimpleQA 上达到 94.7%——自定义相关性模型会根据你的查询对段落进行评分，返回最相关的摘录，所需 token 比整页处理少 10 倍。

高效利用 token 的抓取

此方法受 Anthropic 的动态过滤启发——始终先过滤，再进行推理。在其基准测试中，这使输入 token 减少约 24%，准确率提高约 11%。

原则：搜索 → 过滤 → 抓取 → 过滤 → 推理

建议：

Search (titles/URLs only) → Evaluate relevance → Scrape top hits → Filter by section → Reason

不建议：

Search → Scrape everything → Reason over all of it

高效工作流步骤

# Step 1: Search — get titles/URLs only (cheap)
firecrawl search "query" --limit 20

# Step 2: Evaluate results, pick 3-5 best URLs

# Step 3: Scrape only those, filter to relevant sections
firecrawl scrape URL1 --only-main-content | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py \
  --sections "API,Authentication" --max-chars 5000

使用 filter_web_results.py 进行后处理

将任何 Firecrawl 或 Exa 输出通过此脚本传递，在推理前缩减上下文：

# Extract only matching sections from scraped page
firecrawl scrape URL --only-main-content | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --sections "Pricing,Plans"

# Keep only paragraphs with keywords
firecrawl search "query" --scrape --pretty | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --keywords "pricing,cost" --max-chars 5000

# Extract specific JSON fields from API output
python3 ~/.claude/skills/exa-search/scripts/exa_search.py "query" --json | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --fields "title,url,text" --max-chars 3000

# Combine filters with stats
firecrawl scrape URL --only-main-content | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --sections "API" --keywords "endpoint" --compact --stats

完整路径： python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py 标志： --sections、--keywords、--max-chars、--max-lines、--fields（JSON）、--strip-links、--strip-images、--compact、--stats

其他节省 token 的模式

• 使用 --only-main-content 去除导航和页脚的冗余内容，减少 token 消耗。只有在确实需要导航或页脚内容时才省略此选项。
• 使用 --only-clean-content（Python API 脚本）进行强力清理——去除导航、广告和 Cookie 横幅。其效果比 --only-main-content 更强；如果经过正文过滤后页面仍然杂乱，可使用此选项。
• 先使用 firecrawl map URL --search "topic" 查找相关子页面，再进行抓取
• 先使用 --format links 获取 URL 列表并进行评估，然后有选择地抓取
• 将 --max-chars 与 exa_contents.py 搭配使用，以限制提取长度
• 需要概要而非原始内容时，使用 --formats summary（Python API 脚本），而不是全文

Claude API 原生工具（适用于 API Agent 构建者）

Anthropic 的 API 现已提供内置的动态过滤工具：

web_search_20260209 / web_fetch_20260209
Header: anthropic-beta: code-execution-web-tools-2026-02-09

这些工具通过代码执行内置了动态过滤。直接构建 Claude API Agent 时可使用这些工具。需要自主 Agent、批量抓取、结构化提取、特定领域的爬取，或未使用 Claude API 时，请使用 Firecrawl/Exa。

---

可用工具

1. 官方 Firecrawl CLI（firecrawl）— 主要工具

无密钥设置： npm install -g firecrawl-cli@latest（search/scrape/parse/interact 可立即使用） 完整设置： npm install -g firecrawl-cli@latest && firecrawl login --api-key $FIRECRAWL_API_KEY Agent 设置： npx -y firecrawl-cli@latest init --all --browser（安装 CLI + 技能 + OAuth）

命令	用途	快速示例
scrape	单个页面 → markdown	firecrawl scrape URL --only-main-content
crawl	抓取整个网站并显示进度	firecrawl crawl URL --wait --progress --limit 50
map	发现网站上的所有 URL	firecrawl map URL --search "API"
search	网页搜索，SimpleQA 准确率为 94.7%（可选抓取）	firecrawl search "query" --limit 10

完整 CLI 参考： references/cli-reference.md

2. 自动保存别名（fc-save）——Shell 别名

需要配置 Shell 别名（本技能不包含此配置）。

fc-save URL
# → Saves to ~/Desktop/Screencaps & Chats/Web-Scrapes/docs-example-com-api.md

3. Python API 脚本（firecrawl_api.py）——高级功能

命令： python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py <command> 需要： pip install firecrawl-py requests。对于无需密钥的命令（search、scrape、parse、interact），FIRECRAWL_API_KEY 为可选项；对于其他所有命令，则为必需项。

命令	用途	快速示例
search	搜索网页并进行抓取	firecrawl_api.py search "query" -n 10
scrape	执行页面操作的单个 URL	firecrawl_api.py scrape URL --formats markdown summary
batch-scrape	并发抓取多个 URL	firecrawl_api.py batch-scrape URL1 URL2 URL3
crawl	爬取网站	firecrawl_api.py crawl URL --limit 20
map	发现 URL	firecrawl_api.py map URL --search "query"
parse	解析本地文档（PDF、DOCX、XLSX）	firecrawl_api.py parse report.pdf
extract	由大模型驱动的结构化提取	firecrawl_api.py extract URL --prompt "Find pricing"
agent	自主提取（无需 URL）	firecrawl_api.py agent "Find YC W24 AI startups"
parallel-agent	批量 Agent 查询（v2.8.0+）	firecrawl_api.py parallel-agent "Q1" "Q2" "Q3"
interact	抓取后的浏览器交互	firecrawl_api.py interact SCRAPE_ID --prompt "Click pricing"
interact-stop	停止交互会话	firecrawl_api.py interact-stop SCRAPE_ID

Agent 模型： spark-1-fast（10 积分，适用于简单任务）、spark-1-mini（默认）、spark-1-pro（适用于深入任务）

完整的 Python API 参考： references/python-api-reference.md

4. DeepWiki —— GitHub 仓库文档

~/.claude/skills/firecrawl/scripts/deepwiki.sh <owner/repo> [section] [options]

为任何公开的 GitHub 仓库生成 AI Wiki。无需 API 密钥。

# Overview
~/.claude/skills/firecrawl/scripts/deepwiki.sh karpathy/nanochat

# Browse sections
~/.claude/skills/firecrawl/scripts/deepwiki.sh langchain-ai/langchain --toc

# Specific section
~/.claude/skills/firecrawl/scripts/deepwiki.sh karpathy/nanochat 4.1-gpt-transformer-implementation

# Full dump for RAG
~/.claude/skills/firecrawl/scripts/deepwiki.sh openai/openai-python --all --save

5. Jina Reader（jina）——备用方案

Firecrawl 失败时，或处理 Twitter/X URL 时使用（Firecrawl 会拦截 Twitter，Jina 则可以正常工作）。

jina https://x.com/username/status/123456

---

Firecrawl、Exa 与原生 Claude 工具对比

需求	最佳工具	原因
免费抓取，无需 API 密钥	firecrawl scrape (keyless)	核心命令无需身份验证即可使用
免费搜索，无需 API 密钥	firecrawl search (keyless)	SimpleQA 准确率达 94.7%，无需密钥
单个页面 → Markdown	firecrawl scrape --only-main-content	输出最简洁
一次性完成搜索和抓取	firecrawl search --scrape	合并操作
抓取整个网站	firecrawl crawl --wait --progress	跟随链接并显示进度
本地文件 → Markdown	firecrawl_api.py parse FILE	直接上传，无需 URL
自主查找数据	firecrawl_api.py agent	无需 URL
语义／神经网络搜索	Exa exa_search.py	AI 驱动的相关性排序
查找研究论文	Exa --category "research paper"	学术索引
快速获取研究答案	Exa exa_research.py	引文 + 综合分析
查找相似页面	Exa exa_similar.py	竞争分析
构建 Claude API Agent	原生 web_search_20260209	内置动态过滤
Twitter/X 内容	jina URL	唯一可用的工具
GitHub 仓库文档	deepwiki.sh owner/repo	AI 生成的 Wiki
绕过反机器人机制／Cloudflare	scrapling 隐身抓取	本地 Turnstile 求解器
提取页面元素	scrapling + CSS 选择器	精确定位、自适应跟踪
无 API 密钥抓取	scrapling HTTP 抓取	100% 本地运行，无需凭据
适应网站重新设计	scrapling 自适应模式	SQLite 相似度匹配
经济实惠地抓取 JS 渲染页面	cf_browser.py markdown URL	CF 免费层：每天 10 分钟；付费为 $0.09/小时
免费抓取静态页面	cf_browser.py markdown URL --no-render	Beta 期间免费（不执行 JS）
经济实惠地抓取多个页面	cf_browser.py crawl URL	每天免费抓取 5 次，每次最多 100 个页面
增量重新抓取	cf_browser.py crawl --modified-since	内置功能，Firecrawl 不支持
页面截图／PDF	cf_browser.py screenshot/pdf URL	内置 CF 端点，费用更低
AI 结构化提取	cf_browser.py json URL --prompt "..."	免费包含 Workers AI

---

常见工作流

抓取单个页面

firecrawl scrape https://example.com/page --only-main-content
# Or auto-save: fc-save URL
# Or to file: firecrawl scrape URL --only-main-content -o page.md

抓取文档

# Map first, then crawl relevant paths
firecrawl map https://docs.example.com --search "API"
firecrawl crawl https://docs.example.com --include-paths /api,/guides --wait --progress

研究工作流

firecrawl search "machine learning best practices 2026" --scrape --scrape-formats markdown

文档解析（本地文件）

将本地文档解析为整洁的 Markdown。本地或非公开文件使用 parse；指向文档的公开 URL 使用 scrape——两者使用相同的基于 Rust 的解析器。

# PDF to markdown
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py parse report.pdf

# Excel spreadsheet with main content only
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py parse data.xlsx --only-main-content

# Word doc with zero data retention, save to file
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py parse contract.docx --zero-data-retention -o contract.md

# Raw JSON output for programmatic use
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py parse invoice.pdf --json

支持的格式：PDF、DOCX、DOC、XLSX、XLS、HTML、HTM、ODT、RTF（最大 50 MB）。

PDF 解析（Fire-PDF v2.9）

Fire-PDF 现已成为所有 PDF 抓取任务的默认解析流程。提供三种模式：

# Auto mode (default) — detects text layer vs scanned, chooses best method
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape "https://example.com/report.pdf"

# Fast mode — text layer only, skip OCR (use for PDFs with selectable text)
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape URL --pdf-mode fast

# OCR mode — force full OCR (use for scanned docs or image-only PDFs)
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape URL --pdf-mode ocr

# Limit pages parsed (large documents)
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py parse report.pdf --pdf-mode auto --pdf-max-pages 20

标志	值	说明
--pdf-mode	fast、auto、ocr	默认值：auto。fast = 仅使用文本层；ocr = 强制使用 OCR
--pdf-max-pages	整数	限制解析的页数；适用于控制大型 PDF 的费用

两个标志均适用于 scrape（针对 PDF URL）和 parse（针对本地文件）。

Agent 驱动的研究（无需 URL）

python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py agent \
  "Compare pricing tiers for Firecrawl, Apify, and ScrapingBee"

Interact 工作流（抓取后的浏览器交互）

抓取页面后，可对其执行操作——点击按钮、填写表单、提取动态内容。提供两种模式：AI 提示词（自然语言）和代码执行（Node.js/Python/Bash）。

何时使用 Interact，何时使用 Actions

需求	使用	原因
单次抓取前点击／等待	在 scrape 上使用 --actions	发起后即不再处理，无会话开销
与同一页面进行多次交互	interact	持久会话，可来回交互
填写表单、登录、导航	interact	有状态，支持多步骤
简单地“等待 JS 加载”	使用 wait 的 --actions	费用更低，无需会话

基本 Interact（AI 提示词模式）

# Step 1: Scrape and note the Scrape ID from output
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape "https://example.com/pricing"

# Step 2: Interact using natural language
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact SCRAPE_ID \
  --prompt "Click the Enterprise pricing tab"

# Step 3: More interactions on same session
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact SCRAPE_ID \
  --prompt "What is the monthly price for the Enterprise plan?"

# Step 4: Stop when done
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact-stop SCRAPE_ID

代码执行模式（费用更低）

# Execute Playwright code directly (2 credits/min vs 7 for prompts)
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact SCRAPE_ID \
  --code "const text = await page.locator('.pricing-table').textContent(); console.log(text);"

# Python mode
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact SCRAPE_ID \
  --code "text = await page.locator('.content').text_content(); print(text)" \
  --language python

持久化配置文件（登录会话）

# Scrape with a named profile — browser state persists across sessions
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape "https://app.example.com/login" \
  --profile my-app --json

# Interact to log in
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py interact SCRAPE_ID \
  --code "await page.fill('#email', '[email protected]'); await page.fill('#password', 'pass'); await page.click('button[type=submit]');"

# Later: scrape another page with same profile — cookies restored
python3 ~/.claude/skills/firecrawl/scripts/firecrawl_api.py scrape "https://app.example.com/dashboard" \
  --profile my-app

重要提示： Interact 不会返回页面 Markdown。交互后如需获取更新的内容，请使用代码模式提取指定元素，或再执行一次抓取。

完整的 interact 参考： references/interact-reference.md

---

计费说明

• 积分／令牌统一（v2.9）： 积分和令牌现已统一——15 个令牌 = 1 个积分。所有价格均以积分计价。
• 默认缓存 TTL： 结果会缓存 2 天。使用 --max-age 0（或在 API 中设置 maxAge: 0）可强制重新抓取，不受缓存影响。
• query 格式： 传入 formats=["query"]（Python API）即可获取直接答案（data.answer），而非完整 Markdown。适用于无需完整页面内容的事实查询。
• audio 格式： formats=["audio"] 会返回朗读页面内容的 MP3。适用于无障碍工作流或语音界面。
• wikimedia 引擎： 在搜索选项中传入 engine="wikimedia"，即可通过 Wikimedia 执行查询。适用于百科类查询。

故障排除

# Check status and credits
firecrawl --status && firecrawl credit-usage

# Re-authenticate
firecrawl logout && firecrawl login --api-key $FIRECRAWL_API_KEY

# Check API key
echo $FIRECRAWL_API_KEY

• 抓取失败： 尝试使用 jina URL，或为 JavaScript 内容较多的网站添加 --wait-for 3000
• 异步任务卡住： 使用 crawl-status／batch-status 检查，并使用 crawl-cancel／batch-cancel 取消
• 禁用遥测： export FIRECRAWL_NO_TELEMETRY=1

---

参考文档

文件	内容
references/cli-reference.md	完整的 CLI 参数参考（scrape、crawl、map、search、fc-save、jina、deepwiki）
references/python-api-reference.md	完整的 Python API 脚本参考（所有命令、SDK 示例）
references/firecrawl-api.md	Firecrawl Search API 参考
references/firecrawl-agent-api.md	Agent API（spark 模型、并行 Agent、webhook）
references/actions-reference.md	动态内容的页面操作（点击、输入、等待、滚动）
references/interact-reference.md	Interact API：抓取后的浏览器交互（提示词、代码、配置文件）
references/branding-format.md	品牌标识提取（颜色、字体、UI）

测试套件

python3 ~/.claude/skills/firecrawl/scripts/test_firecrawl.py --quick    # Quick validation
python3 ~/.claude/skills/firecrawl/scripts/test_firecrawl.py            # Full suite
python3 ~/.claude/skills/firecrawl/scripts/test_firecrawl.py --test scrape  # Specific test