X (Twitter) is still where breaking news, technical discussion, and personal branding happen in real time. If your agent can read that stream and post into it without you touching a keyboard, you gain a meaningful advantage. Bird makes that possible — and the setup is straightforward once you understand the X API credential structure.
What the Bird Skill Does
Bird wraps the X API v2 and gives your agent four core capabilities:
- Post tweets — single tweets, threads, and quote-tweets with optional media
- Read mentions — pull recent @mentions and replies directed at your account
- Monitor timeline — read your home timeline or a specific user's recent posts
- Manage DMs — read incoming direct messages and send replies
The skill handles authentication transparently once credentials are configured. Your agent calls /tweet with content and Bird manages the OAuth 2.0 flow, API call construction, error handling, and response parsing — returning clean structured data rather than raw API JSON.
Installation
openclaw plugins install birdAfter install:
openclaw plugins list | grep bird
# bird v1.5.2 built-in enabledThe skill shows as enabled but won't authenticate until you configure the X API credentials. Run a test immediately after credential setup to confirm the connection before building anything on top of it.
X API Credentials Setup
Getting X API credentials takes more steps than most APIs. Here's the exact path that works as of early 2025:
- Go to developer.x.com and create a developer account if you don't have one
- Create a new Project and App inside it
- Under App Settings, enable OAuth 2.0 and set User Authentication Settings
- Set app permissions to Read and Write (or Read, Write, and Direct Messages if you need DMs)
- Generate API Key, API Secret, Access Token, and Access Token Secret
- Copy all four values
Set these as environment variables:
export X_API_KEY="your_api_key"
export X_API_SECRET="your_api_secret"
export X_ACCESS_TOKEN="your_access_token"
export X_ACCESS_TOKEN_SECRET="your_access_token_secret"Skill.md Configuration
# skill.md — Bird skill configuration
skill: bird
version: "1.5"
config:
default_account: "@youraccount"
max_tweet_length: 280
auto_shorten_urls: true
mention_lookback_hours: 24 # how far back /mentions searches
dm_polling_enabled: false # set true to enable DM monitoring
rate_limit_buffer: 0.85 # stop at 85% of rate limit to avoid errorsSlash Commands
/tweet — Post to X
Posts a tweet from your configured account. Supports flags for media, threads, and quote-tweets.
/tweet "Just shipped the GoPlaces skill update. Location intelligence for any OpenClaw agent."
/tweet "Thread on what we learned building 50 agents this quarter:" --thread
/tweet "Great take on agent memory" --quote https://x.com/user/status/123456/mentions — Read Replies
Returns recent @mentions directed at your account, sorted by recency. Useful for agents that monitor and respond to inbound engagement.
/mentions
/mentions --since 6h
/mentions --filter question/dm — Direct Messages
Reads incoming DMs and sends replies. Requires DM permissions enabled in your X app settings.
/dm inbox
/dm reply @username "Thanks for reaching out — here's the info you requested..."Real-World Use Cases
Social Media Agent for Personal Branding
The most direct use case. Set up an agent that drafts tweet content based on your notes, research, or ideas, then posts on your behalf after you approve. The agent handles formatting, hashtag suggestions, and thread structure. You handle the ideas. Combined with the Obsidian skill, the agent can pull from your knowledge vault and turn notes into tweets automatically.
Content Monitoring and Amplification
Agents that watch specific X accounts or keywords via /mentions, summarize what's worth engaging with, and draft reply content for your review. Publishers use this to stay on top of industry conversations without spending hours scrolling. The agent surfaces the five tweets most worth engaging with each morning.
Automated Technical Update Announcements
Development teams use Bird to announce releases, changelogs, and status updates automatically. The agent reads a changelog file or GitHub release, formats it into a tweet thread, and posts. No manual social media management for routine technical updates.
Rate Limit Awareness
X API rate limits apply to your developer app, not individual accounts. Basic tier limits that affect Bird usage:
| Action | Basic Tier Limit | Reset Period |
|---|---|---|
| Tweet posts | 1,500/month | Monthly |
| Reads (tweets) | 500,000/month | Monthly |
| DM sends | 500/month | Monthly |
For personal automation — a few posts per day, checking mentions twice daily — Basic tier is more than sufficient. For agents serving multiple users or posting at scale, calculate your monthly post volume carefully before committing to a tier.
Terms of Service Considerations
Automated posting via the official API is explicitly permitted under X Developer Terms. What's prohibited: spam, coordinated inauthentic behavior, automated following/unfollowing at scale, and posting identical content across multiple accounts.
The Bird skill doesn't prevent you from building ToS-violating agents — that's your responsibility. The rule of thumb: if you'd be comfortable doing it manually and it serves a legitimate purpose, automation is fine. If the automation only makes economic sense at scale because manual execution would be detectable, you're in ToS-risky territory.
Common Mistakes
Forgetting that write access requires Basic tier, then wondering why tweets aren't posting. The error message is clear — "403 Forbidden: Your access token does not have write permission" — but easy to misread as a credential problem rather than a tier problem.
Not setting mention_lookback_hours appropriately. The default looks back 24 hours. If your agent checks mentions every 6 hours, you'll see duplicates unless you track which mentions you've already processed. Implement deduplication at the agent logic level.
Ignoring the rate_limit_buffer config. Set it to 0.80 or 0.85 so the skill stops before hitting hard limits. Hitting hard limits causes 429 errors that can temporarily block your app's API access.
Frequently Asked Questions
What X API tier does the Bird skill require?
Bird works with the X API Basic tier (formerly called Essential). Free tier access was removed in 2023. Basic tier ($100/month) provides write access for posting and reading mentions. For DM access and higher read volumes, the Pro tier is required.
Can the Bird skill post threads?
Thread posting is supported in Bird v1.4+. Use /tweet with the --thread flag followed by each tweet separated by a delimiter. The skill handles the reply-chain structure automatically, posting each segment as a reply to the previous one.
What are the rate limits for Bird skill posting?
Rate limits are set by X API, not the Bird skill. Basic tier allows 1,500 tweet posts per month and 500,000 reads per month. The skill surfaces rate limit errors when limits are hit and will not retry automatically — that logic is your agent's responsibility.
Does Bird skill support media uploads?
Image uploads are supported using the --media flag with a local file path or URL. Video upload support was added in Bird v1.5. Uploaded media is referenced by media_id in the tweet payload, following the standard X API v2 media upload flow.
Can I use the Bird skill for multiple X accounts?
Multiple accounts require separate skill instances, each with their own API credentials. Create separate agent skill configurations pointing to different credential sets. The Bird skill does not support account switching within a single session.
Is automated posting against X Terms of Service?
Automated posting is explicitly allowed under X Developer Terms when using the official API. What's prohibited is spam, coordinated inauthentic behavior, and platform manipulation. Legitimate automation — scheduling, monitoring, personal assistant workflows — is permitted.
You now have the complete picture: what Bird does, what credentials it needs, what the rate limits are, and where the ToS boundaries sit. The X API cost is real — $100/month for Basic tier — but for anyone serious about automating their social media presence, that's a reasonable trade against the hours of manual work it replaces.
Install Bird, configure your credentials, and run your first /tweet. Once you see a post go live through your agent, the use cases multiply fast.
J. Donovan builds automated content and engagement workflows for indie creators and small teams. He's run X automation via Bird since the skill's v1.0 release and has documented every API tier change that affected skill behavior since 2024.