BuilderIO/gpt-crawler 딥다이브
— 웹사이트를 크롤링해서 커스텀 GPT용 지식 파일 하나로

1한 줄 정체

gpt-crawler는 "웹사이트 → LLM이 먹을 수 있는 지식 파일" 변환기다. 사용자가 config.ts에 시작 URL·크롤링 범위·본문 셀렉터만 적어주면, 실제 브라우저(Chromium 등)를 띄워 그 사이트의 페이지들을 순서대로 열고, 지정한 부분의 텍스트만 뽑아 output.json 하나(또는 용량/토큰 한도에 따라 여러 개)로 저장한다.

에이전트도 아니고, 검색엔진도 아니다. AI 추론은 전혀 하지 않는다 — 순수하게 "브라우저 자동화 + 텍스트 추출 + 파일 분할"만 담당하는 파이프라인이고, 결과물을 실제로 "똑똑하게" 만드는 일은 그 JSON을 업로드받는 ChatGPT·Assistants API 쪽 몫이다. 이 역할 분리가 이 프로젝트를 이해하는 첫 번째 열쇠다.

2왜 뜨는가 — 그리고 지금은 어떤 상태인가

이 저장소는 2023년 11월 OpenAI가 커스텀 GPT 기능을 발표한 직후 만들어졌다. "내 문서 사이트를 GPT에게 학습시키고 싶은데, 페이지를 일일이 복사-붙여넣기 하기는 너무 번거롭다"는 아주 구체적인 불편을 정확히 겨냥했고, README에는 Builder.io가 자사 개발 문서로 실제 커스텀 GPT를 만든 예시가 그대로 실려 있다. 짧고 명확한 문제 정의 덕에 "LLM 지식 파일 만들기"의 대표적인 참고 구현으로 자리 잡았다.

다만 정직하게 짚어야 할 부분이 있다. 이 문서 작성 시점(2026-07-29) 기준으로 마지막 커밋은 2025-07-07이고, package.json의 버전은 CHANGELOG상 2025-01-23의 1.5.1에서 멈춰 있다. 즉 "요즘 활발하게 기능이 추가되는 중"이라기보다는, 한 번 완성된 뒤 큰 변화 없이 안정적으로 참조되는 스테디셀러에 가깝다. "왜 지금 뜨는가"보다는 "왜 지금도 계속 언급되는가"로 질문을 바꿔 보는 게 정확하다.

① 문제 정의가 좁고 코드가 짧아 "학습용 표준 예제"로 오래 살아남았다

소스 코드가 src/ 아래 5개 파일, 수백 줄뿐이다. Crawlee·Playwright라는 잘 관리되는 라이브러리 위에 얇게 얹혀 있어서, 라이브러리 쪽이 계속 업데이트되는 한 이 얇은 래퍼 자체는 손댈 일이 적다. "짧아서 읽기 쉽고, 얇아서 안 망가지는" 코드가 시간이 지나도 계속 인용되는 이유다.

② RAG·에이전트 지식 수집 파이프라인의 "가장 쉬운 첫 예제"로 계속 소환된다

"웹사이트를 LLM 지식으로 바꾼다"는 요구는 커스텀 GPT를 넘어 RAG(검색 증강 생성) 파이프라인 전반에서 여전히 흔하다. gpt-crawler는 셀렉터·매치 패턴·토큰 분할이라는 이 문제의 핵심 개념을 가장 적은 코드로 보여주는 예제라서, 각종 블로그·강의·awesome 목록에서 두고두고 다시 소개된다.

③ 실행 방식이 다양해 상황별로 바로 써먹을 수 있다

CLI 대화형 실행, npm start 스크립트 실행, Express API 서버, Docker 컨테이너까지 네 가지 실행 경로를 다 갖췄다. "일단 한 번 돌려보고 싶다"부터 "다른 서비스에서 API로 호출하고 싶다"까지 진입 장벽이 낮다.

