firecrawl

Firecrawl CLI

搜索、抓取并与网页交互。返回适用于大模型上下文窗口的干净 Markdown。

运行 firecrawl --help 或 firecrawl <command> --help，查看完整选项详情。

如果任务是将 Firecrawl 集成到应用中、向项目添加 FIRECRAWL_API_KEY，或在产品代码中选择端点用法，请使用 firecrawl-build skills。如果任务是成果导向的工作流，例如深入研究、SEO 审计、QA、潜在客户开发、知识库创建、仪表板报告、购物研究或网站设计系统提取，请使用 firecrawl-workflows skills。运行 firecrawl init 时，这些 skills 已与此 CLI skill 一同安装。

先决条件

必须已安装并完成身份验证。使用 firecrawl --status 检查。

  🔥 firecrawl cli v1.8.0

  ● Authenticated via FIRECRAWL_API_KEY
  Concurrency: 0/100 jobs (parallel scrape limit)
  Credits: 500,000 remaining

• 并发数：最大并行任务数。并行操作不得超过此上限。
• 额度：剩余 API 额度。每项操作都会消耗额度。

如果尚未就绪，请参阅 rules/install.md。有关输出处理指南，请参阅 rules/security.md。

开始实际工作前，先发送一个小型请求验证设置：

mkdir -p .firecrawl
firecrawl scrape "https://firecrawl.dev" -o .firecrawl/install-check.md

firecrawl search "query" --scrape --limit 3

工作流

按以下升级模式操作：

1. 搜索 - 尚无具体 URL。查找页面、回答问题、发现来源。
2. 抓取 - 已有 URL。直接提取其内容。
3. 映射 + 抓取 - 网站较大或需要特定子页面。使用 map --search 查找正确的 URL，然后抓取。
4. 爬取 - 需要批量获取整个网站版块的内容（例如，所有 /docs/）。
5. 监控 - 需要定期检查或持续提醒。优先使用 --page 加 --goal 设置监控，而不是反复进行一次性抓取。
6. 交互 - 先抓取，再与页面交互（分页、模态框、表单提交、多步骤导航）。

需求	命令	适用场景
查找某主题的页面	search	尚无具体 URL
获取页面内容	scrape	已有 URL，页面为静态页面或由 JS 渲染
查找网站内的 URL	map	需要定位特定子页面
批量提取网站版块内容	crawl	需要获取多个页面（例如，所有 /docs/）
AI 驱动的数据提取	agent	需要从复杂网站提取结构化数据
与页面交互	scrape + interact	内容需要点击、填写表单、分页或登录
将网站下载为文件	download	将整个网站保存为本地文件
解析本地文件	parse	磁盘上的文件（PDF、DOCX、XLSX 等）——不是 URL
监视页面变化	monitor	安排定期抓取/爬取，并与快照进行差异比较

运行 firecrawl <command> --help，查看详细的命令参考。

抓取与交互：

• 首先使用 scrape。它支持静态页面和 JS 渲染的 SPA。
• 当需要与页面交互时，使用 scrape + interact，例如点击按钮、填写表单、浏览复杂网站、无限滚动，或 scrape 无法抓取所需的全部内容时。
• 切勿使用 interact 进行网页搜索——请改用 search。 监控： 安排定期抓取或爬取，并将每次结果与上一次保留的快照进行比较。当用户的目标是持续检测变化、接收提醒或长期重复检查时，优先使用 monitor。对于单个页面，默认使用 --page <url> 和 --goal "..." 设置监控。适用于产品页面、文档、博客、更新日志、竞争对手网站——任何变化都值得关注的页面。每个监控都应包含简短的 goal，说明哪些变化值得关注；每次检查都会将页面标记为 same、new、changed、removed 或 error，并提供 webhook 和电子邮件通知选项。

编写 --goal 时，将用户的监控意图转化为简洁的 2-3 句监控目标，风格类似 Web 应用的设置流程：

• 以 Alert when ... 开头，并根据用户明确表达的意图说明什么情况应触发提醒。
• 重申用户提到的范围，例如前 N 项、价格、职位类型、公司、地区、主题、状态或特定实体。
• 只有当请求中明确体现了与意图相关的排除项时，才添加 Ignore ... 句子，例如排名中的积分/评论、定价中的无关营销文案，或职位监控中的一般公司页面更新。
• 不要在每个目标中重复通用的噪声排除项；判断器已会处理空白、大小写、标点、编码、仅格式变化、请求/会话 ID、缓存破坏参数、跟踪参数、通用元数据噪声以及无关的页面元素。
• 除非用户提到，否则不要自行编造页面专属版块、实体、阈值、排除项或业务规则。
• 如果用户的意图含糊不清，应保持目标宽泛，不要猜测排除项。
• 如果用户要求“任何变化”，应保留这一点，不要添加排除项。
• 如果用户提到不在意的噪声，应明确写入。

