AI 에이전트가 '웹을 방문하도록' 만드는 기반으로서, Firecrawl이라는 OSS 프로젝트가 급성장하고 있습니다. GitHub의 스타 수는 2026년 7월 기준으로 15만 개를 초과했으며, 공식 웹사이트에 따르면 주간으로 npm/PyPI 합쳐 250만 회 이상 다운로드되고 있다고 합니다2.
본 기사에서는 firecrawl-cli를 실제로 설치하고, API 키를 전혀 설정하지 않은 상태에서 각 커맨드가 어디까지 작동하는지 하나씩 검증했습니다. 그 결과, 공식 문서 설명만으로는 알 수 없었던 '캐시의 동작'에 주목하게 되었고, 이에 대한 메커니즘도 함께 설명합니다.
-
Firecrawl의 전체 구성 (호스트 버전 API와 셀프 호스팅의 차이)
-
firecrawl-cli로 API 키 없이 작동하는 커맨드/작동하지 않는 커맨드의 실측 결과 - 스크래프 결과가 기본적으로 2일간 캐시되는 메커니즘과 주의점
-
Claude Code의 클라우드 실행 환경 (Linux・Node.js)
-
npm install -g firecrawl-cli
(버전 1.19.26)
- Firecrawl은 '웹을 검색/스크래프/조작하여 AI 에이전트가 사용하기 쉬운 형태(Markdown/JSON)로 전달'하는 OSS API입니다. 핵심 부분은 AGPL-3.0, SDK는 MIT, CLI(
firecrawl-cli)는 ISC 라이선스입니다.
scrape와 search는 API 키 없이도 작동합니다 (IP 기반 무료 사용량). 반면 map, crawl, credit-usage는 로그인을 요구하며 무료 사용량 대상이 아닙니다.scrape는 기본적으로 2일간(172,800,000밀리초) 동일 페이지의 캐시를 반환하기 때문에, 같은 URL을 연속으로 호출해도 최신 정보가 돌아오지 않을 수 있습니다.
Firecrawl은 '검색/스크래프/페이지 조작을 AI 에이전트가 사용하기 쉬운 형태(Markdown/JSON)로 반환'하는 데 특화된 OSS 프로젝트입니다. 주요 레포지토리는 다음 구성으로 나뉘어 있습니다.
| 컴포넌트 | 역할 | 배포 형태 |
|---|
firecrawl/firecrawl | 본체 API (Node.js/TypeScript + Rust 제작 크롤러) | AGPL-3.0 (셀프 호스팅 가능) |
firecrawl-cli (npm) | 터미널에서 scrape /search /crawl 등 실행하는 CLI | ISC |
firecrawl / @mendable/firecrawl-js (npm) | JavaScript SDK | MIT |
핵심 API 서버는 AGPL-3.0, SDK는 MIT, CLI는 ISC라는 분리된 구조를 가지고 있어, SDK를 통해 호스트 버전 API를 호출하는 한 상업적 이용에서도 문제가 생기기 어려운 구성입니다1.
npm install -g firecrawl-cli
firecrawl --version
실행하면 다음과 같이 설치되었습니다 (해당 세션에서 실행된 원본 로그).
$ firecrawl --version
1.19.26
firecrawl --help로 서브 커맨드 목록을 확인할 수 있습니다. scrape / crawl / map / search / agent / interact 등, AI 에이전트가 '웹에서 무언가를 검색하고 조작'하는 데 필요한 모든 기능이 갖춰져 있습니다.
공식 문서에는 '일부 커맨드는 로그인 없이도 작동한다 (keyless free tier・IP 기반으로 속도 제한)'라는 내용이 있습니다3. 실제로 로그인된 API 키를 설정하지 않고, FIRECRAWL_API_KEY 환경 변수도 설정하지 않은 상태에서 주요 커맨드를 하나씩 시도했습니다.
$ firecrawl scrape https://example.com
Scrape ID: 019f6415-387a-7146-9405-e7e2b14af3ab
# Example Domain
...
```}{
scrape
그리고 search는 인증 정보를 아무것도 전달하지 않았음에도 불구하고 실제로 네트워크를 통해 페이지 내용과 검색 결과를 가져올 수 있었습니다. 로그인하라는 프롬프트도 나타나지 않습니다.
$ firecrawl search "test query anonymous"
Anonymous Block in Query Service | Adobe Experience Platform
URL: https://experienceleague.adobe.com/en/docs/experience-platform/query/key-concepts/anonymous-block
...
`map`
・`crawl`
・`credit-usage`
의 3개 명령어는 표준 입력을 닫은 상태(`</dev/null>`)로 실행해도 이 로그인 선택 화면이 그대로 표시되어 비대화형 환경에서는 실행할 수 없었습니다. `parse` (로컬 파일의 Markdown 변환)는 API 통신 자체가 발생하지 않기 때문에 당연히 인증 없이 작동합니다.
즉, '무료 사용량으로 동작한다'고 일괄적으로 말할 수 없고, **scrape와 search만이 IP 기반 무료 사용량의 대상**이라는 것이 실측 결과였습니다.
`scrape` 명령어로 동일한 URL을 3회 연속으로 실행했을 때 이상한 동작을 발견했습니다. 임의의 UUID를 반환하는 `https://httpbin.org/uuid`를 3번 스크래핑하자, **세 번 모두 같은 UUID**가 반환된 것입니다.
$ for i in 1 2 3; do firecrawl scrape "https://httpbin.org/uuid"; done
{"uuid": "dee83b13-c9d7-4a2f-a840-4a0a5eeb4dd5"}
{"uuid": "dee83b13-c9d7-4a2f-a840-4a0a5eeb4dd5"}
...
비교를 위해, 동일한 URL을 `curl`로 직접 2번 실행했을 때는 예상대로 매번 다른 UUID가 반환되었습니다.
$ curl -s https://httpbin.org/uuid; curl -s https://httpbin.org/uuid
{"uuid": "db8705e9-ab31-4775-b609-2af39a098c65"}
{"uuid": "98baafcf-1e34-4ece-8ae4-05e5a4d362fc"}
즉, 이 캐시는 네트워크 경로의 문제가 아니라 Firecrawl 자체의 사양이었습니다. 공식 문서의 `scrape` 엔드포인트에는 `maxAge`라는 파라미터가 있으며, **기본값은 172,800,000밀리초(2일)**로 명시되어 있습니다. 이 기간 내에 캐시된 페이지가 있으면 실제로 페이지에 다시 접근하지 않고 캐시를 반환하는 사양입니다4.
maxAge (기본값: 172800000ms = 2일)
→ 이 기간 내에 캐시된 버전이 있으면, 재스크래핑 없이 캐시를 반환함
→ 항상 최신 페이지 내용이 필요한 경우 maxAge: 0을 명시적으로 지정해야 함
요금제 플랜 문서에는 '신선도가 필요하지 않다면 캐시를 활성화하면 속도를 높일 수 있다'는 설명은 있지만, '기본적으로 2일간 캐시된다'는 점은 적극적으로 강조되지 않았습니다. 속보성이 필요한 스크래핑(재고 확인・가격 모니터링・최신 뉴스 수집 등)에 그대로 사용하면 의도치 않게 오래된 정보를 얻을 가능성이 있으므로 주의가 필요합니다.
Firecrawl 자체는 Docker를 이용해 직접 호스팅할 수도 있습니다. 공식의 `SELF_HOST.md`에 따르면, 다음 구성이 필요합니다5.
- Docker / Docker Compose
- Redis (큐 관리・레이트 제한)
- PostgreSQL (설정・스크래핑 데이터 저장)
- Playwright (브라우저 기반 스크래핑용 마이크로서비스)
.env를 준비한 후
docker compose build
docker compose up
CLI에서 사용할 경우에는 `--api-url`
세ルフホスト(self-host)할 URL을 지정하면, 호스트 버전의 API 키 인증이 건너뛰어지는 사양입니다. 하지만 공식 문서는 '세ルフホスト 버전에는 Fire-engine (IP 블록 회피 등의 강화 기능)가 포함되지 않는다'고 명시하고 있으므로, 대규모 사이트 크롤링 시 호스트 버전과의 기능 차이가 있다는 점은 이해해 두어야 합니다5.
실제로 직접 사용해보니 가장 놀라웠던 부분은 '무료로 작동한다'는 설명의 디테일이 공식 문서의 설명보다 훨씬 상세했다는 점입니다. 문서상으로는 '일부 커맨드가 로그인 없이 작동한다'고만 되어 있어, 어떤 커맨드가 대상인지 실제로 하나하나 실행해 보지 않으면 알 수 없었습니다. `scrape`와 `search`만이 무료 사용 범위에 해당하고, `map`이나 `crawl`은 바로 로그인 화면으로 이동합니다. 이러한 비대칭성은 CI/CD 등 비대화형 환경에서 Firecrawl을 통합하려 할 때 사전에 파악해 두지 않으면 막히기 쉬운 포인트라고 느꼈습니다.
- Firecrawl은 AI 에이전트를 위해 검색, 스크래핑, 페이지 조작 기능을 제공하는 OSS 프로젝트입니다. 코어는 AGPL-3.0, SDK는 MIT, CLI는 ISC 라이선스를 따릅니다.
- `firecrawl-cli`에서는 `scrape`와 `search`만이 API 키가 필요 없는 IP 기반 무료 사용 범위에서 작동하며, `map`, `crawl`, `credit-usage`는 로그인이 필수입니다. -
`scrape`는 기본적으로 2일간 캐시를 반환하는 사양입니다. 속보성이 필요한 용도의 경우 `maxAge: 0`을 명시하거나 이 동작을 전제로 설계할 필요가 있습니다.
무료 사용 범위만으로는 시도할 수 있는 영역이 제한적이지만, 'AI 에이전트에게 웹을 보여주는' 구현의 첫걸음으로 CLI를 설치하여 어떤 커맨드가 실제로 작동하는지 직접 확인해 보는 것을 추천합니다.
- firecrawl/firecrawl - GitHub — 라이선스 구성 및 스타 개수 확인
- Firecrawl CLI Docs — keyless free tier 설명
- Firecrawl Scrape API Reference — `maxAge` 파라미터 사양 - SELF_HOST.md - firecrawl/firecrawl — 세ルフホスト 절차
- firecrawl/firecrawl - GitHub (2026년 7월 기준으로 스타 15만 개 초과, AGPL-3.0 코어 + MIT SDK 구성 확인) ↩ ↩
2 -
Firecrawl 공식 사이트 'About' (주간 250만 다운로드 기재) ↩
- Firecrawl CLI Docs (keyless free tier 기재) ↩
- Firecrawl Scrape API Reference ( `maxAge` 기본값 172800000ms 기재) ↩ - SELF_HOST.md - firecrawl/firecrawl (Docker/Redis/PostgreSQL/Playwright 구성, Fire-engine 미지원 기재) ↩ ↩
2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
