Hermes XAPI para Hermes Agent

Instala y configura el plugin Hermes XAPI para automatización de X/Twitter con Twexapi en Hermes Agent.

Hermes XAPI es el plugin nativo de Hermes Agent para usar Twexapi como un conjunto estructurado de herramientas de automatización de X/Twitter. Empaqueta el catálogo de endpoints de Twexapi, herramientas de lectura, herramientas de acción opcionales, comandos slash y una skill de Hermes incluida en un plugin de Python.

Usa Hermes XAPI cuando un flujo de trabajo de Hermes Agent necesite búsqueda de X/Twitter, lecturas de cuenta, consultas de perfiles, tendencias, seguidores, respuestas, artículos, DMs, publicación de tweets, likes, retweets, follows o verificaciones de estado de cuenta.

Requisitos previos

Python 3.11 o posterior
Hermes Agent con soporte de plugins
Una API key de Twexapi desde el panel

Los plugins de Hermes son opt-in. Instala y habilita el plugin antes de esperar que aparezca el toolset hermes-xapi.

Instalación

Usa el instalador de plugins de Hermes para el repositorio público de GitHub:

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

Hermes solicita TWEXAPI_KEY durante una instalación interactiva y la guarda en ~/.hermes/.env. Las instalaciones no interactivas omiten el prompt. Configura la key en el entorno del proceso o en ~/.hermes/.env antes de llamar a xapi_read.

Instala el paquete publicado de PyPI directamente en el entorno Python de Hermes cuando gestiones la instalación de paquetes tú mismo:

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

Si tu entorno Python de Hermes incluye pip, esta ruta también es válida:

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

La versión actual del paquete es 0.1.6. El nombre del plugin es hermes-xapi y el punto de entrada de Python es hermes-xapi = hermes_xapi.

Configuración

Configura tu API key de Twexapi antes de iniciar Hermes:

export TWEXAPI_KEY="twitterx_..."

Para sesiones persistentes de Hermes, agrega la key a ~/.hermes/.env:

TWEXAPI_KEY=twitterx_...

Variables de entorno opcionales:

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

Mantén HERMES_XAPI_ENABLE_ACTIONS=false para sesiones desatendidas. Habilita acciones solo para flujos de trabajo con un paso de aprobación explícito:

export HERMES_XAPI_ENABLE_ACTIONS="true"

Si Hermes ya está en ejecución después de editar ~/.hermes/.env, ejecuta /reload en una sesión CLI interactiva o reinicia las sesiones de gateway y cron antes de llamar a xapi_read.

Herramientas

Herramienta	Propósito
`xapi_explore`	Busca en el catálogo de endpoints de Twexapi incluido sin hacer una llamada API. Úsala antes de cada llamada a endpoint en vivo.
`xapi_read`	Llama a endpoints de solo lectura listados en el catálogo después de configurar `TWEXAPI_KEY`.
`xapi_action`	Llama a endpoints privados, bulk de pago o similares a escritura solo cuando `HERMES_XAPI_ENABLE_ACTIONS=true`.

Comienza con xapi_explore para que el agente pueda descubrir el método, ruta, parámetros y forma de respuesta correctos antes de llamar a un endpoint.

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

Entregas de flujo de trabajo

Usa xapi_explore primero, luego elige xapi_read para lecturas públicas o xapi_action para trabajos aprobados que crean o cambian estado.

Lectura de búsqueda de tweets

Usa xapi_read con /twitter/advanced_search/page u otro endpoint de búsqueda listado en el catálogo. Devuelve IDs de tweet, texto, nombres de usuario de autor, marcas de tiempo, métricas de engagement, has_more y next_cursor cuando estén presentes.

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.

Investigación de tendencias

Usa xapi_explore para encontrar rutas de tendencias, luego llama a xapi_read para endpoints de país, tema, contenido o tendencia.

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.

Exportación de seguidores

Usa xapi_explore para encontrar endpoints de seguidores. Usa xapi_read para lecturas acotadas y xapi_action solo cuando el catálogo marque la ruta como privada, bulk de pago o similar a acción.

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.

Acción de escritura controlada

Usa xapi_action solo después de aprobación. Mantén las herramientas de acción deshabilitadas en sesiones desatendidas.

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.

Diagnósticos de runtime

Para verificaciones scriptables, usa hermes tools list. hermes tools sin argumentos abre la UI interactiva de herramientas y requiere un TTY.

hermes tools list

Ejecuta una sonda one-shot no mutante después de habilitar el plugin:

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

