Xây dựng trình quét X riêng tư, không cần API với Playwright

x-scraper-no-api thực hiện được gì

x-scraper-no-api biến trình duyệt Chromium đã xác thực cục bộ thành một quy trình dữ liệu cho nội dung công khai trên X. Sau khi bạn đăng nhập thủ công một lần, công cụ dòng lệnh có thể thu thập kết quả tìm kiếm, dòng thời gian công khai và một bài đăng cùng các lượt trả lời công khai.

Kết quả được ghi trực tiếp vào máy của bạn ở các định dạng json, jsonl, csv hoặc md. Dự án không sử dụng khóa API X, dịch vụ scraper lưu trữ, proxy hoặc bên trung gian của bên thứ ba.

Tính năng chính

• Không cần khóa API hoặc tài khoản nhà phát triển: sử dụng phiên trình duyệt của riêng bạn thay cho gói API chính thức.
• Xác thực thủ công: bạn tự đăng nhập và công cụ không xử lý mật khẩu hay mã xác thực hai yếu tố của bạn.
• Phiên cố định: hồ sơ trình duyệt được lưu trong ~/.xscraper/, vì vậy các lần chạy sau có thể hoạt động ở chế độ không giao diện.
• Tìm kiếm X nâng cao: sử dụng các toán tử như from:, since:, until:, min_faves:, filter:media và lang:.
• Đầu ra sẵn sàng cho LLM: Markdown được thiết kế để phù hợp với ngữ cảnh tác nhân AI và tiết kiệm token, trong khi JSON, JSONL và CSV hỗ trợ các quy trình lập trình.
• Phân tích cú pháp bền bỉ: scraper thu thập dữ liệu GraphQL có cấu trúc được gửi đến frontend của chính X thay vì phụ thuộc vào các tên lớp HTML dễ thay đổi.
• Giới hạn hợp lý: các lần chạy sử dụng nhịp độ giống người dùng, giới hạn cứng cho số mục và tự động giảm tốc khi X phát hiện áp lực truy cập.
• Hỗ trợ tác nhân: kho mã bao gồm Skill cho OpenClaw, Hermes và các tác nhân khác có khả năng sử dụng CLI.

Cài đặt và thiết lập lần đầu

1. Cài đặt công cụ build cho macOS

Trên macOS, hãy cài đặt Xcode Command Line Tools vì các dependency native có thể yêu cầu chúng.

xcode-select --install

2. Cài đặt Node.js

Cài đặt Node.js 18 trở lên bằng trình cài đặt chính thức hoặc trình quản lý phiên bản. Dự án yêu cầu Node.js 18 trở lên. Truy cập trang tải Node.js để bắt đầu.

3. Cài đặt scraper từ GitHub

Tạo một thư mục làm việc, chuyển vào thư mục đó và cài đặt package trực tiếp từ kho mã:

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

4. Cài đặt Chromium cho Playwright

Tải trình duyệt Chromium được Playwright sử dụng:

npx playwright install chromium

5. Đăng nhập thủ công

Bắt đầu quy trình đăng nhập một lần:

npx xscraper login

Một cửa sổ trình duyệt thực sẽ mở ra. Hãy tự đăng nhập vào X, bao gồm mọi bước xác thực hai yếu tố cần thiết. Công cụ lưu phiên trình duyệt thu được cục bộ trong ~/.xscraper/. Công cụ không nhận hoặc xử lý thông tin đăng nhập của bạn.

Hãy sử dụng tài khoản X mà bạn cảm thấy thoải mái khi dùng để duyệt nội dung. Công cụ chỉ hỗ trợ các bài đăng công khai và không hỗ trợ tài khoản được bảo vệ, tin nhắn trực tiếp hoặc nội dung bị hạn chế.

Cách sử dụng cơ bản

Tìm kiếm X bằng toán tử nâng cao

Truyền một biểu thức tìm kiếm X hoàn chỉnh cho lệnh search. Ví dụ này tìm các bài đăng từ OpenAI sau một ngày nhất định, có ít nhất 500 lượt thích và trả về Markdown:

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

Công cụ hỗ trợ cú pháp tìm kiếm nâng cao của X, bao gồm bộ lọc tài khoản, khoảng thời gian, ngôn ngữ, phương tiện và ngưỡng tương tác.

Yêu cầu tab Latest

Kết quả tìm kiếm thường sử dụng hành vi tìm kiếm mặc định. Thêm --latest khi bạn muốn dùng tab Latest:

xscraper search "ai agents" --latest --limit 25

Xuất dòng thời gian công khai

Sử dụng timeline với tên người dùng công khai. Ví dụ này ghi đầu ra CSV vào một tệp:

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

Thu thập một bài đăng và các lượt trả lời công khai

Sử dụng lệnh tweet với URL bài đăng X:

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

Định dạng đầu ra và tùy chọn lệnh

