---
title: "Hermes XAPI para Hermes Agent"
description: "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](https://twexapi.io/dashboard)

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:

```bash
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:

```bash
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:

```bash
~/.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:

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

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

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

Variables de entorno opcionales:

```bash
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:

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

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

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

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

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

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

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

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

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

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

```bash
hermes tools list
```

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

```bash
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:

```bash
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:

```txt
/xstatus
```

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

```bash
hermes tools list
```

Luego prueba un flujo de trabajo de lectura:

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

## Referencias

- [Repositorio GitHub de Hermes XAPI](https://github.com/twexapi-dev/hermes-xapi)
- [Hermes XAPI en PyPI](https://pypi.org/project/hermes-xapi/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
- API Reference en la barra lateral
- [MCP Server](/mcp/overview)