---
title: "Paperclip"
description: "安装 TwexAPI Paperclip 插件，在 Paperclip AI Agent中实现推文搜索、资料查询、时间线与热门推文。"
---

TwexAPI Paperclip 插件为 [Paperclip](https://paperclip.ai) AI Agent增加六个只读 Twitter/X 工具。它包装已文档化的 TwexAPI REST 路由，提供类型化工具 schema、密钥认证与可预测的 JSON 结果。

当 Paperclip AI Agent需要推文搜索、资料查询、用户搜索、时间线读取或全球热门推文且无需手写原始 HTTP 时，使用该插件。

## 工具

| AI Agent任务 | Paperclip 工具 | TwexAPI 路由 |
| --- | --- | --- |
| 搜索推文 | `twexapi.search_tweets` | `POST /twitter/advanced_search/page` |
| 读取单条推文 | `twexapi.lookup_tweet` | `POST /v2/tweet/detail` |
| 搜索用户 | `twexapi.search_users` | `GET /twitter/search-user/{keyword}/{target_count}` |
| 读取资料 | `twexapi.get_user` | `GET /twitter/{screen_name}/about` |
| 读取资料推文 | `twexapi.get_user_tweets` | `POST /twitter/{screen_name}/timeline/page` |
| 读取热门推文 | `twexapi.get_trends` | `GET /twitter/global-trending/tweets` |

本插件不导出粉丝或发布帖子。粉丝与发布请用 [REST API](/api-reference/overview)、[CLI](/sdks/cli) 或 [MCP Server](/mcp/overview)。

## 前置条件

- Node.js 18 或更新版本
- Paperclip CLI（`paperclipai`）
- 来自 [dashboard](https://twexapi.io/dashboard) 的 TwexAPI API 密钥
- 用于 API 密钥的 Paperclip 密钥引用

## 安装

```bash
paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper
```

需要可重复安装时固定当前发布版本：

```bash
paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper --version 0.1.2
```

npm：[@twexapi-dev/paperclip-plugin-x-api-scraper](https://www.npmjs.com/package/@twexapi-dev/paperclip-plugin-x-api-scraper)

源码：[twexapi-dev/paperclip-plugin-x-api-scraper](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)

## 配置

在 [TwexAPI dashboard](https://twexapi.io/dashboard) 创建 API 密钥，存入 Paperclip 密钥并在插件配置中引用。

| 设置 | 用途 |
| --- | --- |
| `apiBaseUrl` | TwexAPI REST 端点。默认 `https://api.twexapi.io`。 |
| `apiKeySecretRef` | TwexAPI API 密钥的 Paperclip 密钥引用。 |
| `defaultTimelineCount` | 默认时间线页数，1 至 100。 |
| `defaultUserSearchCount` | 默认用户搜索数量，1 至 100。 |
| `defaultTrendCount` | 默认趋势数量，1 至 100。 |

Paperclip 在调用时解析 API 密钥并发送 `Authorization: Bearer`。

示例插件配置形状：

```json
{
  "apiBaseUrl": "https://api.twexapi.io",
  "apiKeySecretRef": "twexapi/api-key",
  "defaultTimelineCount": 20,
  "defaultUserSearchCount": 10,
  "defaultTrendCount": 20
}
```

切勿将 API 密钥提交到纳入源码控制的插件配置文件。

## 示例AI Agent任务

### 搜索推文

让AI Agent搜索某话题的近期帖子。插件通过 `twexapi.search_tweets` 调用 `POST /twitter/advanced_search/page`。

建议 prompt：

```text
Search X for recent posts about "AI agents lang:en -filter:retweets".
Return tweet IDs, author usernames, text, and created_at for the top 10 results.
```

### 读取资料与时间线

```text
Look up @openai, then read the latest timeline page.
Return username, user_id, follower count, and the 5 most recent tweet IDs.
```

### 读取全球热门推文

```text
Get trending tweets for United States, topic Sports, content NFL.
Summarize the top themes and list 5 representative tweet IDs.
```

## Handoff 清单

Paperclip AI Agent将结果交给下游系统时，保留稳定标识符。

| 数据类型 | 存储 |
| --- | --- |
| 推文 | `tweet_id`、`text`、`author_username`、`created_at`、搜索查询 |
| 资料 | `user_id`、`username`、`name`、粉丝数 |
| 趋势 | 国家、主题、内容标签、推文行 |
| 分页 | `next_cursor`、`has_more`、原始请求参数 |

同一工作流中混合 Paperclip 工具与基于 MCP 的AI Agent 时，见 [Agent MCP Handoff](/mcp/agent-handoff)。

## 错误处理

| 状态 | 操作 |
| ------ | ------ |
| `400` | 修正工具输入。切勿原样重试。 |
| `401` | 检查 Paperclip 密钥引用与 API 密钥值。 |
| `403` | 检查账号访问与额度。 |
| `429` | 重试前退避。 |
| `5xx` | 有界退避重试。 |

## 本地开发

```bash
git clone https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper.git
cd paperclip-plugin-x-api-scraper
pnpm install
pnpm check
```

`pnpm check` 运行类型检查、测试与构建。

## 相关指南

* [MCP Server](/mcp/overview)
* [CLI](/sdks/cli)
* [TypeScript SDK](/sdks/typescript)
* [OpenAPI schema](https://docs.twexapi.io/openapi.json)
* [Source repository](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)