Comportamiento esperado:

xapi_explore puede inspeccionar endpoints del catálogo sin una API key.
Sin TWEXAPI_KEY, una sonda de Hermes no mutante expone solo xapi_explore.
Después de configurar TWEXAPI_KEY y recargar el CLI, o reiniciar el proceso de gateway o cron, xapi_read puede leer /twitter/elonmusk/about.
xapi_action permanece oculta o deshabilitada a menos que HERMES_XAPI_ENABLE_ACTIONS=true.
/xstatus y /xtrends aparecen en el registro de comandos del plugin de Hermes.

Los prompts one-shot de Hermes no despachan /xstatus como comando slash interactivo. Verifica comandos slash en una sesión activa de CLI, TUI, Desktop o gateway, y usa hermes -z para sondas de llamadas a herramientas.

Las instalaciones no interactivas no pueden solicitar credenciales; configura TWEXAPI_KEY en el entorno del proceso o en ~/.hermes/.env.

Comandos slash

Comando	Propósito
`/xstatus`	Muestra cuenta, suscripción y estado de uso de Twexapi en una sesión activa de Hermes.
`/xtrends`	Muestra tendencias actuales de X/Twitter desde el registro de comandos del plugin.

Modelo de seguridad

Hermes XAPI lee la autenticación desde variables de entorno y la inyecta al momento de la solicitud. El modelo no recibe la API key como argumento de herramienta.

El plugin bloquea rutas helper de cookie/token, rutas de compra de engagement, publicación con cookie automática, mutación de perfil, creación de listas y rutas de sentimiento del catálogo del agente. Las lecturas privadas, endpoints bulk de pago y endpoints similares a escritura pasan por xapi_action, que permanece oculta a menos que HERMES_XAPI_ENABLE_ACTIONS=true.

Para trabajos desatendidos, mantén las herramientas de acción deshabilitadas y usa solo xapi_explore más xapi_read.

Cobertura de API

Hermes XAPI incluye 76 endpoints de Twexapi invocables por agentes generados desde el contrato OpenAPI.

Área	Usos comunes
Lecturas públicas	Búsqueda de tweets, consulta de tweets, consulta de usuarios, líneas de tiempo, artículos, respuestas y tendencias.
Lecturas privadas	Estado de cuenta, saldo y verificaciones a nivel de cuenta.
Datos de relaciones	Seguidores, following, retweeters, tweets citados y favoriters.
Comunidades y listas	Metadatos de comunidad, miembros, tweets, tweets de listas, suscriptores y miembros.
Acciones	Tweet, respuesta, like, retweet, follow, DM, multimedia, bookmarks, artículos y operaciones de cuenta cuando están habilitadas.

Desarrollo local

Para desarrollo local del plugin, regenera el catálogo incluido desde el contrato OpenAPI de Twexapi:

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

Ejecuta ese comando desde el repositorio hermes-xapi después de que cambie el archivo OpenAPI de Twexapi.

Verificación

Después de instalar, habilitar y configurar TWEXAPI_KEY, ejecuta:

/xstatus

Para diagnósticos scriptables, lista el toolset del plugin:

hermes tools list

Luego prueba un flujo de trabajo de lectura:

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

Para flujos de acción, requiere un borrador explícito y un paso de aprobación antes de habilitar xapi_action.

Solución de problemas

Problema	Solución
Herramientas faltantes	Ejecuta `hermes plugins enable hermes-xapi`, luego confirma que `hermes-xapi` aparezca en `hermes tools list`.
Fallo de autenticación	Confirma que `TWEXAPI_KEY` esté exportada en el mismo entorno que inicia Hermes, o guardada en `~/.hermes/.env`.
Cambios de entorno no detectados	Ejecuta `/reload` en el CLI interactivo, o reinicia las sesiones de gateway y cron.
Herramienta de acción oculta	Configura `HERMES_XAPI_ENABLE_ACTIONS=true` solo para flujos de trabajo de acción aprobados.
Endpoint faltante	Regenera el catálogo desde el archivo OpenAPI actual de Twexapi en desarrollo local.
Escrituras riesgosas	Mantén `HERMES_XAPI_ENABLE_ACTIONS=false` y usa solo herramientas de lectura.

Relación con XApiClaw

XApiClaw es el plugin npm nativo de OpenClaw. Hermes XAPI es el plugin Python nativo de Hermes. Ambos usan el mismo contrato API de Twexapi y exponen descubrimiento de catálogo seguro para agentes antes de llamadas a endpoints en vivo.