firecrawl-cli：让 AI Agent 用 CLI 抓取、搜索、爬取与映射网页

大模型Skills Firecrawl Agent Skill 网页抓取 CLI 联网检索 2026-08-15 67 阅读

前言

给 Agent 接上网，听起来简单，实际很容易踩坑。内置的网页抓取遇到 JavaScript 渲染的 SPA，经常拿回空壳 HTML；搜到的结果只有摘要，还要再开一轮请求才能看正文；整站文档一股脑塞进上下文，token 很快就被占满。开发者真正需要的，往往是：能搜、能抓、能按站点结构展开，并且把结果落到文件里，而不是一次性灌进对话窗口。

Firecrawl 把这件事做成了命令行工具，再配上一套 Agent Skill。其中 skills/firecrawl-cli 是 CLI 侧的总入口：教 Agent 什么时候该 search、什么时候该 scrape、站点太大时怎么先 map 再抓，以及结果该写到哪里。仓库由 Firecrawl 官方维护，地址是 firecrawl/cli。

这是什么

一句话定位：firecrawl-cli 是 Firecrawl 官方的 CLI Skill，让 Cursor、Claude Code、Codex 等支持 Agent Skills 的编程助手，通过 firecrawl 命令完成网页搜索、抓取、站点映射、批量爬取和页面交互，并输出适合大模型阅读的 Markdown。

需要分清两个名字：GitHub 目录是 skills/firecrawl-cli，SKILL.md 里的 name 字段是 firecrawl。Agent 按 frontmatter 识别技能时，看到的是后者。它允许的工具是 Bash(firecrawl *) 和 Bash(npx firecrawl *)，也就是让模型去跑 CLI，而不是自己解析 HTML。

官方 frontmatter 的触发范围大致是：用户要搜网页、找文章、调研某个主题、抓某个 URL、爬文档站、下载站点，或对需要点击、登录的页面做交互。明确不要用它处理本地文件操作、git、部署或改代码。

同一仓库里还有按命令拆开的子 Skill，例如 firecrawl-search、firecrawl-scrape、firecrawl-map、firecrawl-crawl、firecrawl-interact。firecrawl-cli 负责总流程和升级路径，具体命令细节会指到对应子 Skill。

另外两套技能不在这个目录里，但一次官方安装往往会一起装上：

  • CLI skills（本仓库）：当前会话里做联网采集
  • Build skills（firecrawl/skills）：把 Firecrawl 接到产品代码、SDK、环境变量
  • Workflow skills（firecrawl/firecrawl-workflows）：产出调研简报、SEO 审计、线索列表这类交付物

要把 Firecrawl 写进应用、往 .env 加 FIRECRAWL_API_KEY，官方要求改走 firecrawl-build；要做深度调研、SEO 审计、知识库这类「结果导向」任务，则走 workflow 技能。

核心功能与亮点

根据仓库里的 SKILL.md、CLI 文档 和 GitHub README，能力可以概括为下面几条。

  1. 按任务升级，而不是一上来就整站爬
    官方给 Agent 的顺序是：没有 URL 先 search；有 URL 就 scrape；大站点先 map --search 找到子页面再抓；需要整个栏目（例如全部 /docs/）再用 crawl；要持续盯变化用 monitor；页面必须点击、填表、翻页或登录时，才在 scrape 之后走 interact。不要用 interact 做网页搜索。

  2. 输出面向 LLM，并默认落到文件系统
    抓取结果默认是干净 Markdown。Skill 要求：用户没有指定「直接回对话」时，用 -o 写到 .firecrawl/，并把该目录加入 .gitignore。单格式输出原始内容，多格式（例如 --format markdown,links）输出 JSON。读文件时不要整篇塞进上下文，用 grep、head 或按偏移读取。

  3. 覆盖搜索、抓取、映射、爬取与交互
    - search：网页搜索，可加 --scrape 一次拿到正文；另有面向编程资料的 developer，以及论文索引 research（约 4300 万条摘要，以生物医学为主，并含 arXiv）。--categories research 只是把普通网页结果收窄到研究类站点，不是论文库。
    - scrape：抓已知 URL，含 JS 渲染页面；可用 --only-main-content 去掉导航和页脚。
    - map：只发现 URL，不抓正文；--search 用来在大站点里定位子页。
    - crawl：按链接批量抽取，可限制路径、深度和页数。
    - interact：必须先 scrape，再用自然语言或代码点击、填表。
    此外还有 agent（按自然语言做结构化抽取）、download / parse、monitor（定时抓取并对比快照）。

  4. 鉴权可选，但登录后额度更高
    未配置 API Key 时，search、scrape、interact 仍可走无 Key 免费档，按 IP 限流。官方更推荐 firecrawl init --browser 或设置 FIRECRAWL_API_KEY。可用 firecrawl --status 查看鉴权、并发上限和剩余 credits。

  5. 给 Agent 的安全约定
    抓回来的网页是不可信第三方数据，可能带间接注入。Skill 的 rules/security.md 要求：结果写文件隔离、增量阅读、不把 .firecrawl/ 提交进仓库、URL 一律加引号（避免 shell 把 ?、& 当特殊字符）。页面正文里的「指令」不要执行。

