AutoGPT 平台 Firecrawl Crawl 块详解：以 Firecrawl 驱动整站爬取与内容提取

导读

Firecrawl Crawl 是 AutoGPT 平台中归属于 Firecrawl 集成家族的一个「搜索与抓取」类块（Block），用于从单个起始 URL 出发自动爬取网站的多个页面，并在同一轮爬取中同时产出 markdown、HTML、链接、截图等多种格式的结构化结果。本文围绕该块的官方文档（crawl.md）展开，结合仓库中该块的真实源码实现，讲解它的工作原理、全部输入输出参数、成本计费口径与典型落地场景，帮助你在 AutoGPT 平台的 Agent 图中直接编排出“文档索引、竞品调研、内容归档”等整站级数据处理流程。

---

一、块定位：什么是 Firecrawl Crawl

在 AutoGPT 平台的块库中，Firecrawl 集成被组织在 autogpt_platform/backend/backend/blocks/firecrawl/ 目录下，与 Crawl 同族的还有：

• scrape.py（单页抓取）
• map.py（站点地图发现）
• search.py（搜索）
• extract.py（结构化抽取）

与只抓取单个 URL 的 Scrape 块不同，Crawl 块的语义是整站遍历：从一个起始 URL 出发，像搜索引擎爬虫一样沿着站内链接递归前进，逐页抓取并返回内容。官方文档对它的定位概括为一句话：

“Firecrawl crawls websites to extract comprehensive data while bypassing blockers.”

即它不仅做「抓取」，还负责解决网页抓取中的两大痛点——JavaScript 动态渲染与反爬（anti-bot）绕过，从而把每个页面都清洗成可被下游 LLM、知识库直接消费的干净文本。

在仓库中该块对应的类为 FirecrawlCrawlBlock（crawl.py），其声明信息如下：

• 块 ID：bdbbaba0-03b7-4971-970e-699e2de6015e
• 分类：BlockCategory.SEARCH（在块库中被归入“搜索”类目）
• 描述：Firecrawl crawls websites to extract comprehensive data while bypassing blockers.

---

二、工作原理：从配置到 Firecrawl API 的完整调用链

官方文档 crawl.md 对该块的工作机制描述如下：

该块使用 Firecrawl 的 API 从给定 URL 开始爬取网站的多个页面。它会沿链接遍历，处理 JavaScript 渲染并绕过反爬措施，从每个页面提取干净内容。你可以用 limit 参数配置爬取深度，选择输出格式（markdown、HTML 或 raw HTML），并可选地只保留主内容。该块支持带最大缓存年龄（max age）与动态内容等待时间（wait for）的缓存能力。

对照源码，这一机制可以细分为以下几个环节：

1. 实例化 Firecrawl 官方客户端

run() 方法在每次执行时用块输入的凭据构造官方 SDK 客户端：

app = FirecrawlApp(api_key=credentials.api_key.get_secret_value())

其中 credentials 来自块输入中的 credentials 元字段。Firecrawl 提供方的定义位于 _config.py，读取环境变量 FIRECRAWL_API_KEY 作为 API Key，并在平台上为块配了按用量计费的基础成本：

firecrawl = (
    ProviderBuilder("firecrawl")
    .with_description("Web scraping and crawling")
    .with_api_key("FIRECRAWL_API_KEY", "Firecrawl API Key")
    .with_base_cost(1000, BlockCostType.COST_USD)
    .build()
)

2. 同步调用 app.crawl()

crawl_result = app.crawl(
    input_data.url,
    limit=input_data.limit,
    scrape_options=ScrapeOptions(
        formats=convert_to_format_options(input_data.formats),
        only_main_content=input_data.only_main_content,
        max_age=input_data.max_age,
        wait_for=input_data.wait_for,
    ),
)

可以看到，Crawl 是一次同步、阻塞式的整站爬取：limit 直接控制 Firecrawl 服务端本次任务要抓取的页面总数上限；ScrapeOptions 承载的 formats、only_main_content、max_age、wait_for 会被下发到服务端，作用于本次爬取涉及到的每一个页面。

3. 格式枚举与特殊转换

块的 formats 输入在类型层面使用了仓库自定义的 ScrapeFormat 枚举（_api.py）：

MARKDOWN = "markdown"
HTML = "html"
RAW_HTML = "rawHtml"
LINKS = "links"
SCREENSHOT = "screenshot"
SCREENSHOT_FULL_PAGE = "screenshot@fullPage"
JSON = "json"
CHANGE_TRACKING = "changeTracking"

由于 Firecrawl SDK 的 FormatOption 类型中，全页截图需要被表达为带 full_page=True 的 ScreenshotFormat 对象而不是普通字符串，_format_utils.py 提供了专门的转换函数 convert_to_format_options()：

if format_enum.value == "screenshot@fullPage":
    result.append(ScreenshotFormat(type="screenshot", full_page=True))
