Back to Details

twitter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Twitter/X API Skill

Twitter/X API 技能

Interact with X (Twitter) via API v2 for reading, posting, replying, DMs, search, and analytics.
通过API v2与X (Twitter)交互，实现读取、发布、回复、私信、搜索和分析功能。

Setup

配置

Credentials

凭证

Store credentials in environment variables or 
~/.config/twitter/credentials.json
:
bash
export TWITTER_API_KEY="your-api-key"
export TWITTER_API_SECRET="your-api-secret"
export TWITTER_ACCESS_TOKEN="your-access-token"
export TWITTER_ACCESS_SECRET="your-access-secret"
export TWITTER_BEARER_TOKEN="your-bearer-token"  # For read-only operations
Or create credentials file:
bash
mkdir -p ~/.config/twitter
cat > ~/.config/twitter/credentials.json << 'EOF'
{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "access_token": "your-access-token",
  "access_secret": "your-access-secret",
  "bearer_token": "your-bearer-token"
}
EOF
chmod 600 ~/.config/twitter/credentials.json
将凭证存储在环境变量或 
~/.config/twitter/credentials.json
中：
bash
export TWITTER_API_KEY="your-api-key"
export TWITTER_API_SECRET="your-api-secret"
export TWITTER_ACCESS_TOKEN="your-access-token"
export TWITTER_ACCESS_SECRET="your-access-secret"
export TWITTER_BEARER_TOKEN="your-bearer-token"  # 用于只读操作
或者创建凭证文件：
bash
mkdir -p ~/.config/twitter
cat > ~/.config/twitter/credentials.json << 'EOF'
{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "access_token": "your-access-token",
  "access_secret": "your-access-secret",
  "bearer_token": "your-bearer-token"
}
EOF
chmod 600 ~/.config/twitter/credentials.json

Install Dependencies

安装依赖

bash
pip install tweepy
bash
pip install tweepy

Quick Reference

快速参考

TaskCommand
Post tweet
{baseDir}/scripts/tweet.py post "text"
Post with image
{baseDir}/scripts/tweet.py post "text" --media image.png
Reply
{baseDir}/scripts/tweet.py reply TWEET_ID "text"
Thread
{baseDir}/scripts/tweet.py thread "tweet1" "tweet2" ...
Get timeline
{baseDir}/scripts/tweet.py timeline [--count 20]
Get mentions
{baseDir}/scripts/tweet.py mentions [--count 20]
Get DMs
{baseDir}/scripts/tweet.py dms [--count 20]
Send DM
{baseDir}/scripts/tweet.py dm USERNAME "message"
Search
{baseDir}/scripts/tweet.py search "query" [--count 20]
User info
{baseDir}/scripts/tweet.py user USERNAME
Tweet info
{baseDir}/scripts/tweet.py show TWEET_ID
Analytics
{baseDir}/scripts/tweet.py analytics TWEET_ID
任务命令
发布推文
{baseDir}/scripts/tweet.py post "text"
带图发布
{baseDir}/scripts/tweet.py post "text" --media image.png
回复推文
{baseDir}/scripts/tweet.py reply TWEET_ID "text"
发布推文串
{baseDir}/scripts/tweet.py thread "tweet1" "tweet2" ...
获取时间线
{baseDir}/scripts/tweet.py timeline [--count 20]
获取提及通知
{baseDir}/scripts/tweet.py mentions [--count 20]
获取私信
{baseDir}/scripts/tweet.py dms [--count 20]
发送私信
{baseDir}/scripts/tweet.py dm USERNAME "message"
搜索
{baseDir}/scripts/tweet.py search "query" [--count 20]
获取用户信息
{baseDir}/scripts/tweet.py user USERNAME
获取推文信息
{baseDir}/scripts/tweet.py show TWEET_ID
查看分析数据
{baseDir}/scripts/tweet.py analytics TWEET_ID

Scripts

脚本

tweet.py

tweet.py

Main script for all Twitter operations. Run with 
--help
for details:
bash
{baseDir}/scripts/tweet.py --help
{baseDir}/scripts/tweet.py post --help
处理所有Twitter操作的主脚本，运行时添加 
--help
查看详情：
bash
{baseDir}/scripts/tweet.py --help
{baseDir}/scripts/tweet.py post --help

Common Workflows

常用工作流

Post a simple tweet:
bash
{baseDir}/scripts/tweet.py post "Hello, world!"
Post with image:
bash
{baseDir}/scripts/tweet.py post "Check this out!" --media photo.png
{baseDir}/scripts/tweet.py post "Multiple images" --media img1.png --media img2.png
Reply to a tweet:
bash
{baseDir}/scripts/tweet.py reply 1234567890 "Great point!"
Post a thread:
bash
{baseDir}/scripts/tweet.py thread \
  "First tweet in thread" \
  "Second tweet" \
  "Third tweet"
