npm package: @matthew-reed-holden/openclaw-x-plugin
Description: OpenClaw X (Twitter) plugin — post, engage, and manage persona via API v2
Latest version: 0.4.2

# OpenClaw X Plugin

An OpenClaw plugin for posting, engaging, and managing a persona on X (Twitter) via the X API v2.

## Features

**16 agent tools:**

| Tool | Description |
|------|-------------|
| `x_post` | Post a tweet (auto-threads content over 280 chars) |
| `x_like` | Like a tweet (idempotent) |
| `x_reply` | Reply to a tweet |
| `x_retweet` | Retweet (idempotent) |
| `x_quote` | Quote tweet with commentary |
| `x_delete` | Delete a tweet |
| `x_search` | Search recent tweets |
| `x_get_tweet` | Fetch full tweet details |
| `x_get_mentions` | Fetch recent mentions |
| `x_upload_media` | Upload images/video for attachment |
| `x_timeline_scan` | Scan timeline with weighted scoring algorithm |
| `x_analytics` | Engagement summary for recent activity |
| `x_persona_setup` | Generate persona from your X history |
| `x_persona_edit` | Edit persona voice, topics, constraints |
| `x_persona_show` | View current persona |
| `x_persona_delete` | Remove persona |

**Persona system:** Analyzes your tweet history to capture your voice, tone, vocabulary, and engagement style. The agent matches your persona when composing tweets.

**Timeline algorithm:** Weighted scoring system (user relevance, time decay, content relevance) for autonomous engagement decisions. Configurable weights and target users.

**Safety layer:** Tweet deduplication, per-endpoint rate limit tracking, content validation, interaction delays, and dry-run mode.

## Installation

```bash
openclaw plugins install @matthew-reed-holden/openclaw-x-plugin
```

## Configuration

### 1. Create an X Developer App

Go to [developer.x.com](https://developer.x.com) and create an app with OAuth 2.0 enabled. You'll need:
- Client ID
- Access token and refresh token (with `tweet.read`, `tweet.write`, `users.read`, `like.read`, `like.write`, `offline.access` scopes)

### 2. Add credentials to OpenClaw config

```bash
openclaw config set plugins.entries.x.config.x.auth.clientId "your-client-id"
openclaw config set plugins.entries.x.config.x.auth.accessToken "your-access-token"
openclaw config set plugins.entries.x.config.x.auth.refreshToken "your-refresh-token"
openclaw config set plugins.entries.x.config.x.userId "your-x-user-id"
openclaw config set plugins.entries.x.config.x.username "your-x-username"
```

Or edit `~/.openclaw/config.json` directly:

```json
{
  "plugins": {
    "entries": {
      "x": {
        "config": {
          "x": {
            "auth": {
              "clientId": "your-client-id",
              "accessToken": "your-access-token",
              "refreshToken": "your-refresh-token"
            },
            "userId": "your-x-user-id",
            "username": "your-x-username"
          }
        }
      }
    }
  }
}
```

Tokens auto-refresh when they expire. The plugin persists new tokens to config automatically.

### 3. Optional: Enable dry-run mode for testing

```bash
openclaw config set plugins.entries.x.config.x.dryRun true
```

All write actions will be simulated without posting to X.

## Autonomous Engagement

Enable periodic timeline scanning and automatic engagement:

```json
{
  "x": {
    "autonomous": {
      "enabled": true,
      "cronInterval": "*/5 * * * *",
      "maxInteractionsPerRun": 5,
      "algorithm": "weighted",
      "weights": { "user": 3, "time": 2, "relevance": 5 },
      "targetUsers": ["user1", "user2"],
      "interactionDelayMs": { "min": 5000, "max": 15000 }
    }
  }
}
```

The weighted scoring algorithm evaluates tweets on three factors:
- **User score (0-10):** Target users score 10, verified +2, high followers +1
- **Time score (0-10):** Decays 1 point per 2 hours
- **Relevance score (0-10):** Content match against persona topics

## Persona

Generate a persona from your X history:

```
> Use x_persona_setup to analyze my tweets
```

The agent fetches your recent tweets, analyzes your voice and style, and creates a persona document. All future tweets, replies, and quotes will match your tone, vocabulary, and engagement patterns.

Edit specific aspects:

```
> Use x_persona_edit to set my constraints to never tweet about politics
```

## Required OAuth 2.0 Scopes

| Scope | Used For |
|-------|----------|
| `tweet.read` | Get tweets, search, mentions, timeline |
| `tweet.write` | Post, reply, quote, delete tweets |
| `users.read` | Get user profile, verify identity |
| `like.read` | Check like status, persona analysis |
| `like.write` | Like/unlike tweets |
| `offline.access` | Refresh token grant |

## License

MIT