Firecrawl Local 实战:一个二进制把网页变成 Agent 能读的干净文本
一句话结论:它不是「又一个抓取程序」,而是把「网页 → 上下文」这段脏活收进一个本地进程。对编排式 Agent 来说,规划位拿到的是干净 Markdown 而不是一页 HTML,判断质量会明显不一样。
一、它解决的是哪一段
Agent 读外部资料通常卡在三个地方:
| 环节 | 原始做法的问题 | 本地抓取服务做什么 |
|---|---|---|
| 取回 | 直接请求拿到整页 HTML | 按 URL 抓取并做主体提取 |
| 清洗 | 自己写正则删标签,容易漏 | 转成结构化 Markdown |
| 交付 | 手动复制进对话 | 以 MCP 工具形式被 Agent 直接调用 |
关键变化在第三点:清洗后的文本不是给人看的,是给模型当上下文用的。这就和编排流程接上了——规划位需要仓库结构、接口文档、依赖说明这类外部资料时,直接调工具拿干净片段,不必把整页内容塞进提示里。搭配 双模型编排配置指南里的按需检索原则,能把上下文长度压下来一大截。
二、安装:前提比命令重要
它是一个 Rust 写的单二进制,用 cargo 安装:
cargo install firecrawl-local
安装前需要确认两件事,缺一个都会在编译阶段报一堆看不懂的错:
- Rust 工具链(cargo 可用)
- C 编译器(部分依赖需要在本机编译)
装完先本地起服务,确认端口能通再配客户端:
firecrawl-local --help
这个项目采用 AGPL-3.0 许可。自用和内部工具没问题,但如果要把它作为服务嵌进对外产品,先确认许可义务,别等上线前才看。
三、四套客户端配置
本地服务通过 stdio 或本机 HTTP 与 Agent 通信,具体形态以当前版本的 README 为准。下面给的是配置结构,端口和命令名按你的实际安装结果替换。
Claude Desktop / Cursor(JSON 配置)
{
"mcpServers": {
"firecrawl-local": {
"command": "firecrawl-local",
"args": ["--mcp"]
}
}
}
Claude Code(命令行添加)
claude mcp add firecrawl-local -- firecrawl-local --mcp
如果配置里带凭据,优先用 stdin 注入而不是把明文写进命令行——近期的客户端版本已经支持从标准输入读 MCP 配置,这样密钥不会留在 shell history 里:
<密钥来源> | claude mcp add-json firecrawl-local -
VS Code + Copilot / OpenCode:在各自的 MCP 配置文件里加同样的 server 条目即可,字段命名可能略有差异,按客户端文档对齐。
配完在客户端里让 Agent 列一次工具,能看到抓取类工具就算通了。
四、和托管版、通用抓取库怎么选
| 方案 | 适合 | 不适合 |
|---|---|---|
| 本地二进制 | 内网资料、要控制数据不出机、想省调用费 | 大规模并发、需要代理池与反爬对抗 |
| 托管服务 | 免运维、需要分布式抓取 | 敏感页面、要求数据留在内网 |
| 自写 requests + 解析库 | 只抓一两个固定页面 | 页面结构杂、要长期维护 |
一条实际经验:本地版近期移除了托管的远程执行端点,这是把攻击面收小的正确方向。任何「让 Agent 在服务端执行任意命令」的能力,都不该出现在抓取工具里。
五、抓取策略:别把上下文当垃圾桶
三个能直接降低 token 消耗的做法:
- 先列目录再取正文。让 Agent 先拿到链接清单,按标题挑要看的那几页,而不是一次抓整站。
- 限定主体区域。只取正文容器,页头与页面底部导航一律不要。
- 复用已抓结果。同一轮编排里重复引用同一 URL,直接复用第一次的输出,别重抓。
配合 编排式三段提示协议看更清楚:规划位的输入应该是「相关片段」,不是「所有可能相关的页面」。缓存命中的前提也是输入前缀稳定,这点在抓取结果的拼接顺序上同样适用——固定顺序,别每轮重排。
六、本地服务的安全边界
跑在本机不代表没有风险,三条必须守:
- 只监听回环地址。不要绑到对外网卡,浏览器里一个恶意页面就可能借机探测本机服务。
- 做来源校验。近期的 MCP 生态更新里已经出现针对 DNS rebinding 与跨站 TCP 请求的显式拦截,配置时确认这类防护是开着的。
- 凭据不落配置文件。用 stdin 或环境变量注入,别把 Key 写进会提交到仓库的 JSON。
这与终端侧「不可信目录默认禁用项目级 MCP 配置、需要显式信任」是同一套思路:Agent 的工具权限,默认应该是收窄的,用到哪一层再开哪一层。
七、故障排查表
| 现象 | 常见原因 | 处理 |
|---|---|---|
| cargo install 编译失败 | 缺 C 编译器或工具链过旧 | 装编译工具链后更新 Rust 再试 |
| 命令找不到 | cargo 的 bin 目录不在 PATH | 把 cargo bin 加进 PATH |
| 服务起不来 | 端口被占用 | 换端口或停掉冲突进程 |
| 客户端列不出工具 | command / args 与实际不符 | 对照 --help 核对参数 |
| 工具调用超时 | 目标站点响应慢 | 调大客户端超时,别无限重试 |
| 抓取结果为空 | 页面靠 JS 渲染 | 换静态可抓取的等价来源 |
| 正文混入导航 | 未限定主体区域 | 指定主体选择器或改用结构化抽取 |
| Markdown 里表格错乱 | 原页表格合并单元格 | 人工核对关键数据,别直接采信 |
| 内容被截断 | 单次输出过长 | 分页抓取,按段落切分 |
| 中文乱码 | 响应编码识别错 | 显式指定字符集再转码 |
| 密钥出现在 history | 明文写进命令行 | 改用 stdin 注入方式 |
| 升级后配置失效 | 参数或端点变更 | 按新版 README 重配,保留旧配置备份 |
八、验证清单
- 本地能列出工具,且工具名与预期一致
- 抓一个静态文档页,输出是干净 Markdown、无导航与脚本残留
- 同一 URL 二次引用走复用,不重复抓
- 服务仅监听回环地址
- 配置文件里没有明文凭据
- 与编排流程接通后,规划位拿到的是片段而非整页
相关阅读
- 编排模型的接入配置:双模型编排配置指南
- Agent 工具权限的终端侧实践:OpenCode 接入
- MCP 客户端配置基础:Cursor MCP 接入