social-media-autopilot

通过 OpenClaw 在 X (Twitter)、LinkedIn 和 Instagram 上安排、撰写和发布社交媒体帖子。管理内容日历、通过审批工作流程对帖子进行排队、跟踪参与度分析并保持品牌声音的一致性。在以下情况下使用：(1) 安排或发布社交媒体帖子，(2) 管理内容日历，(3) 为多个平台起草帖子，(4) 审查帖子表现/分析，(5) 设置自动发布工作流程，或 (6) 维护社交媒体存在。

# Social Media Autopilot

Multi-platform social media management from your OpenClaw agent. Schedule posts, manage a content calendar, get approval before publishing, and track performance.

## Setup

### Required API Credentials

Configure in your environment or `.env` file:

- **X (Twitter):** Requires `xurl` skill or X API v2 credentials (`X_BEARER_TOKEN`, `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_SECRET`)
- **LinkedIn:** `LINKEDIN_ACCESS_TOKEN` (OAuth 2.0 — see `references/linkedin-setup.md`)
- **Instagram:** `INSTAGRAM_ACCESS_TOKEN` + `INSTAGRAM_BUSINESS_ID` (Meta Graph API — see `references/instagram-setup.md`)

### Content Directory

All content lives in `~/.openclaw/workspace/social-media/`:

```
social-media/
├── calendar.json        # Scheduled posts
├── drafts/              # Posts awaiting approval
├── published/           # Archive of sent posts
├── templates/           # Reusable post templates
└── analytics/           # Performance data
```

Run `scripts/init-workspace.sh` to create this structure.

## Core Workflows

### 1. Draft & Schedule Posts

To create a post:

1. Run `scripts/draft-post.sh --platform <x|linkedin|instagram|all> --text "Post content" [--media path/to/image] [--schedule "2026-02-25 09:00 PST"]`
2. Post saves to `drafts/` as a JSON file with metadata
3. If `--schedule` is set, it's added to `calendar.json`
4. Without `--schedule`, it queues for immediate review

Draft JSON format:
```json
{
  "id": "uuid",
  "platforms": ["x", "linkedin"],
  "text": "Post content here",
  "media": [],
  "scheduled_at": "2026-02-25T17:00:00Z",
  "status": "draft",
  "created_at": "2026-02-23T22:00:00Z",
  "approved": false,
  "tags": ["product-launch"],
  "thread": false
}
```

### 2. Approval Workflow

Before any post goes live:

1. Agent presents the draft to the user with platform previews
2. User approves, edits, or rejects
3. Only approved posts get published
4. Use `scripts/approve-post.sh <post-id>` or `scripts/reject-post.sh <post-id> --reason "..."`

**Never auto-publish without explicit approval** unless the user has configured `auto_approve: true` in `social-media/config.json`.

### 3. Publishing

Run `scripts/publish-post.sh <post-id>` to publish an approved post.

The script:
- Validates the post is approved
- Adapts content per platform (character limits, hashtag style, media format)
- Posts via each platform's API
- Saves response data (post IDs, URLs) to `published/`
- Updates `calendar.json` status

Platform-specific adaptations:
- **X:** 280 char limit, auto-thread if longer, image upload via media endpoint
- **LinkedIn:** 3000 char limit, supports articles and documents
- **Instagram:** Requires media (image/video), caption limit 2200 chars

### 4. Content Calendar

View and manage scheduled content:

- `scripts/calendar.sh --week` — Show this week's schedule
- `scripts/calendar.sh --month` — Monthly overview
- `scripts/calendar.sh --gaps` — Find gaps in posting schedule
- `scripts/calendar.sh --reschedule <post-id> "new-datetime"` — Move a post

### 5. Analytics

Pull engagement data for published posts:

- `scripts/analytics.sh --last 7d` — Last 7 days performance
- `scripts/analytics.sh --post <post-id>` — Single post performance
- `scripts/analytics.sh --report weekly` — Generate weekly report

Metrics tracked: impressions, engagements, clicks, replies, reposts, likes, followers gained.

### 6. Templates & Brand Voice

Store reusable templates in `templates/`:

```json
{
  "name": "product-announcement",
  "platforms": ["x", "linkedin"],
  "template": "🚀 {product_name} is here!\n\n{description}\n\n{link}\n\n{hashtags}",
  "variables": ["product_name", "description", "link", "hashtags"],
  "voice_notes": "Excited but professional. No ALL CAPS."
}
```

When composing posts, reference `social-media/brand-voice.md` for tone guidelines if it exists.

## Cron Integration

Add to OpenClaw cron for automated workflows:

- **Publish scheduled posts:** Check `calendar.json` every 15 min, publish any due approved posts
- **Daily digest:** Summarize yesterday's analytics each morning
- **Gap alerts:** Notify if no posts scheduled for next 48h

## Error Handling

- API rate limits: Back off and retry with exponential delay
- Failed posts: Move to `drafts/` with `status: "failed"` and error message
- Expired tokens: Alert user to re-authenticate

## References

- `references/linkedin-setup.md` — LinkedIn OAuth setup guide
- `references/instagram-setup.md` — Instagram/Meta Graph API setup guide
- `references/platform-limits.md` — Character limits, media specs, rate limits per platform

---

## 中文说明