• --limit <n> đặt số mục tối đa. Mặc định là 50 và giới hạn cứng là 200.
• --format chọn json, jsonl, csv hoặc md. Markdown là lựa chọn thực tế cho các quy trình LLM.
• -o <file> ghi đầu ra vào một tệp thay vì đầu ra tiêu chuẩn.
• --headed giữ trình duyệt hiển thị để bạn có thể theo dõi quy trình và khắc phục sự cố.

Một bản ghi JSON có thể bao gồm ID bài đăng, URL, thời gian tạo, văn bản, ngôn ngữ, thông tin tác giả, chỉ số tương tác, hashtag, phương tiện và thời điểm scrape:

{
  "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"
}

Sử dụng scraper với các tác nhân AI

Kho mã bao gồm một Skill cho tác nhân tại skills/x-scraper-no-api/SKILL.md. Bạn có thể trỏ OpenClaw hoặc Hermes đến thư mục skills/, hoặc sao chép manifest của Skill vào thư mục skills phù hợp của tác nhân.

Đối với một tập lệnh LLM tùy chỉnh, hãy chạy CLI dưới dạng quy trình con và thu thập đầu ra Markdown:

import subprocess

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

Skill đi kèm định nghĩa một hợp đồng an toàn: chỉ sử dụng dữ liệu công khai, giữ giới hạn ở mức nhỏ, không bao giờ xử lý thông tin xác thực và coi nội dung được thu thập là dữ liệu đầu vào không đáng tin cậy.

Mẹo nâng cao để chạy ổn định

Giữ giới hạn tập trung

Mỗi lần chạy được giới hạn tối đa 200 mục theo thiết kế. Đối với nghiên cứu và ngữ cảnh cho tác tử, nên thực hiện nhiều lượt tìm kiếm tập trung với giới hạn vừa phải thay vì một tác vụ thu thập lớn duy nhất.

Sử dụng Markdown cho lời nhắc

Khi đích đến là lời nhắc LLM, hãy chọn --format md. Định dạng này được thiết kế để tiết kiệm token và có thể được lấy trực tiếp từ đầu ra chuẩn hoặc lưu bằng -o.

Sử dụng chế độ hiển thị khi khắc phục sự cố

Thêm --headed khi bạn cần theo dõi trình duyệt hoạt động. Khi truy vấn đã hoạt động như mong đợi, hãy bỏ cờ này để các lượt chạy thông thường có thể hoạt động ở chế độ không giao diện.

Đôi khi có ít kết quả hơn

Nếu một lệnh trả về ít mục hơn yêu cầu, dòng thời gian hoặc kết quả tìm kiếm hiện có có thể đã được dùng hết. Đây là điều bình thường và không nhất thiết cho thấy có lỗi.

Tuân thủ các giới hạn sử dụng có trách nhiệm

Dự án cố ý không hỗ trợ giải CAPTCHA, luân phiên proxy, dùng chung tài khoản, xử lý thông tin xác thực hoặc né tránh giới hạn tốc độ. Hãy giữ các lượt chạy ở mức vừa phải, cho phép cơ chế điều tiết và thời gian nghỉ tự động hoạt động, đồng thời tuân thủ Điều khoản dịch vụ của X và luật hiện hành.

Cách dự án hoạt động

Một phiên bản Chromium thực tải X như cách người dùng thao tác. Trình thu thập thụ động ghi lại JSON GraphQL mà X gửi đến giao diện người dùng của chính mình, sau đó chuẩn hóa dữ liệu thành một lược đồ đầu ra ổn định. Công cụ không gọi trực tiếp các endpoint nội bộ của X và không phụ thuộc vào tên class HTML thường xuyên thay đổi.

Các tệp nguồn chính được tổ chức thành năm khu vực tập trung:

• src/cli.js định nghĩa CLI dựa trên Commander.
• src/session.js quản lý hồ sơ Playwright lâu dài và quy trình đăng nhập thủ công.
• src/scraper.js chặn các phản hồi GraphQL và chuẩn hóa bản ghi.
• src/ratelimit.js xử lý việc điều tiết, giới hạn và tăng thời gian chờ.
• src/output.js ghi dữ liệu JSON, JSONL, CSV và Markdown.

Kết luận

x-scraper-no-api cung cấp một cách cục bộ để thu thập dữ liệu X công khai mà không cần khóa API, tín dụng cho từng bài đăng hoặc dịch vụ trung gian lưu trữ. Hãy cài đặt Node.js, đăng nhập thủ công một lần và sử dụng CLI để xuất các lượt tìm kiếm tập trung, dòng thời gian và phản hồi công khai theo những định dạng phù hợp với tệp, tập lệnh hoặc quy trình làm việc của tác tử AI. Giữ mức sử dụng thận trọng và xử lý dữ liệu thu thập được một cách có trách nhiệm.