openclaw-plugin-x

Draft-first X/Twitter management plugin for OpenClaw.

This package has been proven locally for the core single-account workflow:

OAuth PKCE connect flow with manual code/redirect completion
authenticated reads
durable local drafts
explicit approval recording
approval-gated single-post publish
media upload and media-backed publish

It is real, but it is not fully productized yet. The main remaining gaps are release polish, install/load validation in a public-facing runtime path, automatic OAuth callback handling, and thread publish.

Current status

Proven working locally

OAuth auth URL generation and manual completion
session persistence and token refresh handling
x_account_me
x_timeline_me
x_timeline_mentions
x_post_get
x_post_context
x_post_create
x_post_reply
x_post_quote
x_post_thread as durable draft creation
x_post_approve
x_post_publish for approved single-post drafts
x_media_upload
media-backed single-post publish
X/Twitter post URL resolution

Not done yet

automatic OAuth callback HTTP handling inside OpenClaw
live engagement actions for like / repost / bookmark
thread publish
deeper conversation expansion beyond immediate referenced posts
broader public-release validation beyond local/manual QA

Safety model

This plugin is intentionally draft-first:

create/reply/quote/thread actions create stored drafts
x_post_approve records explicit approval
x_post_publish only performs a live write for an already-approved single-post draft with valid user credentials

Approval remains mandatory by design.

Requirements

Node.js 22+
OpenClaw version compatible with the package metadata in package.json
X developer app credentials for OAuth-based account access

Install

Option A: local/path install during development

cd projects/openclaw-plugin-x
npm install
npm run check
npm run build

Then install/load it through your OpenClaw plugin flow using the built package directory.

Option B: packed/published package

This repository includes the package metadata and native OpenClaw manifest needed for external distribution:

package.json
openclaw.plugin.json

It also currently ships plugin.manifest.json for compatibility with the existing local release flow.

Before public publication, do one more install/load validation from the packed artifact, not just from the source tree.

Setup

Copy the example env file and fill in the values you actually need.
Build the plugin.
Configure/load it in OpenClaw.
Run x_account_connect to inspect readiness.
Start OAuth with x_account_auth_url.
Complete OAuth with x_account_complete using either the auth code or the full redirect URL.

Example env bring-up

cp .env.example .env
npm run build

Environment variables

Required for OAuth flow:

X_CLIENT_ID
X_REDIRECT_URI

Commonly needed:

X_CLIENT_SECRET
X_BEARER_TOKEN
X_ACCESS_TOKEN
X_REFRESH_TOKEN
X_USER_ID

Defaults exist, but may be overridden when needed:

X_API_BASE_URL
X_UPLOAD_API_BASE_URL
X_OAUTH_AUTHORIZE_URL
X_OAUTH_TOKEN_URL
X_OAUTH_SCOPES
X_DRAFTS_FILE_PATH
X_SESSION_FILE_PATH

Important: do not point X_SESSION_FILE_PATH or X_DRAFTS_FILE_PATH inside the plugin install directory under ~/.openclaw/extensions/.... OpenClaw plugin updates replace that directory and will wipe plugin-local files stored there.

Recommended stable paths:

X_SESSION_FILE_PATH=~/.openclaw/state/openclaw-plugin-x/session.json
X_DRAFTS_FILE_PATH=~/.openclaw/state/openclaw-plugin-x/drafts.json

Typical scope set now includes:

tweet.read
tweet.write
users.read
offline.access
media.write

Tool surface

Auth / account

x_account_connect
x_account_auth_url
x_account_complete
x_account_me

Read

x_timeline_me
x_timeline_mentions
x_post_get
x_post_context
x_util_resolve_url

Draft / approval / publish

x_post_create
x_post_reply
x_post_quote
x_post_thread
x_post_approve
x_post_publish

Media

x_media_upload

Scaffold-only engagement

x_engagement_like
x_engagement_repost
x_engagement_bookmark

Development

npm run check
npm run build
npm pack --dry-run

Publish path

Recommended public release flow:

clawhub package publish <source> --dry-run
clawhub package publish <source>

Where <source> can be a local folder, owner/repo, owner/repo@ref, or a GitHub URL.

For consumers:

openclaw plugins install clawhub:<package-name>

This plugin is designed to pair with an agent-side skill such as x-management for the full draft-first workflow.

Known limitations

plugin drafts are local plugin drafts, not X-native drafts shown in X apps
OAuth completion is currently manual; automatic callback handling is not implemented
engagement actions are plan-only today
only approved single-post drafts can be published live today
thread drafts are stored, but thread publish is not implemented
public install/load validation still needs one clean pass from the distributable artifact

Release notes for maintainers

Manual release checks live in docs/release-checklist.md
Current implementation truth/status lives in docs/implementation-status.md
Capability-by-capability status lives in docs/capability-matrix.md

License

MIT

Openclaw Plugin X