name

x-twitter-scraper

description

Use when the user needs public X/Twitter data without login: user profile lookup, recent timeline up to about 20 tweets, full tweet content including Note Tweet long-form, pinned tweet lookup, or JSON export. Trigger for check Twitter/X user, view recent tweets, scrape public X profile, and fetch a specific tweet. Not for full history timelines, authenticated/private content, or advanced search requiring login.

x-twitter-scraper 1.0.0

首次使用

首次使用前请运行依赖检测脚本：

bash scripts/setup.sh

Agent 会在首次触发时自动执行此脚本，通常无需手动操作。

通过 X GraphQL API + guest token，无需账号抓取 X/Twitter 公开数据。

⚠️ Gotchas

遇到问题先看这里。

⚠️ 沙箱必须走代理 → 沙箱直连 x.com 可能超时。使用前设置环境变量 X_PROXY（如 export X_PROXY=http://your-proxy:3128），未设置时脚本直连。

⚠️ 普通 UA 获取 guest token 返回 403 → 必须用 Android UA（TwitterAndroid/10.21.0-release.0），脚本已处理，不要修改 UA。

⚠️ Timeline 只返回最近约 20 条 → X GraphQL API 对未登录用户限制 timeline 深度，无法翻页拉取历史。完整历史、受限内容或登录态能力不属于本 skill 范围。

⚠️ 搜索（search 命令）guest token 下几乎无效 → SearchTimeline endpoint 对 guest token 高度受限，通常返回空或 404。不要请求或使用 X 登录 cookie、auth token、ct0 或用户浏览器登录态；改用公开 web search 降级。

⚠️ GraphQL query ID 可能过期 → X 会不定期更新 endpoint 的 query ID。失效时删除 scripts/.x_config.json，升级 twikit（pip install -U twikit），再重新运行 bash scripts/setup.sh 即可自动提取最新值。

⚠️ 置顶推文不在 timeline 里 → 需用 profile 接口取 pinned_tweet_ids_str，再用 tweet 命令逐条获取。

🛑 Hard Stop

同一工具调用失败超过 3 次，立即停止，列出失败原因，标记 "需要人工介入"，等待人工确认。

场景映射表

用户说	执行命令
查 @_LuoFuli 的 X 主页	`python3 x_scraper.py profile _LuoFuli`
看 @某人最新推文	`python3 x_scraper.py timeline 某人 --count 10`
获取这条推文的完整内容	`python3 x_scraper.py tweet <tweet_id>`
查置顶推文	先 `profile` 取 pinned_tweet_ids，再 `tweet <id>`
搜推特关键词	guest search 通常受限；改用公开 web search，不请求登录态
拿 JSON 数据做后续处理	任意命令加 `--json` 参数

快速开始

SKILL_DIR=$(find ~/.openclaw/skills ~/.openclaw/workspace/skills -name "x_scraper.py" 2>/dev/null | head -1 | xargs dirname)
pip install httpx -q

# 查用户
python3 $SKILL_DIR/x_scraper.py profile _LuoFuli

# 查最新推文
python3 $SKILL_DIR/x_scraper.py timeline elonmusk --count 5

# 查单条完整推文（含长文）
python3 $SKILL_DIR/x_scraper.py tweet 2034379957913129140

# JSON 输出
python3 $SKILL_DIR/x_scraper.py profile _LuoFuli --json

GraphQL Endpoints 参考

Query IDs 由 setup.sh 运行时生成到 scripts/.x_config.json。支持的 endpoints：

用户信息（by handle / by ID）
用户 Timeline / 推文+回复
单条推文（含 Note Tweet 长文）
搜索 Timeline
关注者 / 正在关注

更新方式（query ID 过期时）：

rm scripts/.x_config.json
pip install -U twikit
bash scripts/setup.sh

技术原理

POST api.twitter.com/1.1/guest/activate.json（Android UA）→ 获取 guest token
GET x.com/i/api/graphql/<query_id>/<endpoint>（带 guest token + Bearer）→ 拿数据
必须走上游代理（沙箱直连超时）

依赖：httpx（pip install httpx）

Changelog

1.0.0

Initial release. Guest token approach for scraping public X/Twitter data without login.