AI 튜토리얼

Playwright로 비공개 방식의 API 없는 X 스크래퍼 만들기

API 키나 타사 서비스 없이 공개 X 검색 결과, 타임라인, 게시물 답글을 JSON, JSONL, CSV 또는 Markdown으로 내보내는 셀프 호스팅 Node.js 및 Playwright CLI x-scraper-no-api의 설치와 사용 방법을 알아보세요.

2026년 9월 26일약 10분 소요

x-scraper-no-api의 기능

x-scraper-no-api는 로컬에서 인증된 Chromium 브라우저를 공개 X 콘텐츠용 데이터 파이프라인으로 전환합니다. 한 번 수동으로 로그인하면 명령줄 도구가 검색 결과, 공개 타임라인, 공개 답글이 포함된 게시물을 수집할 수 있습니다.

결과는 json, jsonl, csv 또는 md 형식으로 사용자의 컴퓨터에 직접 저장됩니다. 이 프로젝트는 X API 키, 호스팅 스크레이퍼 서비스, 프록시 또는 제3자 릴레이를 사용하지 않습니다.

주요 기능

API 키 또는 개발자 계정 불필요: 공식 API 요금제 대신 자신의 브라우저 세션을 사용합니다.
수동 인증: 직접 로그인하며, 도구가 비밀번호나 2단계 인증 코드를 처리하지 않습니다.
세션 유지: 브라우저 프로필이 ~/.xscraper/에 저장되므로 이후 실행은 헤드리스 방식으로 진행할 수 있습니다.
고급 X 검색: from:, since:, until:, min_faves:, filter:media, lang: 등의 연산자를 사용할 수 있습니다.
LLM에 적합한 출력: Markdown은 토큰을 효율적으로 사용하는 AI 에이전트 컨텍스트를 위해 설계되었으며, JSON, JSONL, CSV는 프로그래밍 방식의 워크플로를 지원합니다.
견고한 파싱: 스크레이퍼는 취약한 HTML 클래스 이름에 의존하지 않고 X 프런트엔드가 전송하는 구조화된 GraphQL 데이터를 수집합니다.
적절한 제한: 실행 시 사람과 유사한 간격, 엄격한 항목 수 제한, X가 과부하 신호를 보낼 때의 자동 백오프를 적용합니다.
에이전트 지원: 저장소에는 OpenClaw, Hermes 및 CLI를 지원하는 기타 에이전트용 Skill이 포함되어 있습니다.

설치 및 최초 설정

1. macOS 빌드 도구 설치

macOS에서는 네이티브 종속성이 필요할 수 있으므로 Xcode Command Line Tools를 설치합니다.

xcode-select --install

2. Node.js 설치

공식 설치 프로그램이나 버전 관리자를 사용해 Node.js 18 이상을 설치합니다. 이 프로젝트에는 Node.js 18 이상이 필요합니다. 시작하려면 Node.js 다운로드 페이지를 방문하세요.

3. GitHub에서 스크레이퍼 설치

작업 디렉터리를 만들고 해당 디렉터리로 이동한 다음 저장소에서 패키지를 직접 설치합니다.

mkdir -p 'xscraper' && cd 'xscraper' && npm install github:JoinArtisanVent/x-scraper-no-api

4. Playwright용 Chromium 설치

Playwright에서 사용하는 Chromium 브라우저를 다운로드합니다.

npx playwright install chromium

5. 수동 로그인

최초 1회 로그인 절차를 시작합니다.

npx xscraper login

실제 브라우저 창이 열립니다. 필요한 2단계 인증을 포함해 X에 직접 로그인하세요. 도구는 생성된 브라우저 세션을 ~/.xscraper/에 로컬로 저장합니다. 사용자의 인증 정보를 수신하거나 처리하지 않습니다.

검색에 사용할 계정은 신중하게 선택하세요. 이 도구는 공개 게시물만 지원하며 보호된 계정, 쪽지 또는 제한된 콘텐츠는 지원하지 않습니다.

기본 사용법

고급 연산자로 X 검색

search 명령에 완전한 X 검색 표현식을 전달합니다. 다음 예시는 특정 날짜 이후 OpenAI가 작성한 게시물 중 좋아요가 500개 이상인 게시물을 찾아 Markdown으로 반환합니다.

xscraper search "from:openai since:2026-01-01 min_faves:500" --limit 50 --format md

이 도구는 계정 필터, 날짜 범위, 언어 필터, 미디어 필터, 참여도 기준을 포함한 X의 고급 검색 구문을 지원합니다.

공개 타임라인 내보내기

공개 사용자 이름과 함께 timeline을 사용합니다. 다음 예시는 CSV 출력을 파일에 저장합니다.

xscraper timeline @nasa --limit 100 --format csv -o nasa.csv

게시물과 공개 답글 수집

X 게시물 URL과 함께 tweet 명령을 사용합니다.

xscraper tweet https://x.com/nasa/status/1846987139428634858 --format json

출력 형식 및 명령 옵션

