CrewAI FirecrawlScrapeWebsiteTool 完全指南：让 Agent 把任意网站抓成干净 Markdown

本文基于 CrewAI 仓库中 lib/crewai-tools 包内的 FirecrawlScrapeWebsiteTool 官方文档及其实现源码，系统讲解这个工具的用途、安装方式、全部配置参数及其默认值、URL 安全校验机制与底层调用链。读完后你可以将该工具直接挂到 CrewAI Agent 上，把目标网页抓取为干净的 Markdown 或结构化数据，并理解每个 config 参数在源码层面的实际去向。

什么是 FirecrawlScrapeWebsiteTool

根据工具模块自带文档 README，Firecrawl 是一个将任意网站抓取并转换为干净 Markdown 或结构化数据的平台。FirecrawlScrapeWebsiteTool 是 CrewAI 官方工具包（crewai-tools）对 Firecrawl v2 Scrape API 的封装，其定位是：

• 让 Agent 具备“读网页”能力：Agent 只需给出一个 url，工具即可返回网页清洗后的内容；
• 以 Markdown 为主输出格式：默认返回 Markdown，天然适配 LLM 上下文；
• 依赖 Firecrawl 云服务：抓取、渲染、去噪在 Firecrawl 服务端完成，本地不需要维护浏览器。

从源码结构看，该工具继承自 crewai.tools.BaseTool，并通过 Pydantic 模型 FirecrawlScrapeWebsiteToolSchema 声明唯一运行参数 url（必填，描述为 "Website URL"）。工具的 name 为 Firecrawl web scrape tool，description 为 Scrape webpages using Firecrawl and return the contents，这两项会直接展示给 LLM 用于决策何时调用该工具。

安装与环境配置

根据官方文档，使用前提只有两步：

1. 从 Firecrawl 平台获取 API key，并设置为环境变量 FIRECRAWL_API_KEY；
2. 安装 Firecrawl SDK 与带 tools 扩展的 CrewAI 包：

pip install firecrawl-py 'crewai[tools]'

仓库中的两个事实佐证了这套依赖约定：

• firecrawl_scrape_website_tool.py 中，工具声明了 package_dependencies = ["firecrawl-py"] 和一个 required=True 的环境变量 FIRECRAWL_API_KEY；
• tool.specs.json 的元数据同样把 firecrawl-py 列为该工具的必需依赖包，并把 FIRECRAWL_API_KEY 记录为其环境变量要求。

另外，pyproject.toml 中定义了可选依赖组 firecrawl-py = ["firecrawl-py>=1.8.0"]，即最低要求 firecrawl-py >= 1.8.0。如果环境中缺少该包，工具的构造函数会通过 click.confirm 交互式询问是否执行 uv add firecrawl-py 自动安装，拒绝则抛出 ImportError 提示手动安装（见 init 实现）。这意味着在脚本、CI 等非交互场景下建议提前装好依赖，避免运行时弹确认框。

快速上手示例

官方文档给出的最小用法如下：

from crewai_tools import FirecrawlScrapeWebsiteTool

tool = FirecrawlScrapeWebsiteTool(config={"formats": ["html"]})
tool.run(url="firecrawl.dev")

要点：

• 工具通过 from crewai_tools import ... 直接从包顶层导出（可在 crewai_tools/init.py 中确认导出存在）；
• 构造参数只传了 config，说明 api_key 可省略——省略时 SDK 会读取 FIRECRAWL_API_KEY 环境变量，这与源码中 FirecrawlApp(api_key=api_key) 在 api_key=None 时走环境变量回退的行为一致；
• tool.run(url="firecrawl.dev") 中，url 是唯一必填参数，可传完整 URL 或裸域名（Firecrawl 服务端会补全）。

仓库中的集成测试 firecrawl_scrape_website_tool_test.py 演示了另一种验证方式：使用 VCR 录制的 HTTP 交互回放，断言返回对象带非空的 markdown 属性且内容包含 "Firecrawl" 字样——这印证了默认 formats=["markdown"] 下返回结果是携带 markdown 字段的响应对象，而不是纯字符串。

参数详解：api_key 与 config

api_key（可选）

指定 Firecrawl API key。缺省时默认读取 FIRECRAWL_API_KEY 环境变量，该环境变量被标记为必需项，因此要么显式传 api_key，要么确保环境变量已设置，两者皆无时 Firecrawl SDK 初始化会失败。

config（可选）：Firecrawl v2 API 参数

