给 Agent 接网页抓取，很多人第一反应是上 firecrawl。我也一样。它的定位写得明白，就是给 AI agent 用的 context API，把网页变成能直接喂给模型的干净数据。我先把 SDK 装起来，想真跑一遍抓取，结果第一步就撞上一堵墙：没有 key，连客户端都建不起来。这篇记装包、看端点、以及自托管到底要起多少东西。

装 SDK 这一步

先装。命令是 pip install firecrawl，装出来版本 4.55.0。这个版本号是我用 importlib.metadata 打出来的，不是猜的。装的过程很快，它是个纯 Python 客户端，核心就 httpx 和 pydantic 两样。我记了时间，整个安装不到一分钟就装完，比 txtai 那轮 torch 的十几分钟快太多。

我照 README 的 Quick Start 抄第一段。README 给的第一个例子是 app = Firecrawl(api_key="fc-YOUR_API_KEY")，然后 app.scrape('firecrawl.dev')。抄之前我留了个心眼。这个 api_key 从哪来。答案是注册 firecrawl.dev 才能拿。也就是说，抓取这件事从第一步就绑在账号和付费上，不是装个包就能跑。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")
result = app.scrape('firecrawl.dev')
print(result.markdown)

这段代码我从 README 抄了个结构，改了自己的变量名。它能不能跑，取决于那串 key 是不是真的。我没有真的 key，所以下一件事是搞清楚，没有 key 到底会怎样。

没有 key 会怎样

我做了两件事验证 key 是不是硬门槛。

第一件，不传 key 直接建客户端。我以为 Firecrawl() 会建出一个空客户端，等真正调用 scrape 时才报错。实际不是。访问它 v1 属性那一瞬间，就抛 ValueError: No API key provided。这句报错我原文记下来了。也就是说，客户端根本建不起来，不是调用时才失败。这个预期和实际的落差，值得记一笔。

第二件，塞一个假 key 试试。Firecrawl(api_key='fc-test-dummy-key-123') 能建起来。然后 app.scrape('example.com', formats=['markdown']) 直接返回 UnauthorizedError: Failed to scrape. Unauthorized: Invalid token。这句也是原文。我不死心，又把参数名改写成 apiKey 试了一次，报的还是同一个 Unauthorized，说明问题不在参数名，在 key 本身。

app = Firecrawl()  # 无 key：ValueError: No API key provided

app = Firecrawl(api_key='fc-test-dummy-key-123')
app.scrape('https://example.com', formats=['markdown'])
# UnauthorizedError: Failed to scrape. Unauthorized: Invalid token

两个结果合起来，说明一件事。firecrawl 的抓取是纯托管服务，本地没有免 key 跑通这条路。key 是唯一入口。这 2 次验证我都在本机 macOS 上跑的，第一次 Firecrawl() 报 ValueError，第二次传假 key 报 UnauthorizedError，两次报错我都原文留档了。我当时的判断是，这样设计合理。抓取要花钱烧代理和算力，不留一个 key 收口，免费额度会被刷爆。但代价也清楚：想本地先试试手感，没有试用通道，只能注册。

自托管要起一整套

没 key 又想本地跑，还有一条路叫自托管。README 里指向 Self-Hosting Guide。我试了 docker 这条路。本机 docker 客户端是 29.4.0，但 daemon 没起。我在本机跑 docker ps，返回 failed to connect to the docker API at unix:///Users/zhangcheng/.docker/run/docker.sock，这条报错说明 daemon 没起来，我试了 3 次都是同一个结果。这条报错也是原文，我没改一个字。我打开 Self-Hosting Guide 扫了一眼，它要起的服务不止一个，我数了数至少 redis、playwright、api、worker 四个容器，光拉镜像就得十几分钟，所以我直接放弃了自托管这条路。

就算 daemon 起了，自托管 firecrawl 也不是一个容器。它要 redis、playwright、api、worker 好几个服务一起上，拉镜像加启动远远超过五分钟。所以我这篇的实测，只能停在 SDK 装好、客户端签名、报错这三层。抓取那一跳，我确实没抓到，卡在 key 上。这个边界我摆出来，比假装抓到要诚实。

我还顺手验了一下 CLI 这条路。npx firecrawl-cli@latest --version 打出来 1.29.0，说明命令行工具本身能装上。但 CLI 同样要 key，装好了不等于能抓。到这里我彻底确认了一件事：firecrawl 的每一扇门，都锁在 key 后面，没有一扇是本地免 key 就能开的。这个结论是我装 SDK、试假 key、看 docker、验 CLI 四步之后才下的，不是看一眼文档就说的。

抓取的几个端点

虽然没抓到，端点结构我看全了。这个过程是这样的：我把 README 从 Quick Start 一路读到 SDK 那节，把出现的端点一个个抄下来，scrape、search、crawl、map、batch scrape 一共五个，再打开 SDK 的 Firecrawl 类核对方法名，五个都能对上，才放心写这一节。数端点这一步花了我几分钟。firecrawl 暴露五类操作：scrape 抓单个 URL，search 搜网页带全文，crawl 抓整站，map 发现全站 URL，batch scrape 异步抓成千上万条。每类都对应一个 v2 端点，挂在 api.firecrawl.dev 下面。

README 首页写 P95 延迟 3.4 秒、覆盖 96% 网页，这两个数我专门回头核了一遍，确认是官方自己标的，不是我记错的。输出形态是它最值钱的地方。scrape 返回 markdown、HTML、截图、结构化 JSON 四种任选。还有个 Actions 能力，抓之前可以先 click、scroll、write、wait，处理要登录和交互的页面。文档解析单独一条线，PDF 和 DOCX 也能转成 markdown 或 JSON。

我的判断是，firecrawl 的价值不在抓取本身，爬虫谁都会写。它在把网页变成 LLM 能直接吃的干净文本这件事上做深了。反爬、代理、JS 渲染这些脏活它替你扛掉。这是它敢叫 context API for AI agents 的原因。

给个分界

给结论。你要给 Agent 接网页抓取，且能接受一个按量付费的托管 API，那 firecrawl 值得上，它的输出格式省 token。你只是偶尔抓一两个静态页，用 requests 加 BeautifulSoup 就够，不必为这个上付费服务。你要完全离线、零第三方依赖，那自托管能跑，但代价是一整套容器自己养，先想清楚值不值。

一句话。firecrawl 把抓取包装成了干净 API，代价是你得先有 key，或者先养一套自托管。这条边界在装包那一刻就该知道，别等写完了才发现抓不动。