3무엇을 해결하나

겉보기엔 "웹사이트 긁어와서 파일로 저장"이라는 단순한 일 같지만, 막상 손으로 하려면 세 가지 지점에서 막힌다. gpt-crawler는 정확히 이 세 가지에만 집중해서 해결한다.

① 페이지가 자바스크립트로 그려지면 단순 요청으론 못 읽는다

많은 문서 사이트는 React·Vue 같은 프레임워크로 페이지를 브라우저 안에서 그린다. 단순히 URL에 HTTP 요청을 보내 받은 HTML엔 실제 본문이 비어 있는 경우가 흔하다. gpt-crawler는 Crawlee의 PlaywrightCrawler로 진짜 브라우저를 띄워 렌더링이 끝난 뒤의 화면을 읽기 때문에 이 문제를 원천적으로 피한다.

② 본문만 골라내지 않으면 메뉴·광고·푸터가 지식을 오염시킨다

페이지 전체 텍스트를 그대로 넣으면 내비게이션 메뉴, 배너, 저작권 문구 같은 반복되는 잡음이 매 페이지마다 끼어들어 지식 파일의 신호 대 잡음비를 떨어뜨린다. gpt-crawler는 CSS 셀렉터(또는 XPath)로 "본문 컨테이너 하나"만 지정하게 해, 그 안의 텍스트만 뽑아낸다.

③ 커스텀 GPT·Assistants 업로드에는 파일 크기·토큰 한도가 있다

ChatGPT나 Assistants API의 지식 파일 업로드에는 파일 하나당 크기 제한이 있다. 사이트가 커서 결과 JSON이 너무 커지면 업로드 자체가 실패한다. gpt-crawler는 maxFileSize(메가바이트)·maxTokens(토큰 수) 설정으로 결과를 자동으로 여러 파일로 쪼개 이 문제를 피해간다.

4전체 구조

레포 구조는 아주 단순하다. "어떻게 실행되는가"를 결정하는 진입점 파일 3개(main.ts·cli.ts·server.ts)와, "실제로 무슨 일을 하는가"를 담당하는 엔진 파일 2개(config.ts·core.ts)로 나뉜다. 어느 진입점으로 들어오든 결국 core.ts의 crawl()과 write() 두 함수를 순서대로 호출하는 것으로 수렴한다.

이 구조가 주는 실용적인 교훈은 "진입점(실행 방식)과 엔진(크롤링 로직)을 분리"했다는 점이다. CLI로 쓰든 API 서버로 쓰든 실제 크롤링·분할 로직은 core.ts 한 곳에만 있으니, 이 파일 하나만 이해하면 이 프로젝트의 8할을 이해한 셈이다. 다음 절에서 그 안을 그대로 뜯어본다.

5핵심 설계·동작 원리

src/core.ts 하나에 이 프로젝트의 실질적인 로직이 거의 다 들어있다. 크게 두 함수 — 크롤링을 실행하는 crawl()과 결과를 파일로 합치는 write() — 로 나뉜다. 대표 흐름 한 줄기를 처음부터 끝까지 손으로 따라가 보자.

① 크롤 시작 — 사이트맵인가, 단일 URL인가

crawl(config)는 가장 먼저 configSchema.parse(config)로 설정값을 검증한다(잘못된 타입이면 여기서 바로 에러). 그다음 config.url이 정규식 /sitemap.*\.xml$/에 걸리는지로 분기한다.

즉 url 하나로 "단일 시작점 크롤"과 "사이트맵 일괄 등록"을 모두 지원한다. sitemap.xml을 주면 enqueueLinks 없이도 사이트 전체 URL 목록을 한 번에 큐에 넣을 수 있어, 링크 구조가 복잡한 사이트에 특히 유용하다.

② 페이지 하나를 방문할 때 — requestHandler