好的目标示例：

• 用户意图：top 10 hackernews stories 目标：当故事进入、离开 Hacker News 前 10 名或排名发生变化时提醒。忽略积分、评论和时间戳。前 10 名之外的变化不触发提醒。
• 用户意图：pricing changes 目标：当定价信息发生变化时提醒，包括价格、套餐名称、计费周期、等级、限额或包含的功能。忽略无关的营销文案、用户评价以及区域货币显示变化，除非实际优惠内容发生变化。
• 用户意图：new engineering roles 目标：发布新的工程职位时提醒。忽略一般公司页面更新，除非其新增、删除或更改了工程职位。
• 用户意图：track this page 目标：当此页面上实质性的可见内容发生变化时提醒。
• 用户意图：any change 目标：当页面上任何可见内容发生变化时提醒，包括文案、数字、时间戳、计数器、链接和布局文本。

子命令：create | list | get | update | delete | run | checks | check。

# create from flags
firecrawl monitor create --name "Blog" --schedule "every 5 minutes" \
  --goal "Alert when a new blog post is published." \
  --page https://example.com/blog --email [email protected]

# multiple pages
firecrawl monitor create --name "Product pages" --schedule "every 5 minutes" \
  --goal "Alert when pricing, docs, or changelog content changes." \
  --scrape-urls https://example.com/pricing,https://example.com/docs,https://example.com/changelog

# webhook notifications
firecrawl monitor create --name "Docs webhook" --schedule "every 5 minutes" \
  --goal "Alert when docs content changes." \
  --page https://example.com/docs \
  --webhook-url https://example.com/webhook \
  --webhook-events monitor.page,monitor.check.completed

# or from JSON (positional file, or piped stdin)
firecrawl monitor create monitor.json
cat monitor.json | firecrawl monitor create

firecrawl monitor list --limit 20
firecrawl monitor run <monitorId>             # trigger a check now
firecrawl monitor checks <monitorId>          # list checks
firecrawl monitor check <monitorId> <checkId> --page-status changed
firecrawl monitor update <monitorId> --state paused
firecrawl monitor delete <monitorId>

计划可使用 cron（--cron "*/5 * * * *"）或自然语言（--schedule "every 5 minutes"）。最短间隔为 5 分钟。目标可以是单个页面（--page <url>）、多个抓取 URL（--scrape-urls a,b,c），也可以是每次检查时进行全站爬取（--crawl-url <url>）。基于标志创建监控时使用 --goal，也可以在 JSON 负载中包含 "goal": "..."。注意：--state（而非 --status）用于设置 active/paused；--page-status（而非 --status）用于在 check 时筛选页面结果，以避免与全局 --status 标志冲突。零数据保留团队无法使用监控功能。

JSON 模式的变更跟踪： 默认情况下，监控会比较每个页面的 markdown，并返回统一文本差异。如果你关注的是特定结构化字段（价格、标题、库存标志、列表中的项目），而非整个页面，请在目标的 scrapeOptions.formats 中添加带有 modes: ["json"] 和 JSON 架构的 changeTracking 格式。基于标志的形式不支持此功能——请通过文件或标准输入传入 JSON 请求体：

