OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Firecrawl

OpenClaw는 다음 세 가지 방식으로 Firecrawl을 사용할 수 있습니다.

  • web_search 제공자로 사용
  • 명시적 Plugin 도구인 firecrawl_search 및 firecrawl_scrape로 사용
  • web_fetch의 대체 추출기로 사용

Firecrawl은 봇 우회와 캐싱을 지원하는 호스팅 추출/검색 서비스로, JS 의존도가 높은 사이트나 일반 HTTP 가져오기를 차단하는 페이지에 유용합니다.

Plugin 설치

공식 Plugin을 설치한 후 Gateway를 다시 시작하십시오.

bash
openclaw plugins install @openclaw/firecrawl-pluginopenclaw gateway restart

키 없는 액세스 및 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 검색 구성

json5
{  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 Plugin이 자동으로 활성화됩니다.
  • API 키 없이 실행하려면 온보딩에서 **Firecrawl Search (Free)**를 선택하거나 provider: "firecrawl-free"을 설정하십시오. 키를 사용하는 Firecrawl Search 제공자는 plugins.entries.firecrawl.config.webSearch.apiKey 또는 FIRECRAWL_API_KEY을 전송합니다.
  • Firecrawl을 사용하는 web_search은 query 및 count을 지원합니다.
  • sources, categories, 결과 스크래핑과 같은 Firecrawl 전용 제어 기능을 사용하려면 firecrawl_search을 사용하십시오.
  • baseUrl은 기본적으로 https://api.firecrawl.dev의 호스팅된 Firecrawl을 사용합니다. 자체 호스팅 재정의는 비공개/내부 엔드포인트에만 허용되며, HTTP도 이러한 비공개 대상에만 허용됩니다.
  • FIRECRAWL_BASE_URL은 Firecrawl 검색 및 스크래핑 기본 URL에 공통으로 사용되는 환경 변수 대체 값입니다.
  • Firecrawl 검색 요청의 기본 제한 시간은 30초이며, firecrawl_search의 timeoutSeconds 매개변수를 사용하면 호출별로 재정의할 수 있습니다.

Firecrawl web_fetch 대체 경로 구성

json5
{  tools: {    web: {      fetch: {        provider: "firecrawl", // 명시적으로 선택하면 키 없는 대체 경로가 활성화됩니다      },    },  },  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을 선택하면 다른 가져오기 제공자가 이미 구성되어 있지 않은 한 Plugin을 활성화하고 web_fetch용으로 Firecrawl을 선택합니다.
  • firecrawl_scrape에는 API 키가 필요합니다.
  • maxAgeMs은 캐시된 결과를 얼마나 오래된 것까지 사용할 수 있는지(ms)를 제어합니다. 기본값은 172,800,000ms(2일)입니다.
  • onlyMainContent의 기본값은 true이며, timeoutSeconds의 기본값은 60입니다.
  • 기존 tools.web.fetch.firecrawl.* 및 tools.web.search.firecrawl.* 구성은 openclaw doctor --fix에 의해 자동으로 마이그레이션됩니다.
  • Firecrawl 스크래핑/기본 URL 재정의에는 검색과 동일한 호스팅/비공개 규칙이 적용됩니다. 공개 호스팅 트래픽은 https://api.firecrawl.dev을 사용하며, 자체 호스팅 재정의는 비공개/내부 엔드포인트로 확인되어야 합니다.
  • firecrawl_scrape은 명백한 비공개, 루프백, 메타데이터 및 비 HTTP(S) 대상 URL을 Firecrawl로 전달하기 전에 거부하며, 명시적 Firecrawl 스크래핑 호출에 대한 web_fetch 대상 안전 계약을 따릅니다.

firecrawl_scrape은 필수 API 키를 포함하여 동일한 plugins.entries.firecrawl.config.webFetch.* 설정과 환경 변수를 재사용합니다.

자체 호스팅 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 Plugin 도구

일반적인 web_search 대신 Firecrawl 전용 검색 제어 기능을 사용하려는 경우 이 도구를 사용하십시오. API 키가 필요합니다.

매개변수:

  • query
  • count(1-100)
  • sources
  • categories
  • includeDomains / excludeDomains(호스트 이름만 허용되며 상호 배타적임)
  • tbs(시간 필터, 예: qdr:d, qdr:w, sbd:1)
  • location 및 country(지역 타기팅)
  • scrapeResults
  • timeoutSeconds

firecrawl_scrape

일반적인 web_fetch으로 처리하기 어려운 JS 의존도가 높은 페이지나 봇 차단 페이지에 이 도구를 사용하십시오.

매개변수:

  • url
  • extractMode
  • maxChars
  • onlyMainContent
  • maxAgeMs
  • proxy
  • storeInCache
  • timeoutSeconds

스텔스/봇 우회

호출자가 해당 매개변수를 재정의하지 않는 한 firecrawl_scrape 및 web_fetch Firecrawl 대체 경로는 기본적으로 proxy: "auto"과 storeInCache: true을 함께 사용합니다. firecrawl_search 및 web_search Firecrawl 제공자에는 proxy/storeInCache 제어 기능이 없습니다. 스텔스 프록시 모드는 스크래핑/가져오기 요청에만 적용됩니다.

Firecrawl의 proxy 모드는 봇 우회 방식(basic, stealth, 또는 auto)을 제어합니다. auto은 기본 시도가 실패하면 스텔스 프록시로 재시도하므로 기본 스크래핑만 사용할 때보다 더 많은 크레딧이 소모될 수 있습니다.

web_fetch에서 Firecrawl을 사용하는 방식

web_fetch 추출 순서:

  1. Readability(로컬)
  2. Firecrawl과 같이 구성된 가져오기 제공자(선택되었거나 구성된 자격 증명에서 자동 감지된 경우)
  3. 기본 HTML 정리(최종 대체 경로)

선택 설정은 tools.web.fetch.provider입니다. 이를 생략하면 OpenClaw는 사용 가능한 자격 증명에서 준비된 첫 번째 웹 가져오기 제공자를 자동으로 감지합니다. 공식 Firecrawl Plugin이 이 대체 경로를 제공합니다.

관련 문서

Was this useful?
On this page

On this page