twitter-post

name	twitter-post
description	Post tweets to Twitter/X via the official API v2 (OAuth 1.0a). Use when the user asks to tweet, post to Twitter/X, send a thread, reply to a tweet, or quote tweet. Supports single tweets, threads, replies, and quote tweets with automatic character weight validation.

Twitter Post

Post tweets via the official Twitter/X API v2 using OAuth 1.0a authentication.

Prerequisites

Four environment variables must be set. Obtain them from developer.x.com:

TWITTER_CONSUMER_KEY=<API Key>
TWITTER_CONSUMER_SECRET=<API Key Secret>
TWITTER_ACCESS_TOKEN=<Access Token>
TWITTER_ACCESS_TOKEN_SECRET=<Access Token Secret>

Optional:

• HTTPS_PROXY — HTTP proxy URL (e.g. http://127.0.0.1:7897) for regions that need it
• TWITTER_DRY_RUN=1 — validate and print without posting

Setup

Store credentials as env vars. Recommended: add to the OpenClaw instance config or export in shell profile. Never hardcode keys in SKILL.md or scripts.

If the user hasn't set up OAuth yet, guide them:

1. Go to developer.x.com → Dashboard → Create App
2. Set App permissions to Read and Write
3. Go to Keys and tokens tab
4. Copy API Key, API Key Secret
5. Generate Access Token and Access Token Secret (ensure Read+Write scope)
6. If the portal only shows Read, use PIN-based OAuth flow:
   • Call POST /oauth/request_token with oauth_callback=oob
   • User opens https://api.twitter.com/oauth/authorize?oauth_token=<token>
   • User provides the PIN code
   • Call POST /oauth/access_token with the PIN as oauth_verifier

Usage

All commands via exec. Script path: scripts/tweet.js (relative to this skill directory).

Single tweet

node scripts/tweet.js "Your tweet content here"

Reply to a tweet

node scripts/tweet.js --reply-to 1234567890 "Reply text"

Quote tweet

node scripts/tweet.js --quote 1234567890 "Your commentary"

Thread (multiple tweets)

node scripts/tweet.js --thread "First tweet" "Second tweet" "Third tweet"

Output

JSON to stdout:

{"ok":true,"id":"123456789","url":"https://x.com/i/status/123456789","remaining":"99","limit":"100"}

On error: {"ok":false,"error":"..."}

Character Limits

• Max 280 weighted characters per tweet
• CJK characters (Chinese/Japanese/Korean) count as 2 each
• URLs count as 23 each regardless of length
• Script auto-validates before posting; rejects if over limit

Rate Limits

• 100 tweets / 15 min per user (OAuth 1.0a)
• 3,000 tweets / month on Basic plan ($200/mo)
• Check remaining field in output to monitor quota

Tips

• For content from Notion/database: fetch the text first, then pipe to tweet.js
• For cron-based auto-posting: use exec with env vars set, parse JSON output to confirm success
• Thread mode posts sequentially; each tweet auto-replies to the previous one
• Combine --thread with --reply-to to attach a thread under an existing tweet