Hermes XAPI pour Hermes Agent

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

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 :

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 :

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 :

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

export TWEXAPI_KEY="twitterx_..."

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

TWEXAPI_KEY=twitterx_...

Variables d’environnement optionnelles :

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 :

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.

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.

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.

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.

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.

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.

hermes tools list

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

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 :

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 :

/xstatus

Pour des diagnostics scriptables, listez le toolset du plugin :

hermes tools list

Puis testez un workflow de lecture :

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.