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

config.ts를 고쳐서 한 번 돌리고 끝내는 방식

1) git clone https://github.com/builderio/gpt-crawler → 2) npm i(이때 Playwright 브라우저도 함께 설치됨) → 3) 루트의 config.ts를 열어 url·match·selector·maxPagesToCrawl·outputFileName을 자신의 사이트에 맞게 수정 → 4) npm start 실행. 내부적으로는 main.ts가 defaultConfig를 그대로 읽어 crawl() → write() 순서로 실행하고, 루트에 output-1.json(또는 분할 시 -2, -3…)이 생성된다.

대화형 CLI (npm run start:cli)

npm run start:cli로 실행하면 cli.ts가 실행된다. --url·--match·--selector·--maxPagesToCrawl·--outputFileName 플래그로 값을 바로 넘길 수 있고, 필수값(url·match·selector)이 비어 있으면 inquirer가 터미널에서 하나씩 되물어 채워준다. config.ts를 편집하지 않고 반복 실행할 때 편하다.

Express API 서버 (npm run start:server)

npm run start:server로 서버를 띄운 뒤, POST /crawl에 config JSON을 body로 보내면 그 자리에서 크롤·분할까지 마친 결과 파일 내용을 응답으로 돌려받는다. /api-docs에서 Swagger로 API 명세를 바로 확인할 수 있다. 자체 서비스의 백엔드에서 "필요할 때마다 크롤을 트리거"하고 싶을 때 이 방식을 쓴다.

Docker / containerapp

기본 Dockerfile로 이미지를 빌드해 컨테이너 하나로 실행하거나, containerapp/ 폴더의 run.sh를 실행하면 아예 처음부터 Ubuntu + Docker + Node를 갖춘 이미지를 새로 빌드해, data/config.ts를 컨테이너 안에 복사해 넣고 크롤을 돌린 뒤 data/output.json으로 결과를 돌려준다. 로컬 Node.js 환경을 건드리고 싶지 않을 때 쓰는 방식이다.

output.json을 ChatGPT/Assistants에 업로드

ChatGPT의 "My GPTs → Create a GPT → Configure → Knowledge"에서 파일을 업로드하는 게 기본 경로다. OpenAI Assistants API는 2026-08-26에 종료가 확정돼 있어(2026-08-22 기준) 새로 올릴 곳으로는 권하지 않는다 — 후속은 Responses API다. 파일이 너무 크다는 오류가 나면 그제서야 되돌아가 config.ts에 maxFileSize나 maxTokens를 추가해 다시 크롤하는 게 README가 권하는 순서다.

· 회사·개인 문서 사이트 하나를 커스텀 GPT 지식으로 빠르게 옮기고 싶은 사람(Assistants API는 2026-08-26 종료)
· "웹 크롤링 → 셀렉터 추출 → 토큰 기준 파일 분할"이라는 패턴을 짧은 실제 코드로 배우고 싶은 초보 개발자
· Crawlee·Playwright를 처음 접하는데, 아주 얇은 실전 예제부터 읽고 싶은 사람

· 여러 사이트를 정기적으로 재크롤링하며 자동으로 최신 상태를 유지해야 하는 프로덕션 RAG 파이프라인 → Firecrawl·Crawl4AI 같은 RAG 특화 도구
· 크롤 큐·동시성·재시도 정책을 세밀하게 제어해야 하는 대규모 크롤 → Crawlee를 직접
· 대상 사이트가 로그인·CAPTCHA·강한 봇 차단을 쓰는 경우 → 이 저장소는 그런 회피 로직을 전혀 다루지 않는다

설정 파일과 검증 스키마의 역할 구분하기

목표: 루트의 config.ts는 실행할 값, src/config.ts는 허용할 값의 규칙이라는 차이를 이해한다.

1. package.json의 build 스크립트와 tsconfig.json의 outDir을 읽고, 빌드 후 생성된 CLI의 도움말을 확인한다.

npm run build
node dist/src/cli.js --help

2. src/main.ts에서 defaultConfig가 crawl()과 write()로 전달되는 순서를 따라간다.
3. 아래 명령으로 정상 설정과 잘못된 페이지 수를 비교한다. 크롤링 함수는 호출하지 않는다.

node --input-type=module -e '
import { strict as assert } from "node:assert";
import { configSchema } from "./dist/src/config.js";

const config = {
  url: "about:blank",
  match: "**",
  maxPagesToCrawl: 1,
  outputFileName: "lab.json"
};

assert.doesNotThrow(() => configSchema.parse(config));
assert.throws(() => configSchema.parse({
  ...config,
  maxPagesToCrawl: 0
}));
console.log("정상 설정 통과, 페이지 수 0 거부");
'

완료 기준: 두 검증이 모두 통과하고, maxPagesToCrawl이 양의 정수여야 하는 근거를 스키마에서 찾는다. CLI 도움말에서는 --match와 --maxPagesToCrawl을 구분하고, 겹치는 단축 플래그 대신 긴 이름을 사용한다.

같은 문서를 CSS와 XPath로 읽어 비교하기

목표: src/core.ts의 getPageHtml()이 선택 범위와 추출 방식에 따라 다른 텍스트를 돌려준다는 점을 확인한다.

