Apus can use Firecrawl in three ways:

It is a hosted extraction/search service that supports bot circumvention and caching, which helps with JS-heavy sites or pages that block plain HTTP fetches.

Install plugin

Install the official plugin:

apus plugins install @openclaw/firecrawl-plugin

Installation applies to a running Gateway automatically; otherwise it takes effect on the next startup. See Apply changes and inspect.

Keyless access and API keys

Firecrawl registers two web_search providers:

The explicitly selected Firecrawl web_fetch fallback is also keyless. The explicit firecrawl_search and firecrawl_scrape tools require an API key. Add FIRECRAWL_API_KEY in the gateway environment or configure it for higher limits. Get a key from the Firecrawl dashboard.

Configure Firecrawl search

{
  tools: {
    web: {
      search: {
        provider: "firecrawl",
      },
    },
  },
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "FIRECRAWL_API_KEY_HERE",
            baseUrl: "https://api.firecrawl.dev",
          },
        },
      },
    },
  },
}

Notes:

Both Firecrawl web_search providers and firecrawl_search use tools.web.search.cacheTtlMinutes for Apus's local result cache (default: 15 minutes). Set it to 0 to bypass cache reads and writes. A shorter TTL limits reuse of existing entries; a longer TTL does not extend their original expiry. This setting does not change Firecrawl's upstream scrape caching.

Configure Firecrawl web_fetch fallback

{
  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,
          },
        },
      },
    },
  },
}

Notes:

firecrawl_scrape reuses the same plugins.entries.firecrawl.config.webFetch.* settings and env vars, including its required API key.

Self-hosted Firecrawl

Set plugins.entries.firecrawl.config.webSearch.baseUrl, plugins.entries.firecrawl.config.webFetch.baseUrl, or FIRECRAWL_BASE_URL when you run Firecrawl yourself. Apus accepts http:// only for loopback, private-network, .local, .internal, or .localhost targets. Public custom hosts are rejected so Firecrawl API keys are not sent to arbitrary endpoints by accident.

Firecrawl plugin tools

firecrawl_search

Use this when you want Firecrawl-specific search controls instead of generic web_search. Requires an API key.

Parameters:

firecrawl_scrape

Use this for JS-heavy or bot-protected pages where plain web_fetch is weak.

Parameters:

Stealth / bot circumvention

firecrawl_scrape and the web_fetch Firecrawl fallback default to proxy: "auto" plus storeInCache: true unless the caller overrides those parameters. firecrawl_search and the web_search Firecrawl provider have no proxy/storeInCache controls; stealth proxy mode only applies to scrape/fetch requests.

Firecrawl's proxy mode controls bot circumvention (basic, stealth, or auto). auto retries with stealth proxies if a basic attempt fails, which may use more credits than basic-only scraping.

How web_fetch uses Firecrawl

web_fetch extraction order:

  1. Readability (local)
  2. Configured fetch provider, such as Firecrawl (when selected, or auto-detected from configured credentials)
  3. Basic HTML cleanup (last fallback)

The selection knob is tools.web.fetch.provider. If you omit it, Apus auto-detects the first ready web-fetch provider from available credentials. The official Firecrawl plugin provides that fallback.

Related