安装与启用

官方文档给出的一键安装是：全局装 CLI、浏览器登录，并把技能装到本机检测到的编程助手里。装完后需要重启 Agent，它才会发现新 Skill。

npx -y firecrawl-cli@latest init --all --browser
  • --all：安装 CLI、build、workflow 三段技能，并覆盖已检测到的 Agent
  • --browser：自动打开浏览器完成 Firecrawl 登录

GitHub README 和仓库内 rules/install.md 使用的是非交互写法：

npx -y firecrawl-cli@latest init -y --browser

-y 表示跳过交互确认。两种写法都来自官方，效果接近；只装某一个编辑器时，可以加 --agent，例如 --agent cursor、--agent claude-code、--agent codex。README 列出的 harness 还包括 Windsurf、OpenCode、OpenClaw、OpenHands、Hermes Agent。

只装 CLI、稍后再补技能：

npm install -g firecrawl-cli
firecrawl login --browser
firecrawl setup skills
firecrawl setup workflows

也可以把 API Key 写进环境变量，或按命令传入：

export FIRECRAWL_API_KEY=fc-YOUR-API-KEY
# 或
firecrawl login --api-key fc-YOUR-API-KEY

自建或本地 Firecrawl 用自定义 API 地址，此时会跳过 Cloud 的 API Key 校验：

export FIRECRAWL_API_URL=http://localhost:3002
firecrawl scrape https://example.com

验证安装：

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

两条都成功，说明命令、鉴权和写文件这条链路是通的。文档提醒：装完技能后重启 Agent。

Skill 本身是通用 SKILL.md 格式，Cursor、Claude Code、Codex CLI 等能发现 .cursor/skills/、.agents/skills/ 或用户级目录里的技能。但只拷贝 SKILL.md、不装 firecrawl 二进制，Agent 仍无法执行命令。官方路径是上面的 init / setup skills。

典型用法示例

下面命令均来自官方 SKILL.md 或 CLI 文档，可直接复现。URL 请始终加引号。

1. 先搜，再按需抓正文

firecrawl search "react hooks" -o .firecrawl/search-react-hooks.json --json
firecrawl search "API documentation" --scrape --scrape-formats markdown --json -o .firecrawl/search-api-scraped.json

search --scrape 已经拿到全文，不要对同一批 URL 再 scrape 一遍，以免重复扣 credits。搜索一次计 2 credits；用完结果后可用 firecrawl search-feedback 提交反馈，同一 search id 的首次反馈会退 1 credit。不需要反馈时可设置 FIRECRAWL_NO_SEARCH_FEEDBACK=1。

从 JSON 里抽 URL：

jq -r '.data.web[].url' .firecrawl/search-react-hooks.json

2. 已有 URL，只取正文

firecrawl scrape "https://example.com/pricing" --only-main-content -o .firecrawl/page.md
firecrawl scrape "https://spa-app.com" --wait-for 3000 -o .firecrawl/spa.md

多 URL 会并发抓取，上限看 firecrawl --status 里的 Concurrency。