1. 과제 1의 빌드를 마친 뒤 아래 명령을 실행한다. 브라우저에는 문자열로 만든 문서를 넣고, 페이지의 네트워크 요청은 모두 차단한다.
2. 기본 선택 범위, article, //article의 결과를 비교한다. 예제의 hidden 속성은 숨겨진 텍스트의 차이를 드러내기 위한 장치다.

node --input-type=module -e '
import { strict as assert } from "node:assert";
import { chromium } from "playwright";
import { getPageHtml } from "./dist/src/core.js";

const browser = await chromium.launch();
try {
  const page = await browser.newPage();
  await page.route("**/*", route => route.abort());
  await page.setContent(
    "<nav>메뉴</nav><article>본문<span hidden>숨김</span></article>"
  );

  const whole = await getPageHtml(page);
  const css = await getPageHtml(page, "article");
  const xpath = await getPageHtml(page, "//article");

  assert.ok(whole.includes("메뉴"));
  assert.equal(css.trim(), "본문");
  assert.equal(xpath, "본문숨김");
  console.log({ whole, css, xpath });
} finally {
  await browser.close();
}
'

완료 기준: 기본 범위에는 메뉴가 포함되고, CSS 결과에서는 숨겨진 글자가 빠지며, XPath 결과에는 포함된다. 이를 innerText와 textContent의 차이로 설명하고, 결과에 원본 태그가 남지 않는 것도 확인한다.

크롤링 없이 JSON 조각을 결과 파일로 합치기

목표: 수집 단계와 저장 단계를 분리해 write()의 입력 경로와 출력 이름을 확인한다.

1. src/core.ts에서 NO_CRAWL 조건과 storage/datasets/default/*.json 검색 부분을 읽는다.
2. 아래 명령으로 임시 작업 폴더에 페이지 조각 두 개를 만든다. process.chdir() 이후의 상대 경로는 그 임시 폴더를 기준으로 하므로 기존 수집 데이터와 섞이지 않는다.
3. NO_CRAWL=true로 실제 방문을 건너뛰고, 반환된 파일을 다시 읽어 입력과 출력의 URL 목록을 비교한다.

NO_CRAWL=true node --input-type=module -e '
import { strict as assert } from "node:assert";
import { mkdtemp, mkdir, writeFile, readFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { crawl, write } from "./dist/src/core.js";

const dir = await mkdtemp(join(tmpdir(), "gpt-crawler-lab-"));
process.chdir(dir);
await mkdir("storage/datasets/default", { recursive: true });

const pages = [
  { title: "첫 문서", url: "about:blank#one", html: "짧은 설명." },
  { title: "둘째 문서", url: "about:blank#two", html: "추가 설명." }
];
for (const [i, page] of pages.entries()) {
  await writeFile(
    "storage/datasets/default/" + (i + 1) + ".json",
    JSON.stringify(page)
  );
}

const config = {
  url: "about:blank",
  match: "**",
  maxPagesToCrawl: 2,
  outputFileName: "lab.json"
};
await crawl(config);
const path = await write(config);
const rows = JSON.parse(await readFile(path, "utf8"));

assert.equal(path, "lab-1.json");
assert.deepEqual(
  rows.map(row => row.url).sort(),
  pages.map(page => page.url).sort()
);
console.log(dir, path, rows.length);
'

완료 기준: 출력된 임시 폴더에 lab-1.json이 생성되고 두 문서의 URL이 모두 보존된다. outputFileName을 lab.json으로 지정해도 실제 파일에는 번호가 붙는 이유를 nextFileName()에서 찾는다.

토큰 한도 초과로 문서가 빠지는 조건 재현하기

목표: 실행 성공과 데이터 보존을 별도로 검증하는 방법을 익힌다. 과제 3의 명령을 바탕으로 같은 임시 폴더 생성 절차를 매번 새로 수행한다.

1. 과제 3 코드에서 둘째 문서의 html을 "설명 ".repeat(1000)으로 바꾸고, config에 maxTokens: 64를 추가한다. 이 값은 누락 조건을 관찰하기 위한 실습용 한도다.
2. 다음 import를 코드 맨 위에 추가한다.

import { isWithinTokenLimit } from "gpt-tokenizer";

3. await crawl(config) 앞에 아래 검증을 넣는다. 첫 문서는 한도 안에 있고 둘째 문서는 한도를 넘는 입력인지 먼저 확인한다.

assert.equal(
  typeof isWithinTokenLimit(JSON.stringify(pages[0]), config.maxTokens),
  "number"
);
assert.equal(
  isWithinTokenLimit(JSON.stringify(pages[1]), config.maxTokens),
  false
);

4. 과제 3의 URL 목록 비교 검증을 아래 코드로 바꾼 뒤, 같은 NO_CRAWL=true node --input-type=module -e 방식으로 전체 코드를 다시 실행한다.

assert.equal(rows.length, 1);
assert.equal(rows[0].url, pages[0].url);
console.log("누락 재현:", pages[1].url);

완료 기준: 입력은 두 문서인데 출력에는 짧은 문서 하나만 남는 조건을 재현하고, addContentOrSplit()에서 false를 받은 항목이 추가되지 않는 분기를 찾는다. 이어서 “한도 초과 항목을 나누거나 오류로 알린다”는 개선 규칙과, 입력 URL이 설명 없이 사라지면 실패하는 회귀 테스트의 조건을 적는다.