Hermes Agent용 Hermes XAPI

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
대시보드의 Twexapi API 키

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

설치

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

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

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

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

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

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

~/.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 키를 설정하세요.

export TWEXAPI_KEY="twitterx_..."

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

TWEXAPI_KEY=twitterx_...

선택적 환경 변수:

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

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

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로 시작하세요.

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가 있으면 반환하세요.

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를 호출하세요.

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을 사용하세요.

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을 사용하세요. 무인 세션에서는 액션 도구를 비활성화 상태로 유지하세요.

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가 필요합니다.

hermes tools list

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

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 계약에서 번들 카탈로그를 재생성하세요.

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

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

확인

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

/xstatus

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

hermes tools list

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

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 계약을 사용하며 실시간 엔드포인트 호출 전에 에이전트 안전 카탈로그 발견을 노출합니다.