Firecrawl
OpenClaw 可以通过三种方式使用 Firecrawl:
- 作为
web_search提供商 - 作为显式插件工具:
firecrawl_search和firecrawl_scrape - 作为
web_fetch的回退提取器
它是一个托管的提取/搜索服务,支持绕过机器人检测和缓存,有助于处理重度依赖 JavaScript 的网站或阻止普通 HTTP 抓取的页面。
安装插件¶
安装官方插件:
安装会自动应用到正在运行的 Gateway;否则将在下次启动时生效。参见 应用更改并检查。
无密钥访问和 API 密钥¶
Firecrawl 注册了两个 web_search 提供商:
- Firecrawl Search(
firecrawl)— 使用你的密钥调用托管的/v2/searchAPI;存在密钥时会自动检测。 - Firecrawl Search (Free)(
firecrawl-free)— 使用托管的无密钥入门层,无需 API 密钥。它仅手动启用,且永远不会被自动选择,因为选择它会将你的搜索查询发送到 Firecrawl 的免费层。
显式选择的 Firecrawl web_fetch 回退也是无密钥的。显式的 firecrawl_search 和 firecrawl_scrape 工具需要 API 密钥。在 Gateway 环境中添加 FIRECRAWL_API_KEY,或配置它以获得更高限额。从 Firecrawl 控制台 获取密钥。
配置 Firecrawl 搜索¶
{
tools: {
web: {
search: {
provider: "firecrawl",
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webSearch: {
apiKey: "FIRECRAWL_API_KEY_HERE",
baseUrl: "https://api.firecrawl.dev",
},
},
},
},
},
}
说明:
- 在引导流程或
openclaw configure --section web中选择 Firecrawl 会自动启用已安装的 Firecrawl 插件。 - 在引导流程中选择 Firecrawl Search (Free)(或设置
provider: "firecrawl-free")即可无密钥运行,无需 API 密钥。带密钥的 Firecrawl Search 提供商会发送plugins.entries.firecrawl.config.webSearch.apiKey或FIRECRAWL_API_KEY。 - 使用 Firecrawl 的
web_search支持query和count。 - 对于 Firecrawl 特有的控制项,例如
sources、categories或结果抓取,请使用firecrawl_search。 baseUrl默认为托管 Firecrawl 的https://api.firecrawl.dev。自托管覆盖仅允许用于私有/内部端点;HTTP 仅接受这些私有目标。FIRECRAWL_BASE_URL是 Firecrawl 搜索和抓取基础 URL 的共享环境变量回退值。- Firecrawl 搜索请求默认超时时间为 30 秒;
firecrawl_search的timeoutSeconds参数可按调用覆盖该值。
两个 Firecrawl web_search 提供商和 firecrawl_search 都使用 tools.web.search.cacheTtlMinutes 作为 OpenClaw 本地结果缓存(默认:15 分钟)。将其设置为 0 可绕过缓存读取和写入。较短的 TTL 会限制现有条目的复用;较长的 TTL 不会延长其原始过期时间。此设置不会更改 Firecrawl 的上游抓取缓存。
配置 Firecrawl web_fetch 回退¶
{
tools: {
web: {
fetch: {
provider: "firecrawl", // explicit selection enables keyless fallback
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webFetch: {
baseUrl: "https://api.firecrawl.dev",
onlyMainContent: true,
maxAgeMs: 172800000,
timeoutSeconds: 60,
},
},
},
},
},
}
说明:
- 显式选择的 Firecrawl
web_fetch回退无需 API 密钥即可工作。配置后,OpenClaw 会发送plugins.entries.firecrawl.config.webFetch.apiKey或FIRECRAWL_API_KEY以获得更高限额。 - 在引导流程或
openclaw configure --section web中选择 Firecrawl 会启用插件,并为web_fetch选择 Firecrawl,除非已配置其他抓取提供商。 firecrawl_scrape需要 API 密钥。maxAgeMs控制缓存结果可保留多久(毫秒)。默认值为 172,800,000 毫秒(2 天)。onlyMainContent默认为true;timeoutSeconds默认为 60。- 旧版
tools.web.fetch.firecrawl.*和tools.web.search.firecrawl.*配置会由openclaw doctor --fix自动迁移。 - Firecrawl 抓取/基础 URL 覆盖遵循与搜索相同的托管/私有规则:公共托管流量使用
https://api.firecrawl.dev;自托管覆盖必须解析到私有/内部端点。 firecrawl_scrape在将目标 URL 转发到 Firecrawl 之前,会拒绝明显的私有、回环、元数据以及非 HTTP(S) 目标 URL,以符合显式 Firecrawl 抓取调用的web_fetch目标安全约定。
firecrawl_scrape 复用相同的 plugins.entries.firecrawl.config.webFetch.* 设置和环境变量,包括其必需的 API 密钥。
自托管 Firecrawl¶
当你自行运行 Firecrawl 时,请设置 plugins.entries.firecrawl.config.webSearch.baseUrl、plugins.entries.firecrawl.config.webFetch.baseUrl 或 FIRECRAWL_BASE_URL。OpenClaw 仅对回环、私有网络、.local、.internal 或 .localhost 目标接受 http://。公共自定义主机将被拒绝,以免 Firecrawl API 密钥被意外发送到任意端点。
Firecrawl 插件工具¶
firecrawl_search¶
当你需要 Firecrawl 特有的搜索控制项,而不是通用 web_search 时,请使用此工具。需要 API 密钥。
参数:
querycount(1-100)sourcescategoriesincludeDomains/excludeDomains(仅限主机名;互斥)tbs(时间过滤器,例如qdr:d、qdr:w、sbd:1)location和country(地理定位)scrapeResultstimeoutSeconds
firecrawl_scrape¶
对于重度依赖 JavaScript 或受机器人保护的页面,普通 web_fetch 效果较弱时,请使用此工具。
参数:
urlextractModemaxCharsonlyMainContentmaxAgeMsproxystoreInCachetimeoutSeconds
隐身 / 机器人规避¶
firecrawl_scrape 和 web_fetch 的 Firecrawl 回退默认使用 proxy: "auto" 以及 storeInCache: true,除非调用方覆盖这些参数。firecrawl_search 和 web_search 的 Firecrawl 提供商没有 proxy/storeInCache 控制项;隐身代理模式仅适用于 scrape/fetch 请求。
Firecrawl 的 proxy 模式控制机器人规避(basic、stealth 或 auto)。如果 basic 尝试失败,auto 会使用隐身代理重试,这可能会比仅使用 basic 的抓取消耗更多积分。
web_fetch 如何使用 Firecrawl¶
web_fetch 提取顺序:
- Readability(本地)
- 已配置的 fetch 提供商,例如 Firecrawl(当被选中时,或从已配置的凭据中自动检测)
- 基础 HTML 清理(最后回退)
选择项是 tools.web.fetch.provider。如果省略它,OpenClaw 会从可用凭据中自动检测第一个就绪的 web-fetch 提供商。官方 Firecrawl 插件提供该回退。
相关¶
- Web Search 概览 -- 所有提供商和自动检测
- Web Fetch -- 带 Firecrawl 回退的 web_fetch 工具
- Tavily -- 搜索 + 提取工具
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw