---
title: "Hermes Agent용 Hermes XAPI"
description: "Hermes Agent에서 Twexapi 기반 X/Twitter 자동화를 위해 Hermes XAPI 플러그인을 설치하고 구성합니다."
---

Hermes XAPI는 Twexapi를 구조화된 X/Twitter 자동화 도구 세트로 사용하기 위한 네이티브 Hermes Agent 플러그인입니다. Twexapi 엔드포인트 카탈로그, 읽기 도구, 선택적 액션 도구, 슬래시 명령 및 번들 Hermes 스킬을 Python 플러그인으로 패키징합니다.

Hermes Agent 워크플로에 X/Twitter 검색, 계정 읽기, 프로필 조회, 트렌드, 팔로워, 답글, 기사, DM, 트윗 게시, 좋아요, 리트윗, 팔로우 또는 계정 상태 확인이 필요할 때 Hermes XAPI를 사용하세요.

## 전제조건

- Python `3.11` 이상
- 플러그인 지원이 있는 Hermes Agent
- [대시보드](https://twexapi.io/dashboard)의 Twexapi API 키

Hermes 플러그인은 옵트인입니다. `hermes-xapi` 도구 세트가 나타나기를 기대하기 전에 플러그인을 설치하고 활성화하세요.

## 설치

공개 GitHub 저장소에 Hermes 플러그인 설치 프로그램을 사용하세요.

```bash
hermes plugins install twexapi-dev/hermes-xapi --enable
```

대화형 설치 중 Hermes는 `TWEXAPI_KEY`를 요청하고 `~/.hermes/.env`에 저장합니다. 비대화형 설치는 프롬프트를 건너뜁니다. `xapi_read`를 호출하기 전에 프로세스 환경 또는 `~/.hermes/.env`에 키를 설정하세요.

패키지 설치를 직접 관리할 때는 Hermes Python 환경에 게시된 PyPI 패키지를 설치하세요.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-xapi
hermes plugins enable hermes-xapi
```

Hermes Python 환경에 `pip`가 포함되어 있으면 이 경로도 유효합니다.

```bash
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-xapi
hermes plugins enable hermes-xapi
```

현재 패키지 버전은 `0.1.6`입니다. 플러그인 이름은 `hermes-xapi`이고 Python 진입점은 `hermes-xapi = hermes_xapi`입니다.

## 구성

Hermes를 시작하기 전에 Twexapi API 키를 설정하세요.

```bash
export TWEXAPI_KEY="twitterx_..."
```

지속적인 Hermes 세션을 위해 `~/.hermes/.env`에 키를 추가하세요.

```bash
TWEXAPI_KEY=twitterx_...
```

선택적 환경 변수:

```bash
export TWEXAPI_BASE_URL="https://api.twexapi.io"
export HERMES_XAPI_ENABLE_ACTIONS="false"
```

무인 세션에서는 `HERMES_XAPI_ENABLE_ACTIONS=false`를 유지하세요. 명시적 승인 단계가 있는 워크플로에서만 액션을 활성화하세요.

```bash
export HERMES_XAPI_ENABLE_ACTIONS="true"
```

`~/.hermes/.env`를 편집한 후 Hermes가 이미 실행 중이면 대화형 CLI 세션에서 `/reload`를 실행하거나, `xapi_read`를 호출하기 전에 게이트웨이 및 cron 세션을 재시작하세요.

## 도구

| 도구 | 목적 |
| --- | --- |
| `xapi_explore` | API 호출 없이 번들 Twexapi 엔드포인트 카탈로그를 검색합니다. 모든 실시간 엔드포인트 호출 전에 사용하세요. |
| `xapi_read` | `TWEXAPI_KEY`가 구성된 후 카탈로그에 나열된 읽기 전용 엔드포인트를 호출합니다. |
| `xapi_action` | `HERMES_XAPI_ENABLE_ACTIONS=true`일 때만 비공개, 유료 대량 또는 쓰기 유사 엔드포인트를 호출합니다. |

에이전트가 올바른 메서드, 경로, 매개변수, 응답 형태를 발견할 수 있도록 `xapi_explore`로 시작하세요.

```txt
Use xapi_explore to find the endpoint for user lookup, then call xapi_read for @username.
```

## 워크플로 핸드오프

`xapi_explore`를 먼저 사용한 다음 공개 읽기에는 `xapi_read`를, 상태를 생성하거나 변경하는 승인된 작업에는 `xapi_action`을 선택하세요.

### 트윗 검색 읽기

`/twitter/advanced_search/page` 또는 다른 카탈로그 검색 엔드포인트와 함께 `xapi_read`를 사용하세요. 트윗 ID, 텍스트, 작성자 사용자명, 타임스탬프, 참여 지표, `has_more`, `next_cursor`가 있으면 반환하세요.

```txt
Use xapi_explore to find tweet search endpoints.
Use xapi_read for /twitter/advanced_search/page with searchTerms ["AI agents"] and maxItems 25.
Return tweet_id, text, author_username, created_at, and engagement counts.
```

### 트렌드 연구

트렌드 경로를 찾기 위해 `xapi_explore`를 사용한 다음 국가, 주제, 콘텐츠 또는 트렌드 엔드포인트에 `xapi_read`를 호출하세요.

```txt
Use xapi_explore to find X/Twitter trend endpoints.
Use xapi_read to return current trends for worldwide.
Preserve the country, topic, content, rank, has_more, and next_cursor fields when present.
```

### 팔로워 내보내기

팔로워 엔드포인트를 찾기 위해 `xapi_explore`를 사용하세요. 제한된 읽기에는 `xapi_read`를, 카탈로그가 경로를 비공개, 유료 대량 또는 액션 유사로 표시할 때만 `xapi_action`을 사용하세요.

```txt
Use xapi_explore to find follower export endpoints.
Fetch followers for @username with a bounded count.
If the response returns a task_id, store it and poll the documented status and next-page routes.
```

### 제어된 쓰기 작업

승인 후에만 `xapi_action`을 사용하세요. 무인 세션에서는 액션 도구를 비활성화 상태로 유지하세요.

```txt
Use xapi_explore with include_actions true to find tweet posting endpoints.
Draft the exact request body.
Ask for explicit approval.
Only after approval, call xapi_action.
Return tweet_id, status, charged_credits, and any write action ID.
```

## 런타임 진단

스크립트 가능한 확인에는 `hermes tools list`를 사용하세요. `hermes tools`만 실행하면 대화형 도구 UI가 열리며 TTY가 필요합니다.

```bash
hermes tools list
```

플러그인 활성화 후 변경하지 않는 일회성 프로브를 실행하세요.

```bash
hermes -z "Use xapi_explore, then read /twitter/elonmusk/about. Do not call xapi_action." --toolsets hermes-xapi
```

예상 동작:

- `xapi_explore`는 API 키 없이 카탈로그 엔드포인트를 검사할 수 있습니다.
- `TWEXAPI_KEY` 없이는 변경하지 않는 Hermes 프로브가 `xapi_explore`만 노출합니다.
- `TWEXAPI_KEY`가 구성되고 CLI가 다시 로드되거나 게이트웨이/cron 프로세스가 재시작된 후 `xapi_read`가 `/twitter/elonmusk/about`을 읽을 수 있습니다.
- `HERMES_XAPI_ENABLE_ACTIONS=true`가 아니면 `xapi_action`은 숨겨지거나 비활성화됩니다.
- `/xstatus` 및 `/xtrends`가 Hermes 플러그인 명령 레지스트리에 나타납니다.

Hermes 일회성 프롬프트는 `/xstatus`를 대화형 슬래시 명령으로 디스패치하지 않습니다. 활성 CLI, TUI, Desktop 또는 게이트웨이 세션에서 슬래시 명령을 확인하고 도구 호출 프로브에는 `hermes -z`를 사용하세요.

비대화형 설치는 자격 증명을 프롬프트할 수 없습니다. 프로세스 환경 또는 `~/.hermes/.env`에 `TWEXAPI_KEY`를 설정하세요.

## 슬래시 명령

| 명령 | 목적 |
| --- | --- |
| `/xstatus` | 활성 Hermes 세션에서 Twexapi 계정, 구독 및 사용 상태를 표시합니다. |
| `/xtrends` | 플러그인 명령 레지스트리에서 현재 X/Twitter 트렌드를 표시합니다. |

## 안전 모델

Hermes XAPI는 환경 변수에서 인증을 읽고 요청 시점에 주입합니다. 모델은 API 키를 도구 인수로 받지 않습니다.

플러그인은 에이전트 카탈로그에서 쿠키/토큰 헬퍼 경로, 참여 구매 경로, 자동 쿠키 게시, 프로필 변경, 목록 생성, 감정 분석 경로를 차단합니다. 비공개 읽기, 유료 대량 엔드포인트, 쓰기 유사 엔드포인트는 `HERMES_XAPI_ENABLE_ACTIONS=true`가 아니면 숨겨진 `xapi_action`을 통해 진행됩니다.

무인 작업에서는 액션 도구를 비활성화하고 `xapi_explore`와 `xapi_read`만 사용하세요.

## API 범위

Hermes XAPI에는 OpenAPI 계약에서 생성된 76개의 에이전트 호출 가능 Twexapi 엔드포인트가 포함됩니다.

| 영역 | 일반적인 용도 |
| --- | --- |
| 공개 읽기 | 트윗 검색, 트윗 조회, 사용자 조회, 타임라인, 기사, 답글, 트렌드 |
| 비공개 읽기 | 계정 상태, 잔액, 계정 수준 확인 |
| 관계 데이터 | 팔로워, 팔로잉, 리트윗한 사용자, 인용 트윗, 좋아요한 사용자 |
| 커뮤니티 및 목록 | 커뮤니티 메타데이터, 멤버, 트윗, 목록 트윗, 구독자, 멤버 |
| 액션 | 활성화 시 트윗, 답글, 좋아요, 리트윗, 팔로우, DM, 미디어, 북마크, 기사, 계정 작업 |

## 로컬 개발

로컬 플러그인 개발을 위해 Twexapi OpenAPI 계약에서 번들 카탈로그를 재생성하세요.

```bash
python scripts/build_catalog.py ../twexapi/openapi.yaml
```

Twexapi OpenAPI 파일이 변경된 후 `hermes-xapi` 저장소에서 이 명령을 실행하세요.

## 확인

설치, 활성화 및 `TWEXAPI_KEY` 설정 후 실행하세요.

```txt
/xstatus
```

스크립트 가능한 진단을 위해 플러그인 도구 세트를 나열하세요.

```bash
hermes tools list
```

그다음 읽기 워크플로를 테스트하세요.

```txt
Use xapi_explore to find X/Twitter trends, then use xapi_read to return current trends.
```

액션 워크플로에서는 `xapi_action`을 활성화하기 전에 명시적 초안 및 승인 단계를 요구하세요.

## 문제 해결

| 문제 | 해결 |
| --- | --- |
| 도구 누락 | `hermes plugins enable hermes-xapi`를 실행한 다음 `hermes tools list`에 `hermes-xapi`가 나타나는지 확인하세요. |
| 인증 실패 | Hermes를 시작하는 동일 환경에 `TWEXAPI_KEY`가 내보내졌거나 `~/.hermes/.env`에 저장되었는지 확인하세요. |
| 환경 변경 미반영 | 대화형 CLI에서 `/reload`를 실행하거나 게이트웨이 및 cron 세션을 재시작하세요. |
| 액션 도구 숨김 | 승인된 액션 워크플로에서만 `HERMES_XAPI_ENABLE_ACTIONS=true`를 설정하세요. |
| 엔드포인트 누락 | 로컬 개발에서 현재 Twexapi OpenAPI 파일에서 카탈로그를 재생성하세요. |
| 위험한 쓰기 | `HERMES_XAPI_ENABLE_ACTIONS=false`를 유지하고 읽기 도구만 사용하세요. |

## XApiClaw와의 관계

XApiClaw는 OpenClaw 네이티브 npm 플러그인입니다. Hermes XAPI는 Hermes 네이티브 Python 플러그인입니다. 둘 다 동일한 Twexapi API 계약을 사용하며 실시간 엔드포인트 호출 전에 에이전트 안전 카탈로그 발견을 노출합니다.

## 참고 자료

- [Hermes XAPI GitHub repo](https://github.com/twexapi-dev/hermes-xapi)
- [Hermes XAPI on PyPI](https://pypi.org/project/hermes-xapi/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
- 사이드바의 API Reference
- [MCP Server](/mcp/overview)