# 社交媒体自动驾驶

通过你的 OpenClaw 代理实现多平台社交媒体管理。安排帖子、管理内容日历、在发布前获取审批，并跟踪表现。

## 设置

### 必需的 API 凭据

在你的环境或 `.env` 文件中配置：

- **X (Twitter)：** 需要 `xurl` 技能或 X API v2 凭据（`X_BEARER_TOKEN`、`X_API_KEY`、`X_API_SECRET`、`X_ACCESS_TOKEN`、`X_ACCESS_SECRET`）
- **LinkedIn：** `LINKEDIN_ACCESS_TOKEN`（OAuth 2.0 —— 参见 `references/linkedin-setup.md`）
- **Instagram：** `INSTAGRAM_ACCESS_TOKEN` + `INSTAGRAM_BUSINESS_ID`（Meta Graph API —— 参见 `references/instagram-setup.md`）

### 内容目录

所有内容都存放在 `~/.openclaw/workspace/social-media/`：

```
social-media/
├── calendar.json        # Scheduled posts
├── drafts/              # Posts awaiting approval
├── published/           # Archive of sent posts
├── templates/           # Reusable post templates
└── analytics/           # Performance data
```

运行 `scripts/init-workspace.sh` 来创建此结构。

## 核心工作流程

### 1. 起草和安排帖子

创建帖子：

1. 运行 `scripts/draft-post.sh --platform <x|linkedin|instagram|all> --text "Post content" [--media path/to/image] [--schedule "2026-02-25 09:00 PST"]`
2. 帖子作为带元数据的 JSON 文件保存到 `drafts/`
3. 如果设置了 `--schedule`，则会将其添加到 `calendar.json`
4. 不带 `--schedule` 时，它会排队等待立即审查

草稿 JSON 格式：
```json
{
  "id": "uuid",
  "platforms": ["x", "linkedin"],
  "text": "Post content here",
  "media": [],
  "scheduled_at": "2026-02-25T17:00:00Z",
  "status": "draft",
  "created_at": "2026-02-23T22:00:00Z",
  "approved": false,
  "tags": ["product-launch"],
  "thread": false
}
```

### 2. 审批工作流程

在任何帖子上线之前：

1. 代理向用户展示带有平台预览的草稿
2. 用户批准、编辑或拒绝
3. 只有获批的帖子才会被发布
4. 使用 `scripts/approve-post.sh <post-id>` 或 `scripts/reject-post.sh <post-id> --reason "..."`

**未经明确批准切勿自动发布**，除非用户已在 `social-media/config.json` 中配置 `auto_approve: true`。

### 3. 发布

运行 `scripts/publish-post.sh <post-id>` 来发布已获批的帖子。

该脚本会：
- 验证帖子已获批
- 按平台调整内容（字符限制、话题标签样式、媒体格式）
- 通过每个平台的 API 发布
- 将响应数据（帖子 ID、URL）保存到 `published/`
- 更新 `calendar.json` 状态

平台特定的调整：
- **X：** 280 字符限制，超出则自动串联成线程，通过媒体端点上传图片
- **LinkedIn：** 3000 字符限制，支持文章和文档
- **Instagram：** 需要媒体（图片/视频），标题限制 2200 字符

### 4. 内容日历

查看和管理已安排的内容：

- `scripts/calendar.sh --week` — 显示本周的安排
- `scripts/calendar.sh --month` — 月度概览
- `scripts/calendar.sh --gaps` — 查找发布安排中的空档
- `scripts/calendar.sh --reschedule <post-id> "new-datetime"` — 移动帖子

### 5. 分析

拉取已发布帖子的参与度数据：

- `scripts/analytics.sh --last 7d` — 最近 7 天的表现
- `scripts/analytics.sh --post <post-id>` — 单个帖子的表现
- `scripts/analytics.sh --report weekly` — 生成周报

跟踪的指标：曝光量、互动量、点击量、回复、转发、点赞、新增关注者。

### 6. 模板和品牌声音

将可复用的模板存放在 `templates/`：

```json
{
  "name": "product-announcement",
  "platforms": ["x", "linkedin"],
  "template": "🚀 {product_name} is here!\n\n{description}\n\n{link}\n\n{hashtags}",
  "variables": ["product_name", "description", "link", "hashtags"],
  "voice_notes": "Excited but professional. No ALL CAPS."
}
```

撰写帖子时，如果 `social-media/brand-voice.md` 存在，请参考它的语气指南。

## Cron 集成

将以下内容添加到 OpenClaw cron 以实现自动化工作流程：

- **发布已安排的帖子：** 每 15 分钟检查一次 `calendar.json`，发布任何到期的已获批帖子
- **每日摘要：** 每天早上汇总前一天的分析数据
- **空档提醒：** 如果未来 48 小时内没有安排帖子则通知

## 错误处理

- API 速率限制：退避并以指数延迟重试
- 失败的帖子：移至 `drafts/`，标记 `status: "failed"` 并附上错误消息
- 令牌过期：提醒用户重新认证

## 参考资料

- `references/linkedin-setup.md` — LinkedIn OAuth 设置指南
- `references/instagram-setup.md` — Instagram/Meta Graph API 设置指南
- `references/platform-limits.md` — 各平台的字符限制、媒体规格、速率限制