PlaywrightCrawler에 등록된 requestHandler가 방문한 페이지마다 실행된다. 순서대로: (1) 제목을 읽고 진행 로그를 찍는다 → (2) config.selector가 있으면 그 요소가 나타날 때까지 기다린다(waitForSelector 또는 XPath면 waitForXPath) → (3) getPageHtml()로 텍스트를 뽑는다 → (4) pushData()로 storage/datasets/default/에 JSON 조각 하나를 저장한다 → (5) config.onVisitPage 콜백이 있으면 실행한다 → (6) enqueueLinks()로 match 패턴에 맞는 링크를 다음 크롤 대상 큐에 추가한다.

여기서 짚고 넘어가야 할 세부 하나. getPageHtml()은 이름과 달리 실제로는 HTML 마크업이 아니라 순수 텍스트를 반환한다.

// src/core.ts
export function getPageHtml(page: Page, selector = "body") {
  return page.evaluate((selector) => {
    if (selector.startsWith("/")) {
      // XPath: 일치하는 첫 요소의 textContent(태그 없는 순수 텍스트)
      const elements = document.evaluate(selector, document, null, XPathResult.ANY_TYPE, null);
      let result = elements.iterateNext();
      return result ? result.textContent || "" : "";
    } else {
      // CSS: 일치하는 첫 요소의 innerText(화면에 보이는 대로의 텍스트)
      const el = document.querySelector(selector) as HTMLElement | null;
      return el?.innerText || "";
    }
  }, selector);
}

결과 JSON에는 이 값이 html이라는 필드 이름으로 저장된다(pushData({ title, url, html })). 필드 이름은 "html"인데 내용물은 텍스트라는 이 불일치는 코드를 처음 읽는 사람이 가장 자주 헷갈리는 지점이라 함정·오해 방지에서 다시 짚는다.

③ 크롤링 범위 제어 — match / exclude / resourceExclusions / cookie

enqueueLinks({ globs: config.match, exclude: config.exclude ?? [] })가 "어디까지 따라갈지"를 결정한다. match는 glob 패턴(예: "https://example.com/docs/**") 문자열 하나 또는 배열을 받는다. exclude는 그 반대로, 매칭되더라도 크롤 대상에서 뺄 패턴이다.

preNavigationHooks(페이지 이동 전에 실행되는 훅)에서 두 가지가 더 일어난다. 하나는 config.cookie가 있으면 그 값을 페이지 컨텍스트에 쿠키로 심는 것(쿠키 동의 배너를 미리 넘기는 용도로 흔히 쓴다). 다른 하나는 config.resourceExclusions(이미지·폰트·비디오 등 확장자 목록)가 있으면 그 확장자로 끝나는 요청을 page.route(...).abort("aborted")로 아예 막아버리는 것 — 크롤링 속도를 올리고 대역폭을 아끼는 최적화다.

// src/core.ts write() 안의 addContentOrSplit (설명을 위해 정리)
const contentString = JSON.stringify(data);
const tokenCount = isWithinTokenLimit(contentString, config.maxTokens || Infinity);
// tokenCount: 이 항목 하나의 토큰 수(숫자) — 단, 이 항목 자체가 이미
// maxTokens를 넘으면 숫자 대신 false 가 돌아온다

if (typeof tokenCount === "number") {
  if (estimatedTokens + tokenCount > config.maxTokens) {
    if (currentResults.length > 0) await writeBatchToFile(); // 지금까지 모은 걸 파일로 확정
    estimatedTokens = Math.floor(tokenCount / 2); // 다음 파일의 시작 추정치(근사치)
    currentResults.push(data);
  } else {
    currentResults.push(data);
    estimatedTokens += tokenCount;
  }
}
// tokenCount 가 false 였다면 위 if 블록에 아예 들어가지 않는다
// → 이 항목은 currentResults 에 추가되지 않고 그대로 버려진다

currentSize += getStringByteSize(contentString);
if (currentSize > maxBytes) await writeBatchToFile(); // 용량 기준 분할(별도 트리거)