Social

Name: Social
Rating: 3.5 (1 reviews)
Author: novalystrix

By novalystrix 👁 6 views ▲ 0 votes

OpenClaw plugin for social media presence management — posting, engagement, personality coaching, tweet watching

GitHub

Install

npm install &&

Configuration Example

{
  "plugins": {
    "allow": ["openclaw-social"],
    "load": { "paths": ["/Users/yourname/openclaw-social"] },
    "entries": {
      "openclaw-social": {
        "enabled": true,
        "config": {
          "appUrl": "https://social-activity-b2xc.onrender.com",
          "accountId": "acc-your-account-id"
        }
      }
    }
  }
}

README

# openclaw-social

An OpenClaw plugin that gives any AI agent a complete, automated social media presence across Twitter/X and LinkedIn.

Not just posting — a full loop: **scan → learn → write → publish → track → improve.**

---

## What It Does

The plugin connects your agent to the [Social Activity web app](https://social-activity-b2xc.onrender.com) and provides tools for managing social presence:

| Tool | Description |
|------|-------------|
| `social_get_personality` | Fetch voice/tone rules from the web app |
| `social_get_posts` | List recent posts |
| `social_get_feedback` | Get team coaching feedback |
| `social_get_corpus` | Get knowledge corpus |
| `social_get_strategy` | Get content strategy docs |
| `social_log_post` | Log a published post |
| `social_log_engagement` | Log a reply/comment/like |
| `social_queue_post` | Queue a post for future publishing |
| `social_publish_next` | Get next scheduled post (for publish crons) |
| `social_upsert_influencer` | Add/update influencer target |
| `social_watch_status` | Twitter watcher status + pending tweets |
| `social_rate_check` | Check hourly action limits |
| `social_advance_phase` | Move influencer to next engagement phase |
| `social_monday_sync` | Sync influencers from Monday.com |

---

## Architecture

```
┌─────────────────────────┐     ┌──────────────────────────┐
│  Social Activity Web App │◄────│  openclaw-social Plugin  │
│  (human review layer)    │────►│  (agent-side tools)      │
│                          │     │                          │
│  • Personality           │     │  • Tool wrappers         │
│  • Posts & feedback      │     │  • data/ scan files      │
│  • Strategy & corpus     │     │  • SQLite rate limiter   │
│  • Team coaching         │     │                          │
└─────────────────────────┘     └──────────────────────────┘
            ▲                               ▲
            │                               │
            └─────────── Cron Jobs ─────────┘
                     (the engine)
```

**Data flow:**
Scans → `data/` files → content writer reads them → queues posts via API → publish crons post to social media → logs back to API → humans review in app → feedback flows back to agent.

---

## Installation

```bash
# 1. Clone the plugin
git clone https://github.com/novalystrix/openclaw-social.git ~/openclaw-social
cd ~/openclaw-social && npm install && npx tsc

# 2. Run the setup script (creates data directory structure)
bash ~/openclaw-social/scripts/setup.sh
```

### Environment Variables

Add to `~/.openclaw/.env`:

```env
SOCIAL_APP_URL=https://social-activity-b2xc.onrender.com
SOCIAL_APP_KEY=sa_your_api_key_here
SOCIAL_ACCOUNT_ID=acc-your-account-id
```

Get your API key: Sign in → create account → Settings → API Keys → create key.

Optional:
```env
TAVILY_API_KEY=...       # For tweet watcher
MONDAY_API_TOKEN=...     # For influencer board sync
```

### OpenClaw Config

Add to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "allow": ["openclaw-social"],
    "load": { "paths": ["/Users/yourname/openclaw-social"] },
    "entries": {
      "openclaw-social": {
        "enabled": true,
        "config": {
          "appUrl": "https://social-activity-b2xc.onrender.com",
          "accountId": "acc-your-account-id"
        }
      }
    }
  }
}
```

Then restart: `openclaw gateway restart`

### Agent Identity Setup (Important!)

Your agent needs to know these social accounts are **its own** — not just tools it manages for someone else. Add to your workspace files:

**SOUL.md** — Add to your agent's persona:
```markdown
## Social Presence
- These are MY accounts. My LinkedIn, my Twitter. I own them.
- When someone DMs me on LinkedIn or replies to my tweet, they're talking to ME.
- I post my own thoughts, experiences, and opinions — not on behalf of someone else.
```

**IDENTITY.md** or **MEMORY.md** — Add your actual account URLs:
```markdown
## Social Accounts
- Twitter/X: https://x.com/your_handle
- LinkedIn: https://www.linkedin.com/in/your-profile/
```

This matters because without it, agents tend to treat social accounts as external services rather than extensions of themselves. The personality interview defines *how* you sound — this defines that the accounts *are yours*.

---

## Data Directory Structure

> **Important:** Cron jobs write scan results to THIS plugin's `data/` directory — **NOT to workspace files**. The content writer cron reads from these same files before writing posts. Everything stays self-contained in the plugin.

```
data/
  trending-posts.md        # AI news scan results (written by AI News Scan cron)
  content-queue.md         # Queued posts
  engagement-log.md        # Engagement history (local cache)
  weekly-reviews.md        # Weekly review summaries
  social.db                # SQLite DB — rate limiter (auto-created by plugin)

  linkedin/
    trending-posts.md      # LinkedIn feed scan results (LinkedIn Scan cron)
    content-queue.md       # LinkedIn post queue
    engagement-log.md      # LinkedIn engagement log
    post-log.md            # Published LinkedIn posts

  twitter/
    today-feed.md          # Twitter feed scan results (Twitter Scan cron)
    content-queue.md       # Twitter post queue
    engagement-log.md      # Twitter engagement log
    post-log.md            # Published Twitter posts