Read your mentions:
bash
{baseDir}/scripts/tweet.py mentions --count 50
Search for tweets:
bash
{baseDir}/scripts/tweet.py search "openclaw agent" --count 20
{baseDir}/scripts/tweet.py search "#AI lang:en" --count 20
Get user info:
bash
{baseDir}/scripts/tweet.py user elonmusk
Send a DM:
bash
{baseDir}/scripts/tweet.py dm username "Hello from OpenClaw!"
View tweet analytics:
bash
{baseDir}/scripts/tweet.py analytics 1234567890
发布一条简单推文：
bash
{baseDir}/scripts/tweet.py post "Hello, world!"
带图发布推文：
bash
{baseDir}/scripts/tweet.py post "Check this out!" --media photo.png
{baseDir}/scripts/tweet.py post "Multiple images" --media img1.png --media img2.png
回复一条推文：
bash
{baseDir}/scripts/tweet.py reply 1234567890 "Great point!"
发布推文串：
bash
{baseDir}/scripts/tweet.py thread \
  "First tweet in thread" \
  "Second tweet" \
  "Third tweet"
读取提及通知：
bash
{baseDir}/scripts/tweet.py mentions --count 50
搜索推文：
bash
{baseDir}/scripts/tweet.py search "openclaw agent" --count 20
{baseDir}/scripts/tweet.py search "#AI lang:en" --count 20
获取用户信息：
bash
{baseDir}/scripts/tweet.py user elonmusk
发送私信：
bash
{baseDir}/scripts/tweet.py dm username "Hello from OpenClaw!"
查看推文分析数据：
bash
{baseDir}/scripts/tweet.py analytics 1234567890

API Tiers & Limits

API层级与限制

TierCostReadWriteSearch
Free$0Limited--
Basic$100/mo10k/mo1.5k/mo50/mo
Pro$5000/mo1M/mo300k/mo500/mo
Free tier can only post tweets (no read access to timeline/mentions). Basic tier required for reading mentions, timeline, and search. Write-only operations work on free tier.
See 
{baseDir}/references/api-limits.md
for detailed rate limits.
层级费用读取额度写入额度搜索额度
免费版$0有限额度--
基础版$100/月1万次/月1500次/月50次/月
专业版$5000/月100万次/月30万次/月500次/月
免费层级仅可发布推文（无时间线/提及的读取权限）。 基础层级是读取提及、时间线和搜索功能的必要条件。 仅写入操作可在免费层级正常使用。
查看 
{baseDir}/references/api-limits.md
获取详细的速率限制信息。

Error Handling

错误处理

Common errors:
ErrorCauseSolution
403 ForbiddenInsufficient tierUpgrade API tier or check endpoint access
429 Too Many RequestsRate limit hitWait and retry; check rate limit headers
401 UnauthorizedInvalid credentialsVerify API keys and tokens
404 Not FoundTweet/user deletedHandle gracefully, inform user
422 UnprocessableDuplicate tweetWait before posting same content
常见错误：
错误原因解决方案
403 禁止访问层级权限不足升级API层级或检查端点访问权限
429 请求过多达到速率限制等待后重试，检查速率限制响应头
401 未授权凭证无效验证API密钥和令牌是否正确
404 未找到推文/用户已删除优雅处理异常，告知用户
422 无法处理请求推文内容重复间隔一段时间后再发布相同内容

Notes

注意事项

  • Rate limits: X API has strict rate limits. Scripts include retry logic.
  • Media uploads: Images must be <5MB (PNG/JPG) or <15MB (GIF). Videos <512MB.
  • Character limit: 280 characters per tweet. Threads for longer content.
  • DMs: Require OAuth 1.0a user context (not Bearer token).
  • Search operators: 
    {baseDir}/references/search-operators.md
    for advanced queries.
  • 速率限制：X API有严格的速率限制，脚本内置重试逻辑。
  • 媒体上传：图片大小必须小于5MB（PNG/JPG）或小于15MB（GIF），视频大小小于512MB。
  • 字符限制：每条推文最多280字符，长内容可使用推文串发布。
  • 私信：需要OAuth 1.0a用户上下文（不可使用Bearer token）。
  • 搜索运算符：查看 
    {baseDir}/references/search-operators.md
    了解高级查询语法。

Related Files

相关文件

  • {baseDir}/scripts/tweet.py
    - Main CLI for all operations
  • {baseDir}/references/api-limits.md
    - Detailed rate limits by endpoint
  • {baseDir}/references/search-operators.md
    - Twitter search syntax
  • {baseDir}/scripts/tweet.py
    - 处理所有操作的主CLI工具
  • {baseDir}/references/api-limits.md
    - 各端点详细速率限制说明
  • {baseDir}/references/search-operators.md
    - Twitter搜索语法说明