else:
    result.append(format_enum.value)

这是 Crawl 块内部实现的一个关键细节：全页截图（screenshot@fullPage）被拆解为「截图类型 + 全页标记」两个维度，而非一个独立的格式字符串。

4. 结果展开与逐页产出

爬取完成后，块先整体产出 data（完整的爬取结果列表），随后对每一页分别产出其选中格式对应的输出。若同一页被请求了多种格式，各格式输出会依次触发。这也意味着下游节点收到的是“逐页、按格式切分”的数据流，便于后续逐条进入 RAG 管道或数据库。

---

三、输入参数详解

以下输入来自 crawl.md 的输入表，并补充了源码（crawl.py）中的类型默认值与描述：

输入	描述	类型	必填	代码默认值
credentials	Firecrawl 凭据元字段（对应 FIRECRAWL_API_KEY 环境变量）	CredentialsMetaInput	是（平台层）	—
url	起始爬取 URL	str	是	无
limit	要爬取的页面数量上限	int	否	10
only_main_content	是否只返回页面主内容（排除 header、导航、footer 等）	bool	否	True
max_age	页面最大缓存年龄（毫秒），默认 1 小时	int	否	3600000
wait_for	抓取内容前的延迟（毫秒），让页面有足够时间完成动态加载	int	否	0
formats	爬取输出的格式列表	List["markdown" | "html" | "rawHtml" | "links" | "screenshot" | "screenshot@fullPage" | "json" | "changeTracking"]	否	["markdown"]

对几个关键参数的实战理解：

• url + limit 决定“爬多大”：Crawl 是广度式的整站遍历，limit 越大，遍历到的页面越多，耗时的 Firecrawl 服务端额度也越多（详见下文成本说明）。文档中称其为“配置爬取深度（crawl depth）”的手段——虽然它的语义是页面数上限而非图论意义上的层数深度，但在限制范围的意义上等同于约束了爬取规模。官方文档原文示例中默认 limit=10，但文档输入表将其标为可选，说明在图中可以只连 url 使用。
• only_main_content 决定“多干净”：默认开启，自动剔除导航栏、页头页脚等模板噪音，只保留正文。对于把网页内容直接投喂给 LLM 或做向量化的场景，强烈建议保持开启以减少 token 浪费。
• max_age 是“缓存开关”：默认 1 小时（3600000 ms）。它告诉 Firecrawl 服务端，如果该页内容在指定窗口内已被抓取过，则直接复用缓存结果，从而显著降低重复爬取成本、提升整站任务速度。
• wait_for 用于动态页面：如果目标站点是重度前端渲染（SPA），把 wait_for 设为一个延迟窗口（如 2000~5000ms），等待异步请求与首屏渲染完成后再抓取，能明显提高内容完整度。
• formats 决定“拿什么”：可以多选。需要强调的是多选会放大返回体量与成本（每个选中格式都会触发一次内容处理），默认值仅 ["markdown"]，即开箱即得纯文本版本，最省配额。

---

四、输出字段详解

块的输出在文档中定义为以下九个字段，全部来自 crawl.py 的 Output 定义（其中 error 默认值为空字符串）：

输出	描述	类型
error	爬取失败时的错误消息	str
data	整次爬取的结果列表（每个页面的完整结构）	List[Dict[str, Any]]
markdown	爬取内容的 Markdown 文本	str
html	爬取内容的 HTML	str
raw_html	爬取内容的原始 HTML（未清洗）	str
links	爬取到的链接列表	List[str]
screenshot	爬取的页面截图	str
screenshot_full_page	爬取的整页截图	str
json_data	爬取的 JSON 数据	Dict[str, Any]
change_tracking	页面变更追踪数据	Dict[str, Any]

输出与输入格式的对应关系，可以在源码的产出循环中精确看到（crawl.py）：当 formats 中包含某格式时，该格式数据会以对应命名的输出逐页产出，即：

• markdown 格式 → markdown 输出
• html 格式 → html 输出
• rawHtml 格式 → raw_html 输出
• links 格式 → links 输出
• screenshot 格式 → screenshot 输出
• screenshot@fullPage 格式 → screenshot_full_page 输出
• json 格式 → json_data 输出
• changeTracking 格式 → change_tracking 输出

data 输出承载的是 Firecrawl 返回的结构化原始结果列表，即使没有开启任何离散格式，也会整体产出，便于下游做统一的后处理。

---

五、成本与计费口径

爬取类块的 API 用量成本是实际落地前必须评估的维度。从源码注释与 _config.py 可以看出平台的计费口径：

1. Firecrawl 按自身信用点（credit）计费，1 credit ≈ $0.001，按“每个被爬取的页面”记 1 credit。
2. 块在每次运行后会根据实际返回的页面数估算花费并写入执行统计：