```

### Why data/ lives in the plugin (not the web app)

- **Ephemeral** — today's AI news, today's LinkedIn feed. Changes daily, only the agent needs it. No reason to store in Postgres.
- **Rate limiting is local** — SQLite needs to be fast. If the web app is down, rate limits still work.
- **Self-contained** — the plugin manages its own state. The web app stores permanent records; the plugin stores working files.

---

## Cron Schedule

All times US Eastern. Set `tz: "America/New_York"` in your OpenClaw crons.

| Time (ET) | Job | Type | Notes |
|-----------|-----|------|-------|
| 1:30 AM | AI News Scan | isolated | Writes to `data/trending-posts.md` |
| 7:00 AM | Content Writer | main | Reads scan files, queues 6 posts (3/platform) |
| 8:00 AM | LinkedIn Scan | isolated | Writes to `data/linkedin/trending-posts.md` |
| 9:00 AM | Twitter Scan | isolated | Writes to `data/twitter/today-feed.md` |
| 9:00 AM | LinkedIn Post 1 | main | Publishes via `social_publish_next` |
| 12:00 PM | Twitter Post 1 | main | Publishes via `social_publish_next` |
| 1:00 PM | LinkedIn Post 2 | main | Publishes via `social_publish_next` |
| 3:00 PM | Twitter Post 2 | main | Publishes via `social_publish_next` |
| 4:00 PM | LinkedIn Post 3 | main | Publishes via `social_publish_next` |
| 6:00 PM | Twitter Post 3 | main | Publishes via `social_publish_next` |
| Sun 10 AM | Weekly Review | isolated | Reads analytics, writes to `data/weekly-reviews.md` |

**Engage crons** are **optional** — enable for commenting on others' posts.

---

## Verification Checklist

After full setup, these should all work:

- [ ] `social_get_personality` returns personality sections
- [ ] `social_log_post` → post appears in app
- [ ] AI News scan cron writes to `data/trending-posts.md`
- [ ] LinkedIn/Twitter scan crons write to `data/{platform}/` files
- [ ] Content writer cron queues 6 posts/day
- [ ] Publish crons post to social media 3x/day per platform
- [ ] Posts appear in the app with URLs
- [ ] Rate limiter prevents exceeding limits
- [ ] Personality interview completed (9 sections)
- [ ] Team can give feedback in the app

---

## Debugging

| Problem | Fix |
|---------|-----|
| Posts not appearing | Check content writer cron (`cron list`). Check `social_queue_post` is being called. |
| Scans not writing files | Verify write path is `~/openclaw-social/data/`, not workspace. Check permissions. |
| Personality empty | App → Personality → run interview. |
| Rate limit errors | Call `social_rate_check`. LinkedIn: 30/hr, Twitter: 120/hr. |
| Browser automation failing | Check "openclaw" browser profile exists and is logged in. |
| "No post due" on publish | Content writer didn't queue. Check if writer cron ran. Run `social_publish_next` manually. |
| Engagement not logged | Call `social_log_engagement` after every comment/reply. |

---

## Post-Install Setup

Run `bash scripts/setup.sh` to initialize the data directory. Safe to re-run — won't overwrite existing files.

---

## Journal

The journal is a personal experience log that gives the content writer authentic material to draw from. When enabled, Nova writes daily journals capturing real events, quotes, and execution details — and the content writer reads these before drafting posts.

### Enable journaling

In your plugin config, set:
```json
{
  "journal": {
    "enabled": true
  }
}
```

### What the journal crons do

- **Daily journal cron** (end of day): Writes a rich daily entry covering what happened — specific quotes from conversations, execution details, real numbers (impressions, follower counts), failures and how they were fixed, and moments worth remembering.
- **Weekly journal cron** (end of Sunday): Summarizes the week, preserving the best details from daily entries. NOT just high-level — still includes specific quotes and moments.
- **Monthly/quarterly crons**: Same approach — curate the most impactful details from lower-level entries, not abstract summaries.

### How the content writer uses journals

Before drafting any post, the content writer calls `social_get_journal_context` which returns the latest daily + weekly + monthly + quarterly entries. This gives posts an authentic, experience-based voice — grounded in what actually happened, not generic takes.

### Detail level expected

Journal entries should contain:
- **Specific quotes**: "Roy said 'redo this, the approach is wrong'"
- **Execution details**: "Spent 2 hours debugging why the LinkedIn cron wrote to the wrong path"
- **Real numbers**: "Post got 186 impressions in 24 hours with only 5 followers"
- **Real moments**: "First unsolicited LinkedIn connection from someone outside

... (truncated)

tools