--limit <n>은 최대 항목 수를 설정합니다. 기본값은 50이며 최대 제한은 200입니다.
--format은 json, jsonl, csv 또는 md를 선택합니다. Markdown은 LLM 워크플로에 실용적인 선택입니다.
-o <file>은 표준 출력 대신 파일에 출력을 저장합니다.
--headed는 브라우저를 표시된 상태로 유지하므로 처리 과정을 확인하고 문제를 해결할 수 있습니다.

JSON 레코드에는 게시물 ID, URL, 생성 시간, 텍스트, 언어, 작성자 정보, 참여도 지표, 해시태그, 미디어 및 스크랩 시간이 포함될 수 있습니다.

{
  "id": "1846987139428634858",
  "url": "https://x.com/nasa/status/1846987139428634858",
  "created_at": "Wed Oct 16 12:34:56 +0000 2026",
  "text": "Liftoff! …",
  "lang": "en",
  "author": { "username": "nasa", "name": "NASA", "verified": true },
  "metrics": { "replies": 1200, "reposts": 4800, "likes": 32000, "views": 1500000 },
  "hashtags": ["EuropaClipper"],
  "scraped_at": "2026-09-26T10:00:00.000Z"
}

AI 에이전트와 스크레이퍼 사용

저장소에는 skills/x-scraper-no-api/SKILL.md에 에이전트 Skill이 포함되어 있습니다. OpenClaw 또는 Hermes가 skills/ 디렉터리를 참조하도록 설정하거나, Skill 매니페스트를 에이전트에 적합한 skills 폴더에 복사할 수 있습니다.

사용자 지정 LLM 스크립트에서는 CLI를 하위 프로세스로 실행하고 Markdown 출력을 캡처합니다.

import subprocess

ctx = subprocess.run(
    ["xscraper", "search", "local-first software", "--limit", "50", "--format", "md"],
    capture_output=True,
    text=True,
    timeout=600,
).stdout

포함된 Skill은 공개 데이터만 사용하고, 제한을 작게 유지하며, 자격 증명을 절대 다루지 않고, 스크랩한 콘텐츠를 신뢰할 수 없는 입력으로 취급하는 안전 계약을 정의합니다.

안정적인 실행을 위한 고급 팁

제한을 집중적으로 설정하기

모든 실행은 설계상 최대 200개 항목으로 제한됩니다. 조사 및 에이전트 컨텍스트에는 하나의 대규모 수집 작업보다 적당한 제한을 둔 집중 검색 여러 번이 더 적합합니다.

프롬프트에는 Markdown 사용하기

대상이 LLM 프롬프트라면 --format md를 선택하세요. 이 형식은 토큰 효율을 고려해 설계되었으며 표준 출력에서 바로 캡처하거나 -o를 사용해 저장할 수 있습니다.

문제 해결 중에는 headed 모드 사용하기

브라우저의 작업을 확인해야 할 때 --headed를 추가하세요. 쿼리가 예상대로 작동하는 것을 확인한 후에는 플래그를 생략하여 일반 실행이 헤드리스로 동작하도록 하세요.

때로는 결과가 더 적을 수 있음

명령이 요청한 수보다 적은 항목을 반환한다면, 사용 가능한 타임라인이나 검색 결과가 단순히 소진되었을 수 있습니다. 이는 정상적인 상황이며 반드시 오류를 의미하지는 않습니다.

책임 있는 사용 제한 준수하기

이 프로젝트는 의도적으로 CAPTCHA 해결, 프록시 순환, 계정 풀링, 자격 증명 처리 및 속도 제한 우회를 피합니다. 실행 규모를 적절히 유지하고, 자동 페이싱 및 쿨다운이 작동하도록 하며, X 서비스 약관과 관련 법률을 준수하세요.

프로젝트 작동 방식

실제 Chromium 인스턴스가 사람의 사용 방식과 동일하게 X를 로드합니다. 스크래퍼는 X가 자체 프론트엔드로 보내는 GraphQL JSON을 수동적으로 캡처한 다음, 해당 데이터를 안정적인 출력 스키마로 정규화합니다. X의 내부 엔드포인트를 직접 호출하지 않으며 변경되는 HTML 클래스 이름에도 의존하지 않습니다.

주요 소스 파일은 다섯 가지 핵심 영역으로 구성되어 있습니다.

src/cli.js는 Commander 기반 CLI를 정의합니다.
src/session.js는 영구 Playwright 프로필과 수동 로그인을 관리합니다.
src/scraper.js는 GraphQL 응답을 가로채고 레코드를 정규화합니다.
src/ratelimit.js는 페이싱, 제한 및 백오프를 처리합니다.
src/output.js는 JSON, JSONL, CSV 및 Markdown을 작성합니다.

결론

x-scraper-no-api는 API 키, 트윗별 크레딧 또는 호스팅 중개 서비스 없이 공개 X 데이터를 수집할 수 있는 로컬 방식을 제공합니다. Node.js를 설치하고 한 번 수동으로 인증한 다음, CLI를 사용해 파일, 스크립트 또는 AI 에이전트 워크플로에 적합한 형식으로 집중 검색, 타임라인 및 공개 답글을 내보내세요. 사용량을 보수적으로 유지하고 수집한 데이터를 책임감 있게 다루세요.