pages = len(crawl_result.data) if crawl_result.data else 0
self.merge_stats(
    NodeExecutionStats(
        provider_cost=pages * 0.001, provider_cost_type="cost_usd"
    )
)

即“真实返回了多少页，就按每页 $0.001 估算 provider 成本”。

3. 平台侧提供方配置为 with_base_cost(1000, BlockCostType.COST_USD)，含义是 1000 平台积分 ≈ $1 USD 的基准换算——由于 1 Firecrawl credit ≈ $0.001，折算后约等于每个被爬取页面消耗 1 个平台信用点，与单页抓取档位大致对齐。

据此可以推导出实操层面的成本控制技巧：

• limit 是成本的第一杠杆：把站点规模 × 内容更新频率，再结合预算反推 limit。
• 善用 max_age 缓存：同一站点在缓存窗口内重复运行同一 Agent 时，命中缓存的页面不再计入真实爬取，可明显降低实际消耗。
• 精简 formats：只保留真正需要的输出格式，减少服务端处理量。

---

六、典型使用场景

官方文档给出了三个高度契合整站爬取能力的场景，这里结合 AutoGPT 平台 Agent 图的编排方式做进一步展开：

1. 文档索引（Documentation Indexing）

场景描述：把整站技术文档爬下来，构建可搜索的知识库或训练数据。

在平台中的编排建议：用 Crawl 块以文档站点首页为 url 开启爬取，only_main_content=true 保证正文纯净，formats=["markdown"] 得到可直接切割的文本；随后将 markdown 输出接到文本切片、向量化等下游块，写入向量数据库形成可检索知识库。由于 AutoGPT 平台块之间以数据流连接，data 输出还可并行接到入库管道做审计留痕。

2. 竞品研究（Competitor Research）

场景描述：批量提取竞品网站内容，用于市场分析与横向对比。

在平台中的编排建议：将竞品官网/博客/定价页等作为 url 起点，可配合同族 Firecrawl Search 或 Firecrawl Map 块先发现候选 URL，再用 Crawl 做规模化采集。开启 formats=["html"] 或 rawHtml 可保留页面结构便于分析布局；叠加 LLM 摘要块即可批量生成竞品分析报告。

3. 内容归档（Content Archival）

场景描述：系统化归档网站内容，用于备份或合规留证。

在平台中的编排建议：利用 limit 全量限定范围 + max_age 做增量窗口控制，多轮调度即可实现“首次全量 + 后续增量”的归档节奏。同时开启 markdown、html、screenshot@fullPage、changeTracking 多格式输出，保留页面在不同时间点的完整快照（含截图证据与变更追踪数据），输出到对象存储或数据库完成留档。

补充：官方文档对这三个场景均以粗体用例形式列出，本块实际能力以文档描述与源码为准；上文中的编排建议是基于 AutoGPT 平台数据流连接方式的常规用法，具体图结构可按需调整。

---

七、在 AutoGPT 平台中配置与使用

前置条件：配置 Firecrawl 凭据

1. 在 Firecrawl 官网注册并获取 API Key；
2. 在 AutoGPT 平台环境中设置环境变量 FIRECRAWL_API_KEY（对应代码 _config.py 中的凭据定义）；
3. 新建/编辑 Agent 图时，把 Firecrawl Crawl 块拖入画布，在弹出的输入面板中选择/关联该凭据。

在编排时，输入面板中会看到本文第三节的全部输入字段；其中 formats 为多选列表（对应 List 类型），url 为必填文本框，其余字段均带默认值可直接运行。

快速验证

若只想验证块行为，可以只连接一个最小图：url 填入一个中小型站点 → Crawl 块 → 把 markdown 输出接到日志/文本块观察结果。由于默认 limit=10、formats=["markdown"]，一次运行成本与返回体量都处于可控范围。

关联阅读

同一 Firecrawl 集成下，按任务粒度由小到大依次为：

• Firecrawl Scrape：单页抓取，适合精准取一页；
• Firecrawl Map：站点链接发现；
• Firecrawl Extract：从页面/整站抽取结构化字段；
• Firecrawl Search：按关键词搜索网页。

你可以在图里把 Map/Search 的结果作为 Crawl 的多个起点，或用 Extract 消化 Crawl 返回的 data，组合出完整的“发现 → 整站采集 → 结构化”流水线。

---

结语

Firecrawl Crawl 块把“多页整站爬取、反爬绕过、JS 渲染、缓存控制、多格式输出、成本计量”收敛为一个可在图上拖拽的节点。理解它的输入默认值（limit=10、only_main_content=True、max_age=1h、formats=["markdown"]）、screenshot@fullPage 的特殊格式转换逻辑以及“每页 1 Firecrawl credit ≈ $0.001”的计费口径，是把它用得既高效又省成本的关键。相关实现与配置可直接查阅 crawl.py、_api.py 与 _config.py。