twitter-openclaw 🐦‍⬛

Interact with Twitter/X posts, timelines, and users from OpenClaw.

Authentication

Requires a Twitter API Bearer Token set as TWITTER_BEARER_TOKEN.

Optionally set TWITTER_API_KEY and TWITTER_API_SECRET for write operations (post, like, retweet).

Run twclaw auth-check to verify credentials.

Commands

Reading

twclaw read <tweet-url-or-id>          # Read a single tweet with full metadata
twclaw thread <tweet-url-or-id>        # Read full conversation thread
twclaw replies <tweet-url-or-id> -n 20 # List replies to a tweet
twclaw user <@handle>                  # Show user profile info
twclaw user-tweets <@handle> -n 20     # User's recent tweets

Timelines

twclaw home -n 20                      # Home timeline
twclaw mentions -n 10                  # Your mentions
twclaw likes <@handle> -n 10           # User's liked tweets

Search

twclaw search "query" -n 10            # Search tweets
twclaw search "from:elonmusk AI" -n 5  # Search with operators
twclaw search "#trending" --recent     # Recent tweets only
twclaw search "query" --popular        # Popular tweets only

twclaw trending                        # Trending topics worldwide
twclaw trending --woeid 23424977       # Trending in specific location

Posting

twclaw tweet "hello world"                          # Post a tweet
twclaw reply <tweet-url-or-id> "great thread!"      # Reply to a tweet
twclaw quote <tweet-url-or-id> "interesting take"   # Quote tweet
twclaw tweet "look at this" --media image.png        # Tweet with media

Engagement

twclaw like <tweet-url-or-id>          # Like a tweet
twclaw unlike <tweet-url-or-id>        # Unlike a tweet
twclaw retweet <tweet-url-or-id>       # Retweet
twclaw unretweet <tweet-url-or-id>     # Undo retweet
twclaw bookmark <tweet-url-or-id>      # Bookmark a tweet
twclaw unbookmark <tweet-url-or-id>    # Remove bookmark

Following

twclaw follow <@handle>                # Follow user
twclaw unfollow <@handle>              # Unfollow user
twclaw followers <@handle> -n 20       # List followers
twclaw following <@handle> -n 20       # List following

Lists

twclaw lists                           # Your lists
twclaw list-timeline <list-id> -n 20   # Tweets from a list
twclaw list-add <list-id> <@handle>    # Add user to list
twclaw list-remove <list-id> <@handle> # Remove user from list

Output Options

--json          # JSON output
--plain         # Plain text, no formatting
--no-color      # Disable ANSI colors
-n <count>      # Number of results (default: 10)
--cursor <val>  # Pagination cursor for next page
--all           # Fetch all pages (use with caution)

Guidelines for OpenClaw

When reading tweets, always show: author, handle, text, timestamp, engagement counts.
For threads, present tweets in chronological order.
When searching, summarize results concisely with key metrics.
Before posting/liking/retweeting, confirm the action with the user.
Rate limits apply — space out bulk operations.
Use --json when you need to process output programmatically.

Troubleshooting

401 Unauthorized

Check that TWITTER_BEARER_TOKEN is set and valid.

429 Rate Limited

Wait and retry. Twitter API has strict rate limits per 15-minute window.

TL;DR: Read, search, post, and engage on Twitter/X. Always confirm before write actions.

x-twitter