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

快速参考

Task	Command
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

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层级与限制

Tier	Cost	Read	Write	Search
Free	$0	Limited	-	-
Basic	$100/mo	10k/mo	1.5k/mo	50/mo
Pro	$5000/mo	1M/mo	300k/mo	500/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:

Error	Cause	Solution
403 Forbidden	Insufficient tier	Upgrade API tier or check endpoint access
429 Too Many Requests	Rate limit hit	Wait and retry; check rate limit headers
401 Unauthorized	Invalid credentials	Verify API keys and tokens
404 Not Found	Tweet/user deleted	Handle gracefully, inform user
422 Unprocessable	Duplicate tweet	Wait 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
```
了解高级查询语法。

twitter

Original

Translation

Twitter/X API Skill

Twitter/X API 技能

Setup

配置

Credentials

凭证

Install Dependencies

安装依赖

Quick Reference

快速参考

Scripts

脚本

tweet.py

tweet.py

Common Workflows

常用工作流

API Tiers & Limits

API层级与限制

Error Handling

错误处理

Notes

注意事项

Related Files

相关文件