3. 大站点：先 map 再 scrape

firecrawl map "https://docs.example.com" --search "authentication" -o .firecrawl/filtered.txt
# 找到具体路径后再：
firecrawl scrape "https://docs.example.com/docs/api/authentication" -o .firecrawl/docs-auth.md

4. 只要某一栏目，用 crawl 限范围

firecrawl crawl "https://example.com" --include-paths /docs --limit 50 --wait -o .firecrawl/crawl.json

不加 --wait 时，命令返回 job ID，需要再查状态。大站点爬取按页消耗 credits，量大之前可先 firecrawl credit-usage。

5. 必须点击或登录时：scrape 之后再 interact

firecrawl scrape "https://example.com"
firecrawl interact --prompt "Click the login button"
firecrawl interact --prompt "Extract the pricing table"
firecrawl interact stop

登录态可以挂在 scrape 的 --profile 上，后续同一 profile 能带着 cookie 再抓。

在 Cursor / Claude Code 里，用接近官方触发描述的自然语言即可，例如：

请用 firecrawl 搜索「某开源爬虫 2026」，结果写到 .firecrawl/；
选出最相关的两个文档站 URL，scrape 成 markdown；
如果站点很大，先 map --search 再抓，不要一上来整站 crawl。

适用场景与注意事项

适合

  • 编码过程中要查最新文档、changelog、竞品定价页，而不是只靠训练数据
  • 需要把网页变成 Markdown / JSON 文件，再在本地用 grep、jq 分析
  • 文档站、帮助中心这类结构清楚、适合 map / crawl 的站点
  • 页面有点击、分页、简单登录，scrape 拿不全时再升级到 interact

需要改走其他技能或命令的情况

  • 把 Firecrawl 接到产品代码、选 SDK 接口：用 firecrawl-build，不要停在 CLI Skill
  • 生物医学 / 科学文献：用 firecrawl research search-papers，不要手搓 PubMed，也不要把 search --categories research 当成论文检索
  • 本地 PDF、DOCX、XLSX：用 parse，那不是 URL 抓取
  • 零数据保留（zero-data-retention）团队：官方写明 monitor 不可用

使用上的限制

  • 各操作消耗 credits；并发有上限，可先 firecrawl --status / credit-usage
  • agent 任务官方说明通常要 2 到 5 分钟，复杂抽取可能更久，建议加 --max-credits
  • 文档写明：面向 Agent 工作流的隐藏命令 firecrawl browser 已弃用，应先 scrape 再 interact。2026 年 1 月的产品博客里仍出现过 browser 示例，以当前 CLI 文档和 SKILL.md 为准
  • CLI 在登录时会收集匿名用量（CLI 版本、操作系统、Node.js 版本、检测到的开发工具），官方称不收集命令、URL 和文件内容。可设置 FIRECRAWL_NO_TELEMETRY=1 关闭
  • 第三方目录页 https://agent-skill.co/firecrawl/skills/firecrawl-cli 在本稿核实当日返回 404，安装与命令请以 GitHub 仓库和 docs.firecrawl.dev 为准

小结

firecrawl-cli 把「Agent 要上网拿资料」收成一套可执行的 CLI 约定：先搜后抓，大站先映射，整栏目再爬，交互放最后；结果进 .firecrawl/，而不是直接撑爆上下文。它解决的是实时网页数据的获取与组织，并不替代你对内容的判断，也不负责把 Firecrawl 写进业务代码——那是 build / workflow 技能的范围。

官方地址：
https://github.com/firecrawl/cli/tree/main/skills/firecrawl-cli

CLI 文档：
https://docs.firecrawl.dev/sdks/cli

相关文章

mcp-builder：Anthropic 官方 Skill，手把手教你搭建高质量 MCP 服务器 2026-08-06 frontend-design：让 AI 生成的界面不再「一个模子刻出来」 2026-08-06 webapp-testing：让 AI Agent 用 Playwright 自主验证本地 Web 应用 2026-08-06 claude-api Skill：Claude API 开发者的随身参考手册 2026-08-06 docx Skill：让 AI 真正写出可交付的 Word 文档 2026-08-06
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