Firecrawl

OpenClaw 可以通过三种方式使用 Firecrawl：

作为 web_search 提供商
作为显式插件工具：firecrawl_search 和 firecrawl_scrape
作为 web_fetch 的回退提取器

它是一个托管的提取/搜索服务，支持绕过机器人限制和缓存，有助于处理 JS 密集型网站或阻止普通 HTTP 抓取请求的页面。

安装插件¶

安装官方插件：

openclaw plugins install @openclaw/firecrawl-plugin

安装会自动应用于正在运行的 Gateway；否则将在下次启动时生效。参见应用更改并检查。

无密钥访问与 API 密钥¶

Firecrawl 注册了两个 web_search 提供商：

Firecrawl Search（firecrawl）— 使用你的密钥调用托管的 /v2/search API；当存在密钥时自动检测。
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，除非已配置其他 fetch 提供商。
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 密钥。

参数：

query
count（1-100）
sources
categories
includeDomains / excludeDomains（仅限主机名；互斥）
tbs（时间过滤器，例如 qdr:d、qdr:w、sbd:1）
location 和 country（地理定向）
scrapeResults
timeoutSeconds

`firecrawl_scrape`¶

对于 JS 密集型或受机器人保护的页面，当普通 web_fetch 效果不佳时，请使用此工具。

参数：

url
extractMode
maxChars
onlyMainContent
maxAgeMs
proxy
storeInCache
timeoutSeconds

隐身 / 机器人规避¶

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