Crawl4AI를 처음 사용하는 경우에는 pip 설치, Playwright 브라우저 준비, crawl4ai-doctor 확인, 단일 URL 크롤링 순서로 시작하는 것이 가장 단순합니다. 기본 크롤링에는 LLM API 키가 필요하지 않으며, 동적 페이지나 Docker 서버가 필요할 때만 설정을 확장하면 됩니다. 아래 예제는 임의로 실행 결과를 만들어 넣지 않고 Crawl4AI 공식 문서에 공개된 명령과 설정을 기준으로 구성했습니다.
Crawl4AI 5분 설치 가이드
먼저 사용 중인 Python 환경에서 패키지를 설치합니다. 안정 버전을 사용하려면 다음 명령을 실행합니다.
python -m pip install -U crawl4ai
crawl4ai-setup
crawl4ai-doctorcrawl4ai-setup은 크롤링에 필요한 브라우저 구성 요소를 준비하고 운영체제 수준의 누락 항목을 확인합니다. 이어서 crawl4ai-doctor를 실행하면 Python 호환성, Playwright 설치 상태, 환경 변수 또는 라이브러리 충돌 여부를 진단할 수 있습니다. 설치 명령이 성공했다는 사실만 보고 끝내지 말고 doctor가 표시하는 오류가 없는지 확인한 다음 기본 크롤링으로 넘어가야 합니다.
새 기능을 먼저 확인해야 하는 특별한 경우에만 프리릴리스 버전을 선택합니다. 운영용 글의 기본값으로 프리릴리스를 권장하면 재현성이 떨어질 수 있으므로 안정 버전과 명확히 구분합니다.
python -m pip install crawl4ai --prePlaywright 설치 오류 해결
crawl4ai-setup 과정에서 브라우저 관련 오류가 표시되면 Playwright 브라우저를 별도로 설치합니다. 일반적인 Chromium 설치와 Linux 종속성까지 함께 처리하는 명령은 다음과 같습니다.
python -m playwright install chromium
# Linux에서 운영체제 종속성까지 필요한 경우
python -m playwright install --with-deps chromium설치 후에는 다시 crawl4ai-doctor를 실행합니다. 브라우저 실행 파일을 찾지 못한다는 메시지가 계속된다면 명령을 실행한 Python과 Crawl4AI가 설치된 Python이 같은 환경인지 먼저 확인해야 합니다. 이를 확인할 때는 다음처럼 실행 경로와 패키지 정보를 함께 조회할 수 있습니다.
python --version
python -m pip show crawl4ai
python -m playwright --version실제 URL을 크롤링하는 기본 코드
공식 문서의 기본 구조에 브라우저 설정, 실행 설정, 성공 여부 확인을 명시적으로 추가하면 각 객체의 역할을 이해하기 쉽습니다. 아래 코드는 예제용 공개 도메인을 요청하고, 성공하면 변환된 Markdown 일부를 출력하며, 실패하면 오류 메시지를 출력하도록 작성했습니다.
import asyncio
from crawl4ai import (
AsyncWebCrawler,
BrowserConfig,
CacheMode,
CrawlerRunConfig,
)
async def main():
browser_config = BrowserConfig(headless=True)
run_config = CrawlerRunConfig(
cache_mode=CacheMode.BYPASS,
check_robots_txt=True,
page_timeout=60000,
)
async with AsyncWebCrawler(config=browser_config) as crawler:
result = await crawler.arun(
url="https://www.example.com",
config=run_config,
)
if result.success:
print(result.markdown[:500])
else:
print(result.error_message)
if __name__ == "__main__":
asyncio.run(main())| 구성 요소 | 역할 | 처음 사용할 때 확인할 값 |
|---|---|---|
BrowserConfig |
브라우저 실행 환경을 설정합니다. | headless=True이면 별도 브라우저 창 없이 실행됩니다. |
CrawlerRunConfig |
각 요청의 캐시, 대기 조건과 타임아웃 같은 실행 방식을 설정합니다. | 처음에는 필요한 옵션만 명시합니다. |
CacheMode.BYPASS |
이번 요청에서 캐시를 우회합니다. | 변경된 페이지를 다시 확인할 때 유용합니다. |
check_robots_txt |
크롤링 전에 robots.txt 규칙을 확인하도록 설정합니다. | 대상 사이트의 정책도 별도로 확인해야 합니다. |
result.success |
요청 성공 여부를 판단합니다. | 실패 시 Markdown을 사용하지 말고 error_message를 확인합니다. |
동적 페이지는 대기 조건을 따로 설정
일반 HTML 페이지와 달리 JavaScript로 본문을 나중에 그리는 페이지는 탐색이 끝난 직후 내용을 읽으면 빈 결과가 나올 수 있습니다. CrawlerRunConfig의 wait_until, wait_for, page_timeout을 사용하면 어떤 상태까지 기다릴지 명시할 수 있습니다.
run_config = CrawlerRunConfig(
wait_until="domcontentloaded",
wait_for="css:main",
page_timeout=60000,
)wait_for="css:main"은 페이지에 <main> 요소가 나타날 때까지 기다리라는 뜻입니다. 모든 사이트가 main을 사용하는 것은 아니므로 실제 페이지에서 존재하는 선택자로 바꿔야 합니다. 기다리는 시간을 단순히 늘리기 전에 선택자가 정확한지 먼저 확인하는 것이 중요합니다.
버튼 클릭이나 스크롤이 필요한 페이지는 js_code 또는 별도의 상호작용 기능을 사용할 수 있습니다. 다만 로그인, 결제, 개인정보 입력과 같은 작업은 일반적인 콘텐츠 크롤링 예제에 포함하지 않는 편이 안전합니다.
CLI로 빠르게 결과 확인하기
Python 파일을 만들기 전에 명령줄에서 빠르게 Markdown 출력을 확인하려면 설치와 함께 제공되는 crwl 명령을 사용할 수 있습니다. 단일 페이지, 딥 크롤링, LLM 추출은 목적과 비용이 다르므로 한꺼번에 사용하지 말고 필요한 방식만 선택합니다.
# 단일 페이지를 Markdown으로 출력
crwl https://www.example.com -o markdown
# 문서 사이트를 BFS 방식으로 최대 10페이지 탐색
crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10
# LLM을 사용하는 질문 기반 추출 예시
crwl https://www.example.com/products -q "Extract all product prices"첫 번째 명령은 기본 크롤링 확인에 적합합니다. 딥 크롤링은 요청 수가 늘어날 수 있으므로 대상 사이트의 이용정책과 robots.txt를 확인하고 탐색 범위를 작게 설정해야 합니다. -q를 사용하는 LLM 추출은 구성한 공급자에 따라 별도의 API 키와 비용이 필요할 수 있으므로 기본 Markdown 변환과 구분해야 합니다.
예상 출력과 결과에서 확인할 항목
이 글은 코드를 직접 실행했다고 주장하거나 측정하지 않은 실행시간을 제시하지 않습니다. 공식 예제를 실행했을 때에는 특정 문구가 똑같이 나오는지만 보는 것보다 아래 항목을 순서대로 확인하는 것이 좋습니다.
result.success가 참인지 확인합니다.result.markdown이 비어 있지 않은지 확인합니다.- 제목, 본문, 목록이 Markdown 구조로 변환됐는지 확인합니다.
- 페이지 메뉴나 쿠키 문구만 남고 핵심 본문이 빠지지 않았는지 확인합니다.
- 실패한 경우
result.error_message를 먼저 기록합니다.
예제 도메인은 제목과 짧은 설명으로 구성되어 있으므로 정상적인 결과는 다음과 같은 구조에 가깝습니다. 라이브러리 버전과 Markdown 생성 설정에 따라 공백이나 링크 표현은 달라질 수 있습니다.
# Example Domain
This domain is for use in illustrative examples in documents.
[More information...]Crawl4AI 오류 해결표
| 증상 | 먼저 확인할 항목 | 공식 기능 범위의 대응 |
|---|---|---|
| 브라우저 실행 파일을 찾지 못함 | crawl4ai-doctor와 Playwright 버전을 확인합니다. |
python -m playwright install chromium을 실행한 뒤 doctor를 다시 실행합니다. |
| 동적 페이지 결과가 비어 있음 | 본문 요소가 나중에 생성되는지, 지정한 CSS 선택자가 실제 존재하는지 확인합니다. | wait_for에 실제 본문 선택자를 지정하고 필요할 때 page_timeout을 조정합니다. |
| 이전 내용이 반복해서 나옴 | 캐시 설정을 확인합니다. | 최신 페이지 확인이 목적이면 해당 요청에서 CacheMode.BYPASS를 사용합니다. |
| 접근 거부 또는 네트워크 실패 | 대상 URL을 브라우저에서 열 수 있는지와 robots.txt·이용정책을 확인합니다. | 차단을 우회하려고 반복 요청하지 말고 요청 빈도와 접근 권한을 먼저 점검합니다. |
| Docker 서버가 시작되지 않음 | docker info로 Docker 상태와 사용 가능한 자원을 확인합니다. |
컨테이너 로그를 확인하고 공식 self-hosting 문서의 요구사항과 현재 설정을 대조합니다. |
| 결과는 성공이지만 핵심 본문이 없음 | 페이지가 iframe, Shadow DOM 또는 JavaScript 렌더링을 사용하는지 확인합니다. | 공식 페이지 상호작용 문서에서 해당 구조에 맞는 설정을 선택합니다. |
오류 문구만 보고 임의의 옵션을 추가하면 다른 버전에서 새로운 문제가 생길 수 있습니다. 먼저 doctor, 오류 메시지, 설치된 패키지 버전과 대상 페이지 구조를 기록한 뒤 공식 문서와 GitHub 이슈를 확인하는 순서가 좋습니다.
Docker 사용법
Docker는 로컬 Python 환경과 분리된 Crawl4AI 서버가 필요할 때 선택합니다. 기본 크롤링에는 LLM 환경파일이 필요하지 않으므로 API 키를 사용하지 않는 명령과 사용하는 명령을 분리해야 합니다.
이미지 내려받기
docker pull unclecode/crawl4ai:latestLLM 없이 기본 서버 실행
docker run -d \
-p 11235:11235 \
--name crawl4ai \
--shm-size=1g \
unclecode/crawl4ai:latestLLM 공급자 키를 사용하는 서버 실행
LLM 기반 추출을 사용할 경우에만 작업 디렉터리에 .llm.env를 만들고 필요한 공급자의 키를 입력합니다. 실제 키를 코드 저장소나 글 본문에 넣어서는 안 됩니다.
cat > .llm.env << EOL
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
EOL
docker run -d \
-p 11235:11235 \
--name crawl4ai \
--env-file .llm.env \
--shm-size=1g \
unclecode/crawl4ai:latest서버가 시작되면 http://localhost:11235/playground에서 설정을 구성하고 API 요청 형태를 확인할 수 있습니다. 인터넷에 직접 공개하기 전에는 사용 중인 버전의 공식 self-hosting 문서에서 인증, 바인딩 주소와 TLS 설정을 확인해야 합니다.
컨테이너 중지와 삭제
docker stop crawl4ai
docker rm crawl4aiDocker 서버를 Python에서 호출하는 구조
공식 Docker 클라이언트 예시는 로컬 서버 주소와 브라우저·크롤러 설정 객체를 전달하는 형태입니다. 인증이 설정된 서버라면 요청 전에 해당 서버의 공식 인증 절차가 추가로 필요합니다.
import asyncio
from crawl4ai import BrowserConfig, CrawlerRunConfig
from crawl4ai.docker_client import Crawl4aiDockerClient
async def main():
async with Crawl4aiDockerClient(
base_url="http://localhost:11235",
verbose=True,
) as client:
results = await client.crawl(
["https://httpbin.org/html"],
browser_config=BrowserConfig(headless=True),
crawler_config=CrawlerRunConfig(),
)
print(results)
if __name__ == "__main__":
asyncio.run(main())robots.txt와 요청 범위 설정
기술적으로 접근할 수 있는 페이지라고 해서 자동 수집이 항상 허용되는 것은 아닙니다. 대상 사이트의 이용약관, robots.txt, 저작권, 개인정보 처리 조건을 먼저 확인해야 합니다. Crawl4AI에는 robots.txt 확인 옵션이 있지만 이 옵션 하나가 모든 법적·계약상 의무를 대신하지는 않습니다.
- 필요한 페이지만 요청하고 딥 크롤링의 탐색 범위를 작게 설정합니다.
- 로그인 뒤의 개인정보나 결제 페이지를 일반 예제로 수집하지 않습니다.
- 여러 URL을 처리할 때 동시 요청 수와 지연 시간을 보수적으로 설정합니다.
- 수집한 원문을 그대로 재배포하기보다 필요한 사실과 구조만 목적에 맞게 사용합니다.
Firecrawl과 선택 기준
Crawl4AI와 Firecrawl은 모두 웹 콘텐츠를 Markdown 또는 구조화된 데이터로 다루는 데 사용할 수 있지만 운영 방식이 다릅니다. 어느 하나가 항상 우월한 것이 아니라 서버 운영 책임, 외부 API 사용, 커스터마이징 범위에 따라 선택해야 합니다.
| 판단 항목 | Crawl4AI | Firecrawl |
|---|---|---|
| 시작 방식 | Python 패키지 또는 자체 Docker 서버 | 관리형 API·SDK 또는 자체 호스팅 |
| 기본 운영 책임 | 브라우저와 실행 환경을 직접 관리합니다. | 관리형 API를 선택하면 서비스 측에서 인프라를 관리합니다. |
| 로컬 제어 | 세션, 프록시, 쿠키와 사용자 스크립트를 직접 구성할 수 있습니다. | 관리형 API 또는 자체 호스팅 방식에 따라 제어 범위가 달라집니다. |
| 비용 판단 | 소프트웨어 사용 외에 자체 서버와 운영 자원을 고려합니다. | 관리형 API 사용량 또는 자체 호스팅 자원을 고려합니다. |
| 적합한 경우 | 로컬 제어와 직접적인 설정이 중요할 때 적합합니다. | 인프라 관리 없이 빠르게 API로 시작하고 싶을 때 관리형 서비스가 편리합니다. |
- 개인 개발 환경에서 설정을 직접 다루고 싶다면: Crawl4AI의 Python 방식부터 시작하는 편이 단순합니다.
- 브라우저 인프라를 직접 유지하고 싶지 않다면: Firecrawl의 관리형 API를 검토할 수 있습니다.
- 외부 서비스로 데이터를 보내기 어려운 환경이라면: 각 도구의 자체 호스팅 요건과 보안 설정을 먼저 비교해야 합니다.
- 대량 수집이 목적이라면: API 요금만 보지 말고 서버 비용, 장애 대응, 프록시와 유지보수 시간을 함께 계산해야 합니다.
자주 묻는 질문
- Q1: 기본 Crawl4AI 크롤링에 LLM API 키가 필요한가요?
- A1: 기본적인 로컬 웹 크롤링과 Markdown 변환에는 LLM API 키가 필요하지 않습니다. 질문 기반 LLM 추출처럼 별도의 모델 기능을 사용할 때만 해당 공급자 설정을 추가합니다.
- Q2:
crawl4ai-doctor만 통과하면 설치가 끝난 것인가요? - A2: doctor는 환경 진단에 유용하지만 마지막으로 단일 공개 URL을 크롤링하여 성공 상태와 Markdown 결과가 비어 있지 않은지도 확인하는 편이 좋습니다.
- Q3: JavaScript 페이지에서 결과가 비어 있으면 시간을 늘리면 되나요?
- A3: 먼저 실제 본문 요소의 CSS 선택자를 확인하고
wait_for에 지정해야 합니다. 선택자가 잘못됐다면 시간만 늘려도 결과가 달라지지 않습니다. - Q4: Docker 실행 시 반드시
.llm.env가 필요한가요? - A4: 기본 서버 실행에는 필요하지 않습니다. LLM 공급자를 사용하는 기능이 필요한 경우에만 환경파일을 만들고 API 키를 전달합니다.
- Q5: Crawl4AI와 Firecrawl 중 무엇이 더 좋은가요?
- A5: 로컬 제어와 직접 운영이 중요하면 Crawl4AI가 적합하고, 관리형 API로 빠르게 시작하려면 Firecrawl이 편리할 수 있습니다. 예상 요청량과 운영 부담을 함께 비교해야 합니다.
