twitter-post

通过官方 API v2 (OAuth 1.0a) 将推文发布到 Twitter/X。当用户要求发推文、发布到 Twitter/X、发送话题、回复推文或引用推文时使用。支持单条推文、话题、回复和引用推文，并具有自动字符权重验证功能。

# Twitter Post

Post tweets via the official Twitter/X API v2 using OAuth 1.0a authentication.

## Prerequisites

Four environment variables must be set. Obtain them from [developer.x.com](https://developer.x.com):

```
TWITTER_CONSUMER_KEY=<API Key>
TWITTER_CONSUMER_SECRET=<API Key Secret>
TWITTER_ACCESS_TOKEN=<Access Token>
TWITTER_ACCESS_TOKEN_SECRET=<Access Token Secret>
```

Optional:
- `HTTPS_PROXY` — HTTP proxy URL (e.g. `http://127.0.0.1:7897`) for regions that need it
- `TWITTER_DRY_RUN=1` — validate and print without posting

## Setup

Store credentials as env vars. Recommended: add to the OpenClaw instance config or export in shell profile. **Never hardcode keys in SKILL.md or scripts.**

If the user hasn't set up OAuth yet, guide them:

1. Go to [developer.x.com](https://developer.x.com) → Dashboard → Create App
2. Set **App permissions** to **Read and Write**
3. Go to **Keys and tokens** tab
4. Copy API Key, API Key Secret
5. Generate Access Token and Access Token Secret (ensure Read+Write scope)
6. If the portal only shows Read, use PIN-based OAuth flow:
   - Call `POST /oauth/request_token` with `oauth_callback=oob`
   - User opens `https://api.twitter.com/oauth/authorize?oauth_token=<token>`
   - User provides the PIN code
   - Call `POST /oauth/access_token` with the PIN as `oauth_verifier`

## Usage

All commands via `exec`. Script path: `scripts/tweet.js` (relative to this skill directory).

### Single tweet

```bash
node scripts/tweet.js "Your tweet content here"
```

### Reply to a tweet

```bash
node scripts/tweet.js --reply-to 1234567890 "Reply text"
```

### Quote tweet

```bash
node scripts/tweet.js --quote 1234567890 "Your commentary"
```

### Thread (multiple tweets)

```bash
node scripts/tweet.js --thread "First tweet" "Second tweet" "Third tweet"
```

### Output

JSON to stdout:

```json
{"ok":true,"id":"123456789","url":"https://x.com/i/status/123456789","remaining":"99","limit":"100"}
```

On error: `{"ok":false,"error":"..."}`

## Character Limits

- Max 280 weighted characters per tweet
- CJK characters (Chinese/Japanese/Korean) count as **2** each
- URLs count as **23** each regardless of length
- Script auto-validates before posting; rejects if over limit

## Rate Limits

- **100 tweets / 15 min** per user (OAuth 1.0a)
- **3,000 tweets / month** on Basic plan ($200/mo)
- Check `remaining` field in output to monitor quota

## Tips

- For content from Notion/database: fetch the text first, then pipe to `tweet.js`
- For cron-based auto-posting: use `exec` with env vars set, parse JSON output to confirm success
- Thread mode posts sequentially; each tweet auto-replies to the previous one
- Combine `--thread` with `--reply-to` to attach a thread under an existing tweet

---

## 中文说明

# Twitter Post

使用 OAuth 1.0a 认证，通过官方 Twitter/X API v2 发布推文。

## 前置条件

必须设置四个环境变量。从 [developer.x.com](https://developer.x.com) 获取它们：

```
TWITTER_CONSUMER_KEY=<API Key>
TWITTER_CONSUMER_SECRET=<API Key Secret>
TWITTER_ACCESS_TOKEN=<Access Token>
TWITTER_ACCESS_TOKEN_SECRET=<Access Token Secret>
```

可选：
- `HTTPS_PROXY` —— HTTP 代理 URL（如 `http://127.0.0.1:7897`），供需要的地区使用
- `TWITTER_DRY_RUN=1` —— 校验并打印但不发布

## 设置

将凭据存储为环境变量。推荐：添加到 OpenClaw 实例配置或在 shell 配置文件中 export。**绝不在 SKILL.md 或脚本中硬编码密钥。**

如果用户尚未设置 OAuth，请引导他们：

1. 前往 [developer.x.com](https://developer.x.com) → Dashboard → Create App
2. 将 **App permissions** 设置为 **Read and Write**
3. 前往 **Keys and tokens** 标签页
4. 复制 API Key、API Key Secret
5. 生成 Access Token 和 Access Token Secret（确保为 Read+Write 范围）
6. 如果门户仅显示 Read，使用基于 PIN 的 OAuth 流程：
   - 以 `oauth_callback=oob` 调用 `POST /oauth/request_token`
   - 用户打开 `https://api.twitter.com/oauth/authorize?oauth_token=<token>`
   - 用户提供 PIN 码
   - 以 PIN 作为 `oauth_verifier` 调用 `POST /oauth/access_token`

## 用法

所有命令通过 `exec` 执行。脚本路径：`scripts/tweet.js`（相对于此 skill 目录）。

### 单条推文

```bash
node scripts/tweet.js "Your tweet content here"
```

### 回复推文

```bash
node scripts/tweet.js --reply-to 1234567890 "Reply text"
```

### 引用推文

```bash
node scripts/tweet.js --quote 1234567890 "Your commentary"
```

### 话题串（多条推文）

```bash
node scripts/tweet.js --thread "First tweet" "Second tweet" "Third tweet"
```

### 输出

向 stdout 输出 JSON：

```json
{"ok":true,"id":"123456789","url":"https://x.com/i/status/123456789","remaining":"99","limit":"100"}
```

出错时：`{"ok":false,"error":"..."}`

## 字符限制

- 每条推文最多 280 个加权字符
- CJK 字符（中文/日文/韩文）每个计为 **2**
- URL 无论长度每个计为 **23**
- 脚本在发布前自动校验；超限则拒绝

## 速率限制

- 每用户 **100 条推文 / 15 分钟**（OAuth 1.0a）
- Basic 套餐（200 美元/月）**3,000 条推文 / 月**
- 检查输出中的 `remaining` 字段以监控配额

## 提示

- 对于来自 Notion/数据库的内容：先获取文本，再通过管道传给 `tweet.js`
- 对于基于 cron 的自动发布：使用设置了环境变量的 `exec`，解析 JSON 输出以确认成功
- 话题串模式按顺序发布；每条推文自动回复上一条
- 将 `--thread` 与 `--reply-to` 结合，可将话题串挂在现有推文下方