---
title: "Hermes XAPI pour Hermes Agent"
description: "Installez et configurez le plugin Hermes XAPI pour l'automatisation X/Twitter via Twexapi dans Hermes Agent."
---

Hermes XAPI est le plugin natif Hermes Agent pour utiliser Twexapi comme ensemble d'outils structurés d'automatisation X/Twitter. Il regroupe le catalogue d'endpoints Twexapi, les outils de lecture, les outils d'action optionnels, les commandes slash et une skill Hermes intégrée dans un plugin Python.

Utilisez Hermes XAPI lorsqu'un workflow Hermes Agent a besoin de recherche X/Twitter, de lectures de compte, de lookups de profil, de tendances, d'abonnés, de réponses, d'articles, de DMs, de publication de tweets, de likes, de retweets, de follows ou de vérifications de statut de compte.

## Prérequis

- Python `3.11` ou plus récent
- Hermes Agent avec support des plugins
- Une clé API Twexapi depuis le [tableau de bord](https://twexapi.io/dashboard)

Les plugins Hermes sont opt-in. Installez et activez le plugin avant d'attendre l'apparition du toolset `hermes-xapi`.

## Installation

Utilisez l'installateur de plugins Hermes pour le dépôt GitHub public :

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

Hermes demande `TWEXAPI_KEY` lors d'une installation interactive et la stocke dans `~/.hermes/.env`. Les installations non interactives ignorent la demande. Définissez la clé dans l'environnement du processus ou `~/.hermes/.env` avant d'appeler `xapi_read`.

Installez le package PyPI publié directement dans l'environnement Python Hermes lorsque vous gérez l'installation des packages vous-même :

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

Si votre environnement Python Hermes inclut `pip`, ce chemin est également valide :

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

La version actuelle du package est `0.1.6`. Le nom du plugin est `hermes-xapi`, et le point d'entrée Python est `hermes-xapi = hermes_xapi`.

## Configuration

Définissez votre clé API Twexapi avant de démarrer Hermes :

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

Pour des sessions Hermes persistantes, ajoutez la clé à `~/.hermes/.env` :

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

Variables d'environnement optionnelles :

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

Gardez `HERMES_XAPI_ENABLE_ACTIONS=false` pour les sessions sans surveillance. Activez les actions uniquement pour les workflows avec une étape d'approbation explicite :

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

Si Hermes est déjà en cours d'exécution après modification de `~/.hermes/.env`, exécutez `/reload` dans une session CLI interactive, ou redémarrez les sessions gateway et cron avant d'appeler `xapi_read`.

## Outils

| Outil | Objectif |
| --- | --- |
| `xapi_explore` | Recherchez dans le catalogue d'endpoints Twexapi intégré sans appel API. Utilisez-le avant chaque appel d'endpoint en direct. |
| `xapi_read` | Appelez les endpoints en lecture seule listés dans le catalogue après configuration de `TWEXAPI_KEY`. |
| `xapi_action` | Appelez les endpoints privés, paid-bulk ou de type écriture uniquement lorsque `HERMES_XAPI_ENABLE_ACTIONS=true`. |

Commencez par `xapi_explore` pour que l'agent puisse découvrir la méthode, le chemin, les paramètres et la forme de réponse avant d'appeler un endpoint.

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

## Handoffs de workflow

Utilisez `xapi_explore` en premier, puis choisissez `xapi_read` pour les lectures publiques ou `xapi_action` pour les jobs approuvés qui créent ou modifient l'état.

### Lecture de recherche de tweets

Utilisez `xapi_read` avec `/twitter/advanced_search/page` ou un autre endpoint de recherche listé dans le catalogue. Retournez les ID de tweet, le texte, les usernames d'auteur, les horodatages, les métriques d'engagement, `has_more` et `next_cursor` si présents.

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

### Recherche de tendances

Utilisez `xapi_explore` pour trouver les routes de tendances, puis appelez `xapi_read` pour les endpoints country, topic, content ou trend.

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

### Export d'abonnés

Utilisez `xapi_explore` pour trouver les endpoints d'abonnés. Utilisez `xapi_read` pour les lectures bornées et `xapi_action` uniquement lorsque le catalogue marque la route comme privée, paid-bulk ou de type 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.
```

### Action d'écriture contrôlée

Utilisez `xapi_action` uniquement après approbation. Gardez les outils d'action désactivés dans les sessions sans surveillance.

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

## Diagnostics runtime

Pour des vérifications scriptables, utilisez `hermes tools list`. `hermes tools` seul ouvre l'UI interactive des outils et nécessite un TTY.

```bash
hermes tools list
```

Exécutez une sonde one-shot non mutante après activation du plugin :

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

Comportement attendu :

- `xapi_explore` peut inspecter les endpoints du catalogue sans clé API.
- Sans `TWEXAPI_KEY`, une sonde Hermes non mutante expose uniquement `xapi_explore`.
- Après configuration de `TWEXAPI_KEY` et rechargement du CLI, ou redémarrage du processus gateway ou cron, `xapi_read` peut lire `/twitter/elonmusk/about`.
- `xapi_action` reste masqué ou désactivé sauf si `HERMES_XAPI_ENABLE_ACTIONS=true`.
- `/xstatus` et `/xtrends` apparaissent dans le registre de commandes du plugin Hermes.

Les prompts one-shot Hermes ne dispatch pas `/xstatus` comme commande slash interactive. Vérifiez les commandes slash dans une session CLI, TUI, Desktop ou gateway active, et utilisez `hermes -z` pour les sondes d'appels d'outils.

Les installations non interactives ne peuvent pas demander des identifiants ; définissez `TWEXAPI_KEY` dans l'environnement du processus ou `~/.hermes/.env`.

## Commandes slash

| Commande | Objectif |
| --- | --- |
| `/xstatus` | Affiche le statut de compte, souscription et utilisation Twexapi dans une session Hermes active. |
| `/xtrends` | Affiche les tendances X/Twitter actuelles depuis le registre de commandes du plugin. |

## Modèle de sécurité

Hermes XAPI lit l'authentification depuis les variables d'environnement et l'injecte au moment de la requête. Le modèle ne reçoit pas la clé API comme argument d'outil.

Le plugin bloque les routes helper cookie/token, les routes d'achat d'engagement, la publication auto-cookie, la mutation de profil, la création de listes et les routes de sentiment du catalogue agent. Les lectures privées, endpoints paid-bulk et endpoints de type écriture passent par `xapi_action`, qui reste masqué sauf si `HERMES_XAPI_ENABLE_ACTIONS=true`.

Pour les jobs sans surveillance, gardez les outils d'action désactivés et utilisez uniquement `xapi_explore` plus `xapi_read`.

## Couverture API

Hermes XAPI inclut 76 endpoints Twexapi appelables par agent générés depuis le contrat OpenAPI.

| Domaine | Usages courants |
| --- | --- |
| Lectures publiques | Recherche de tweets, lookup de tweet, lookup utilisateur, timelines, articles, réponses et tendances. |
| Lectures privées | Statut de compte, solde et vérifications au niveau du compte. |
| Données relationnelles | Abonnés, following, retweeters, tweets cités et favorisateurs. |
| Communautés et listes | Métadonnées de communauté, membres, tweets, tweets de liste, abonnés et membres. |
| Actions | Tweet, réponse, like, retweet, follow, DM, médias, bookmarks, articles et opérations de compte si activées. |

## Développement local

Pour le développement local du plugin, régénérez le catalogue intégré depuis le contrat OpenAPI Twexapi :

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

Exécutez cette commande depuis le dépôt `hermes-xapi` après modification du fichier OpenAPI Twexapi.

## Vérification

Après installation, activation et définition de `TWEXAPI_KEY`, exécutez :

```txt
/xstatus
```

Pour des diagnostics scriptables, listez le toolset du plugin :

```bash
hermes tools list
```

Puis testez un workflow de lecture :

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

Pour les workflows d'action, exigez une étape explicite de draft et d'approbation avant d'activer `xapi_action`.

## Dépannage

| Problème | Solution |
| --- | --- |
| Outils manquants | Exécutez `hermes plugins enable hermes-xapi`, puis confirmez que `hermes-xapi` apparaît dans `hermes tools list`. |
| Échec d'auth | Confirmez que `TWEXAPI_KEY` est exportée dans le même environnement qui démarre Hermes, ou stockée dans `~/.hermes/.env`. |
| Changements d'env non pris en compte | Exécutez `/reload` dans le CLI interactif, ou redémarrez les sessions gateway et cron. |
| Outil d'action masqué | Définissez `HERMES_XAPI_ENABLE_ACTIONS=true` uniquement pour les workflows d'action approuvés. |
| Endpoint manquant | Régénérez le catalogue depuis le fichier OpenAPI Twexapi actuel en développement local. |
| Écritures risquées | Gardez `HERMES_XAPI_ENABLE_ACTIONS=false` et utilisez uniquement les outils de lecture. |

## Relation avec XApiClaw

XApiClaw est le plugin npm natif OpenClaw. Hermes XAPI est le plugin Python natif Hermes. Les deux utilisent le même contrat API Twexapi et exposent une découverte de catalogue sûre pour l'agent avant les appels d'endpoint en direct.

## Références

- [Dépôt GitHub Hermes XAPI](https://github.com/twexapi-dev/hermes-xapi)
- [Hermes XAPI sur PyPI](https://pypi.org/project/hermes-xapi/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
- API Reference dans la barre latérale
- [Serveur MCP](/mcp/overview)