---
title: "Paperclip"
description: "Paperclip 에이전트에서 트윗 검색, 프로필, 타임라인, 트렌딩 트윗을 위해 TwexAPI Paperclip 플러그인을 설치합니다."
---

TwexAPI Paperclip 플러그인은 [Paperclip](https://paperclip.ai) 에이전트에 6개의 읽기 전용 Twitter/X 도구를 추가합니다. 문서화된 TwexAPI REST 경로를 타입 도구 스키마, 시크릿 기반 인증, 예측 가능한 JSON 결과로 래핑합니다.

Paperclip 에이전트가 원시 HTTP 호출 없이 트윗 검색, 프로필 조회, 사용자 검색, 타임라인 읽기, 글로벌 트렌딩 트윗이 필요할 때 이 플러그인을 사용하세요.

## 도구

| 에이전트 작업 | Paperclip 도구 | TwexAPI 경로 |
| --- | --- | --- |
| 트윗 검색 | `twexapi.search_tweets` | `POST /twitter/advanced_search/page` |
| 트윗 1개 읽기 | `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 서버](/mcp/overview)를 사용하세요.

## 전제조건

- Node.js 18 이상
- Paperclip CLI (`paperclipai`)
- [대시보드](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 대시보드](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 키를 커밋하지 마세요.

## 에이전트 작업 예제

### 트윗 검색

에이전트에게 주제에 대한 최근 게시물을 검색하도록 요청합니다. 플러그인은 `twexapi.search_tweets`를 통해 `POST /twitter/advanced_search/page`를 호출합니다.

권장 프롬프트:

```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.
```

## 핸드오프 체크리스트

Paperclip 에이전트가 결과를 다운스트림 시스템에 핸드오프할 때 안정적인 식별자를 보존하세요.

| 데이터 유형 | 저장 |
| --- | --- |
| 트윗 | `tweet_id`, `text`, `author_username`, `created_at`, 검색 쿼리 |
| 프로필 | `user_id`, `username`, `name`, 팔로워 수 |
| 트렌드 | 국가, 주제, 콘텐츠 태그, 트윗 행 |
| 페이지네이션 | `next_cursor`, `has_more`, 원본 요청 매개변수 |

동일한 워크플로에서 Paperclip 도구와 MCP 기반 에이전트를 혼합할 때는 [에이전트 MCP 핸드오프](/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 서버](/mcp/overview)
* [CLI](/sdks/cli)
* [TypeScript SDK](/sdks/typescript)
* [OpenAPI 스키마](https://docs.twexapi.io/openapi.json)
* [소스 저장소](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)