X OAuth API

Post to X (Twitter) using the official OAuth 1.0a API. Use when asked to "post to X", "tweet this", "post on Twitter", create threads, delete tweets, or chec...

Security Scan

The skill implements posting to X/Twitter and requests the expected OAuth keys, but there are inconsistencies (Node runtime not declared, no install instructions) and it includes automation/heartbeat scripts that write state to your home directory — review before installing.

Purpose & Capability

Name, description, CLI commands, and the code (bin/x.js) all align: the skill posts tweets, threads, deletes tweets, and queries account/mentions/search via X API v2 using OAuth 1.0a. The required environment variables (the four OAuth values) are exactly what the code uses.

Instruction Scope

Runtime instructions and README correctly describe using environment variables and direct requests to api.twitter.com. However, included helper scripts (generic-post.sh, heartbeat.sh) create state and log files under $HOME/.openclaw/... (or $OPENCLAW_STATE_DIR) and are designed for automated posting/monitoring. SKILL.md and registry metadata did not declare these state/config paths; users should be aware the skill will write logs and state files and can be used to automate posts.

Install Mechanism

There is no install specification in the registry metadata even though the bundle contains node code (bin/x.js), package.json, and package-lock.json with npm dependencies. The skill metadata lists no required binaries, but the code requires Node (package.json specifies node >=16) and uses npm packages. This mismatch (no declared Node/runtime requirement or install steps) is an incoherence and could cause surprises or failed installations.

Credentials

The skill only requests the four OAuth environment variables required for OAuth 1.0a (consumer key/secret and access token/secret). An optional X_USER_ID is referenced but not required. No unrelated credentials or secrets are requested.

Persistence & Privilege

The skill does not request 'always: true' or elevated platform privileges. It does, however, persist state and logs to user-writable directories (~/.openclaw/...). The presence of automation templates (generic-post.sh) and a heartbeat script means this package is set up to run recurring/automated posts if a user enables or schedules those scripts — consider this before enabling automation.

What to consider before installing

What to check before installing: - Verify you are comfortable providing a dedicated X (Twitter) app's OAuth credentials; these tokens grant full ability to post/delete as that account. Use a dedicated app and tokens, not high-privilege or shared keys. - The package contains Node code and a package.json (node >=16) but the skill metadata does not declare Node as a required binary or provide an install step. Make sure your environment has Node and install dependencies (npm install) before expecting the CLI to work. - The included scripts will create logs and state files under $HOME/.openclaw/x-poster and $HOME/.openclaw/heartbeat (or the path you set with OPENCLAW_STATE_DIR). If you do not want files written there, inspect and modify scripts first or run in an isolated container/VM. - Automation capability: generic-post.sh is a template for automated posting. Do not schedule or enable it unless you review and customize get_content() to avoid accidental or unwanted posts. - Review the code (bin/x.js, the shell scripts) yourself; the code appears to only contact api.twitter.com and read env vars, but you should verify there are no hidden endpoints or unexpected network calls in the runtime you will use. - As a precaution, test with a throwaway or low-privilege account/app, and rotate credentials after testing if you suspect exposure. If you want me to, I can: (a) extract and show the exact lines that create files/dirs, (b) produce a minimal checklist to safely run this skill inside a container, or (c) search the code for any network calls beyond api.twitter.com.

X OAuth API Skill

Post to X (formerly Twitter) using the official X API with OAuth 1.0a authentication.

Overview

This skill provides direct access to X API v2 for posting tweets, managing threads, and monitoring mentions. No proxy or third-party service required — uses your X API credentials directly.

Use when:

• User says "post to X", "tweet this", "post on Twitter"
• Need to create threads or media posts
• Want to check mentions or engage with replies

Quick Start

1. Configure X API Credentials

Store these environment variables (from your X Developer Account):

X_API_KEY              # Consumer Key (API Key)
X_API_SECRET           # Consumer Secret
X_ACCESS_TOKEN         # Access Token
X_ACCESS_TOKEN_SECRET  # Access Token Secret
X_USER_ID              # Optional: Your numeric user ID (speeds up mentions)

Free Tier vs Paid Tier

Free tier supports:

• ✅ Posting tweets and threads
• ✅ Deleting tweets
• ✅ Account info lookup (x me)

Requires Basic+ tier:

• 🔒 Search tweets
• 🔒 Fetch mentions
• 🔒 Media uploads

2. Basic Usage

# Post a simple tweet
x post "Hello from X API"

# Post a thread
x thread "First tweet" "Second tweet" "Third tweet"

# Check mentions
x mentions --limit 10

# Search recent tweets
x search "AI agents" --limit 5

Commands

x post <text>

Post a single tweet.

Options:

• --reply-to <tweet-id> - Reply to a specific tweet
• --quote <tweet-id> - Quote tweet
• --media <file> - Attach image/video

x thread <tweet1> <tweet2> ...

Post a tweet thread.

x mentions [options]

Get recent mentions of your account.

Options:

• --limit <n> - Number of mentions (default: 10, max: 100)
• --since <tweet-id> - Only mentions after this ID
• --format json - Output as JSON

x search <query> [options]

Search recent tweets.

Options:

• --limit <n> - Number of results (default: 10, max: 100)
• --format json - Output as JSON

x delete <tweet-id>

Delete a tweet.

x me

Show current account info (name, username, follower counts, user ID).

API Rate Limits

Endpoint	Limit	Window
POST /2/tweets	200	15 min (Free tier)
GET /2/tweets/search/recent	100	15 min (Free tier)
GET /2/users/:id/mentions	100	15 min (Free tier)

Rate limits vary by access tier. See X API documentation for details.

Authentication

OAuth 1.0a is handled transparently. Just provide your credentials via environment variables. The skill will sign all requests automatically.

Troubleshooting

"Unauthorized" error

• Check X API credentials are correct
• Verify credentials are set in environment
• Ensure your app has write permissions in X Developer Portal

"Rate limit exceeded"

• Wait 15 minutes for limit to reset
• Reduce request frequency

"This endpoint requires a paid X API tier"

• Search and mentions require Basic+ tier on X API
• Free tier only supports posting, deleting, and account lookup

Requirements

• X Developer Account with API access
• OAuth 1.0a credentials configured
• Network access to api.twitter.com

Cost

Free. X API is free for basic usage. Check your app's rate limits in X Developer Portal.

Gotchas

• Free tier only supports posting, deleting, and account lookup — search, mentions, and media uploads require Basic+ tier ($100/month). Don't attempt these on free tier; you'll get a clear "requires paid tier" error.
• "Unauthorized" after credential rotation — X API keys are invalidated when you regenerate them in the Developer Portal. All 4 env vars must be updated together (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET).
• Trailing newlines in env vars break auth — If you copy/paste credentials and include a trailing \n, OAuth signing will fail silently with a 401. Always verify with echo -n "$X_API_KEY" | xxd to confirm no whitespace.
• Rate limit 429s are per-endpoint — Hitting the limit on POST /2/tweets doesn't affect GET /2/users. Each endpoint has its own 15-minute window. Back off only the failing endpoint.
• App write permissions must be set before generating tokens — If you generate access tokens before enabling "Read and Write" in the Developer Portal, the tokens will be read-only. Regenerate tokens after changing permissions.