cat > pricing-monitor.json <<'EOF'
{
  "name": "Pricing watch",
  "goal": "Alert when plan prices or headline features change",
  "schedule": { "text": "hourly", "timezone": "UTC" },
  "targets": [{
    "type": "scrape",
    "urls": ["https://example.com/pricing"],
    "scrapeOptions": {
      "formats": [{
        "type": "changeTracking",
        "modes": ["json"],
        "prompt": "Extract pricing tiers and headline features for each plan.",
        "schema": {
          "type": "object",
          "properties": {
            "plans": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name":     { "type": "string" },
                  "price":    { "type": "string" },
                  "features": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        }
      }]
    }
  }]
}
EOF
firecrawl monitor create pricing-monitor.json

check 响应随后会包含逐字段差异（路径如 plans[0].price）以及本次运行的完整提取结果，而不是（或除了）Markdown 差异。pages[] 中每个发生变化的页面如下所示：

{
  "url": "https://example.com/pricing",
  "status": "changed",
  "diff": {
    "json": {
      "plans[0].price": { "previous": "$19/mo", "current": "$24/mo" },
      "plans[1].features[2]": {
        "previous": "10 GB storage",
        "current": "25 GB storage"
      }
    }
  },
  "snapshot": {
    "json": {
      "plans": [
        /* current full extraction */
      ]
    }
  }
}

使用 modes: ["json", "git-diff"] 启用混合模式：你会同时获得 diff.json（逐字段）和 diff.text（Markdown 附加文件），只要任一内容发生变化，该页面就会标记为 changed。对于仅监控 Markdown 的场景，diff.text 包含统一差异，diff.json 是 parse-diff AST（{ files: [...] }）；此时没有 snapshot。

避免重复抓取：

• search --scrape 已经会抓取完整页面内容。不要再次抓取这些 URL。
• 再次抓取前，先检查 .firecrawl/ 中是否已有数据。

何时加载参考资料

• 先搜索网页或查找来源 -> firecrawl-search
• 抓取已知 URL -> firecrawl-scrape
• 查找已知网站上的 URL -> firecrawl-map
• 批量提取文档栏目或网站内容 -> firecrawl-crawl
• 从复杂网站进行 AI 驱动的结构化提取 -> firecrawl-agent
• 点击、填写表单、登录、翻页或抓取后的浏览器操作 -> firecrawl-interact
• 将网站下载到本地文件 -> firecrawl-download
• 解析本地文件（PDF、DOCX、XLSX、HTML 等） -> firecrawl-parse
• 检测网站内容变化，并通过 webhook 或电子邮件接收通知（定价、职位、帖子、文档、状态页面，以及任何持续更新的内容） -> firecrawl-monitor
• 安装、身份验证或设置问题 -> rules/install.md
• 输出处理和安全的文件读取模式 -> rules/security.md
• 将 Firecrawl 集成到应用中、将 FIRECRAWL_API_KEY 添加到 .env，或在产品代码中选择端点用法 -> 使用 firecrawl-build 技能（已与此 CLI 技能一同安装）
• 生成由 Firecrawl 支持的交付成果，例如研究简报、SEO 审核、QA 报告、潜在客户名单、知识库或设计系统提取结果 -> 使用 firecrawl-workflows 技能（已与此 CLI 技能一同安装）。这些技能会先根据上下文推断，并且只在遇到阻塞问题时提出简短问题。

输出与组织

除非用户指定在上下文中返回，否则请使用 -o 将结果写入 .firecrawl/。将 .firecrawl/ 添加到 .gitignore。始终给 URL 加上引号——Shell 会将 ? 和 & 解释为特殊字符。

firecrawl search "react hooks" -o .firecrawl/search-react-hooks.json --json
firecrawl scrape "<url>" -o .firecrawl/page.md

命名约定：

.firecrawl/search-{query}.json
.firecrawl/search-{query}-scraped.json
.firecrawl/{site}-{path}.md

切勿一次性读取整个输出文件。请使用 grep、head 或增量读取：

wc -l .firecrawl/file.md && head -50 .firecrawl/file.md
grep -n "keyword" .firecrawl/file.md

单一格式的输出为原始内容。多种格式（例如 --format markdown,links）的输出为 JSON。

处理结果

对于复杂任务，使用基于文件的输出（-o 标志）时，以下模式会很有用：

# Extract URLs from search
jq -r '.data.web[].url' .firecrawl/search.json

# Get titles and URLs
jq -r '.data.web[] | "\(.title): \(.url)"' .firecrawl/search.json

搜索后：发送反馈（返还 1 个额度）

每次搜索调用消耗 2 个额度。使用完搜索结果后，请在后台发送结构化反馈。每个搜索 ID 的首次反馈会返还 1 个额度，并用于改进搜索质量。

SEARCH_ID=$(jq -r '.id' .firecrawl/search-react-hooks.json)

firecrawl search-feedback "$SEARCH_ID" \
  --rating good \
  --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Authoritative"}]' \
  --missing-content '[{"topic":"useDeferredValue example"},{"topic":"Server Components hooks"}]' \
  --query-suggestions "Boost react.dev for react-hooks queries" \
  --silent &

最有用的字段是 --missing-content：一个包含你预期能找到但实际未找到的具体内容的_数组_。每个缺失主题使用一项。即使反馈不理想或不完整，只要 --missing-content 详细，也同样有价值。

选择退出： export FIRECRAWL_NO_SEARCH_FEEDBACK=1 会让 CLI 静默跳过所有反馈调用。请遵守此标志——不要尝试绕过它。完整模式请参阅 firecrawl-search。

并行处理

并行运行相互独立的操作。使用 firecrawl --status 检查并发限制：

firecrawl scrape "<url-1>" -o .firecrawl/1.md &
firecrawl scrape "<url-2>" -o .firecrawl/2.md &
firecrawl scrape "<url-3>" -o .firecrawl/3.md &
wait

对于 interact，抓取多个页面，并使用各自的抓取 ID 分别与每个页面交互。

积分使用

firecrawl credit-usage
firecrawl credit-usage --json --pretty -o .firecrawl/credits.json

---

积分与致谢

本技能基于 Firecrawl 的出色工作。

原始仓库：https://github.com/firecrawl/cli

特别感谢 Firecrawl 慷慨贡献开源成果，助力打造了这套技能集合。 由 webconsulting.at 为这套技能集合改编