config 是一个字典，最终会作为关键字参数原样透传给 FirecrawlApp.scrape()。文档 README 中给出的“默认配置”较为精简，而源码 config 字段的 default_factory 定义了当前仓库实际的完整默认值，两者对照如下表（以源码为准）：

参数	类型	源码默认值	说明
formats	list[str]	["markdown"]	返回的内容格式列表，可包含 html、markdown 等
only_main_content	bool	True	仅返回正文，剔除 header/nav/footer 等
include_tags	list[str]	[]	仅保留列出的标签
exclude_tags	list[str]	[]	排除列出的标签
max_age	int	172800000	缓存时效（毫秒），约 2 天，命中则返回缓存
headers	dict	{}	随请求发送的额外请求头（cookie、UA 等）
wait_for	int	0	抓取前等待的毫秒数，用于等待前端渲染
mobile	bool	False	模拟移动端抓取
skip_tls_verification	bool	True	跳过 TLS 证书校验
remove_base64_images	bool	True	从输出中移除 base64 图片，控制上下文体积
block_ads	bool	True	启用广告与 cookie 弹窗拦截
proxy	str	"auto"	代理类型，可选 basic / stealth / auto
store_in_cache	bool	True	是否将页面存入 Firecrawl 索引与缓存

注意：README 中的默认配置示例未列出 max_age、mobile、skip_tls_verification、remove_base64_images、block_ads、proxy、store_in_cache 这七项，源码 docstring（L23-L45）与 default_factory 一致，是更完整的参数参考。

由于 config 是整体透传，传入部分键会完整替换整个默认字典（而非与默认值合并）。例如 config={"formats": ["html"]} 后，only_main_content 等其余键不再是默认值，而是完全交给 Firecrawl API 服务端行为——构造工具前需评估是否需要显式补齐关键项。

底层调用链与 URL 安全校验

_run() 的实现只有三行核心逻辑（源码 L107-L112）：

def _run(self, url: str) -> Any:
    if not self._firecrawl:
        raise RuntimeError("FirecrawlApp not properly initialized")

    url = validate_url(url)
    return self._firecrawl.scrape(url=url, **self.config)

调用链为：BaseTool.run(url=...) → Pydantic args_schema 校验 → _run() → validate_url() → FirecrawlApp.scrape()。这里有一个容易被忽略但很重要的细节：URL 在发出请求前会经过 validate_url 安全校验（来自 safe_path.py），其规则是：

1. 完全禁止 file:// 协议，仅允许 http / https；
2. 对 hostname 做 DNS 解析，若解析结果为私网或保留地址（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、169.254.0.0/16 链路本地/云元数据、IPv6 的 ::1、fc00::/7 等），则直接拒绝，以防止 Agent 被诱导抓取内网服务（SSRF）；
3. 无法解析的 IP 一律按阻断处理。

该模块文档还说明：设置 CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true 可跳过校验（官方不推荐生产使用），托管环境则可用 CREWAI_TOOLS_FORCE_SAFE_PATHS=true 强制开启、防止租户自行绕过。因此把该工具暴露给 LLM 可控输入时，这一层默认防护是安全兜底之一。

返回结果与验证

• 默认 formats=["markdown"] 时，返回对象包含 markdown 字段；指定 ["html"] 时则输出 html 字段。集成测试断言 result.markdown 非空且含目标站点关键词，可作为你自行验证的参照。
• remove_base64_images 默认为 True，对以 LLM 消费为主的场景是合理默认，能显著压缩 token 体积；若下游需要内联图片则应显式关闭。
• max_age 默认为 2 天的缓存时效，配合 store_in_cache=True，重复抓取同一页面会命中 Firecrawl 缓存，注意其对内容新鲜度的影响。

小结

FirecrawlScrapeWebsiteTool 是 CrewAI 官方工具集中把 Firecrawl v2 Scrape API 接入 Agent 的标准封装：构造时声明 api_key / config，运行时只接受一个 url，底层经 validate_url 做 SSRF 防护后透传给 FirecrawlApp.scrape()。掌握其完整默认配置（13 项参数）、config 整体替换而非合并的语义，以及 URL 校验规则后，即可按站点特性（是否需要 wait_for 等待渲染、是否要 stealth 代理、是否保留 HTML）精确调优抓取行为。更多官方说明可参考 docs/edge/en/tools/web-scraping/firecrawlscrapewebsitetool.mdx，同族的 FirecrawlCrawlWebsiteTool（整站爬取）与 FirecrawlSearchTool（网页搜索）可在 tool.specs.json 的元数据中查到对应定义。