X（Twitter）API

通过 API v2 与 X 交互。纯 Python 标准库实现 —— 无任何外部依赖。

功能

公开数据（使用 Bearer Token）：

• 用户资料（简介、关注者数、推文数）
• 用户时间线（支持过滤：排除转发/回复）
• 对话线程（同一作者发布的自包含线程）
• 搜索近期推文（最近 7 天）
• 单条或批量推文查询（tweet lookup）
• 推文指标（点赞数、转发数、回复数）

用户上下文（OAuth 2.0）：

• 书签（Bookmarks）
• 已点赞推文（Liked tweets）
• 发布推文（Post tweets）

配置

参见 SETUP.md 获取凭据配置说明（Bearer Token + 可选 OAuth 2.0）。

使用方法

用户信息

# 获取用户资料（简介、关注者数、认证状态）
python3 {baseDir}/scripts/x.py user steipete
python3 {baseDir}/scripts/x.py user elonmusk

时间线

# 获取用户的近期推文
python3 {baseDir}/scripts/x.py timeline steipete --max 50

# 排除转发
python3 {baseDir}/scripts/x.py timeline steipete --max 100 --exclude retweets

# 同时排除转发和回复
python3 {baseDir}/scripts/x.py timeline steipete --max 100 --exclude retweets,replies

线程

# 获取对话线程（同一作者发布的自包含线程）
python3 {baseDir}/scripts/x.py thread https://x.com/steipete/status/123456
python3 {baseDir}/scripts/x.py thread 123456789

# 注意：仅搜索最近 7 天（近期搜索）。如需检索更早的线程，需使用全量归档搜索（full-archive search）。

搜索

# 搜索近期推文（最近 7 天）
python3 {baseDir}/scripts/x.py search "OpenClaw" --max 20
python3 {baseDir}/scripts/x.py search "from:steipete OpenAI" --max 50

# 支持高级搜索操作符（如 from:、to:、-filter:retweets 等）

推文查询（Tweet Lookup）

# 单条推文
python3 {baseDir}/scripts/x.py tweet 2025504475100614695
python3 {baseDir}/scripts/x.py tweet https://x.com/steipete/status/2025504475100614695

# 多条推文（批量查询）
python3 {baseDir}/scripts/x.py tweets 123456 789012 345678

书签（需 OAuth）

# 一次性授权设置
python3 {baseDir}/scripts/x.py auth

# 获取您的书签
python3 {baseDir}/scripts/x.py bookmarks --max 100

已点赞推文（需 OAuth）

# 获取某用户已点赞的推文（需 OAuth）
python3 {baseDir}/scripts/x.py likes steipete --max 50

发布推文（需 OAuth）

# 发布一条推文
python3 {baseDir}/scripts/x.py post "Hello from OpenClaw! 🦞"

# 注意：API 强制执行 280 字符限制

输出格式

所有命令均输出简洁、易读的文本：

👤 Peter Steinberger 🦞 (@steipete)
   ID: 25401953
   Bio: Polyagentmorous ClawFather...
   👥 382,854 followers · 2,241 following · 135,096 tweets
   https://x.com/steipete

🐦 @VictorKnox99 I think my stance on using AI here is pretty clear.
   📅 2026-02-22 09:34:33
   ❤️  5  🔁 0  💬 0
   https://x.com/steipete/status/2025504475100614695

常见使用场景

研究用户活动：

# 获取某人近期关于特定主题的观点
python3 {baseDir}/scripts/x.py timeline steipete --max 100 --exclude retweets | grep -i openai

监控讨论：

# 搜索 OpenClaw 相关提及
python3 {baseDir}/scripts/x.py search "OpenClaw" --max 100

提取线程：

# 获取完整线程用于分析
python3 {baseDir}/scripts/x.py thread  > thread.txt

归档书签：

# 将书签导出至文件
python3 {baseDir}/scripts/x.py bookmarks --max 100 > bookmarks.txt

速率限制（Rate Limits）

X API 在每 15 分钟窗口内强制执行速率限制：

响应头字段（Headers in responses）：

• x-rate-limit-limit — 允许的最大请求数
• x-rate-limit-remaining — 当前窗口内剩余请求数
• x-rate-limit-reset — 速率限制重置时间（Unix 时间戳）

设计建议：

• 本地缓存结果（去重有助于节省配额，但不保证完全一致）
• 请求之间添加延迟（避免触发限频）
• 尽可能使用批量端点（例如 tweets 批量查询多条推文 ID）

计费与成本

按用量付费模型（Pay-per-usage model）：

• 在开发者控制台（Developer Console）中购买信用额度（credits）
• 按返回的唯一推文/用户数量计费
• 24 小时去重（24-hour deduplication） — 同一推文在 UTC 日内被多次获取，仅计费一次
• 可设置消费上限以控制成本
• 监控用量：使用 /2/usage/tweets 端点或控制台界面

计费项包括：

• 推文查询（Tweet lookups）
• 搜索结果（Search results）
• 时间线请求（Timeline requests）
• 书签获取（Bookmarks retrieval）

不计费项包括：

• 失败请求（4xx / 5xx 错误）
• 在 24 小时 UTC 窗口内重复获取同一推文（已去重）

详细定价信息请参阅 references/pricing.md。

搜索操作符

X API 搜索支持以下高级操作符：

示例：

# 来自已验证用户的 OpenClaw 相关推文，且排除转发
python3 {baseDir}/scripts/x.py search "OpenClaw filter:verified -filter:retweets" --max 50

限制条件

仅支持近期搜索：

• search 和 thread 命令仅覆盖最近 7 天
• 全量归档搜索（Full-archive search）需 Pro 套餐（$5,000/月）或按用量付费

书签/已点赞推文需 OAuth：

• 仅使用 Bearer Token 无法访问私有用户数据
• 需 OAuth 2.0 用户上下文（一次性配置）

无“稍后观看”（Watch Later）等效功能：

• X API 不暴露“Watch Later”或类似列表
• 可使用书签（Bookmarks）作为替代方案

速率限制依然生效：

• 按用量付费模式取消了月度配额上限，但每 15 分钟窗口的速率限制仍存在
• 建议采用指数退避（exponential backoff）策略进行重试设计

故障排查

403 Forbidden：

• 检查凭据文件是否存在，且其中 bearer_token 有效
• 确认所调用端点是否需要 OAuth（如书签、已点赞推文、发推等必须使用 OAuth）

429 Too Many Requests：

• 已达速率限制 — 请等待至 x-rate-limit-reset 指定的时间再重试
• 减小 --max 参数值
• 在请求之间添加延迟

未返回结果：

• 近期搜索仅覆盖 7 天 — 线程/搜索可能遗漏更早内容
• 目标用户可能无推文，或其隐私设置阻止访问

认证错误（OAuth）：

• 确保 oauth2.json 中包含正确的 client_id 和 client_secret
• 重新运行 x.py auth 刷新令牌
• 检查开发者门户（Developer Portal）中配置的作用域（scopes）是否匹配所需权限

备注

• 纯标准库（Pure stdlib） — 无 pip 依赖，仅使用 urllib + json
• 离线可用（Works offline） — 不缓存任何数据，始终获取最新内容
• 线程安全（Thread-safe） — CLI 无状态，支持并行调用
• 去重机制（Deduplication） — X API 在 24 小时 UTC 日内自动去重（软性保障）
• 输出编码（Output encoding） — UTF-8 编码，支持 emoji 和国际字符