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 を呼び出す前に gateway と 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 を選択します。

ツイート検索読み取り

xapi_read で /twitter/advanced_search/page またはカタログ掲載の別検索エンドポイントを使用します。ツイート 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 をリロードするか gateway または cron プロセスを再起動すると、xapi_read で /twitter/elonmusk/about を読み取り可能。
HERMES_XAPI_ENABLE_ACTIONS=true でない限り、xapi_action は非表示または無効。
/xstatus と /xtrends が Hermes プラグインコマンドレジストリに表示。

Hermes ワンショットプロンプトは /xstatus を対話型スラッシュコマンドとしてディスパッチしません。アクティブな CLI、TUI、Desktop、gateway セッションでスラッシュコマンドを確認し、ツール呼び出しプローブには hermes -z を使用してください。

非対話型インストールは認証情報をプロンプトできません。プロセス環境または ~/.hermes/.env に TWEXAPI_KEY を設定してください。

スラッシュコマンド

コマンド	用途
`/xstatus`	アクティブな Hermes セッションで Twexapi アカウント、サブスクリプション、使用状況を表示。
`/xtrends`	プラグインコマンドレジストリから現在の X/Twitter トレンドを表示。

安全モデル

Hermes XAPI は環境変数から認証を読み取り、リクエスト時に注入します。モデルは API キーをツール引数として受け取りません。

プラグインは cookie/token ヘルパールート、エンゲージメント購入ルート、自動 cookie 投稿、プロフィール変更、リスト作成、センチメントルートをエージェントカタログからブロックします。非公開読み取り、有料バルクエンドポイント、書き込み系エンドポイントは xapi_action 経由で、HERMES_XAPI_ENABLE_ACTIONS=true でない限り非表示です。

無人ジョブではアクションツールを無効のまま、xapi_explore と xapi_read のみを使用してください。

API カバレッジ

Hermes XAPI には OpenAPI 契約から生成された76のエージェント呼び出し可能 Twexapi エンドポイントが含まれます。

Area	Common uses
公開読み取り	ツイート検索、ツイート参照、ユーザー参照、タイムライン、記事、返信、トレンド。
非公開読み取り	アカウントステータス、残高、アカウントレベルチェック。
リレーションデータ	フォロワー、フォロー、リツイーター、引用ツイート、いいねしたユーザー。
コミュニティとリスト	コミュニティメタデータ、メンバー、ツイート、リストツイート、購読者、メンバー。
アクション	有効化時のツイート、返信、いいね、リツイート、フォロー、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` が表示されることを確認。
認証失敗	`TWEXAPI_KEY` が Hermes を起動する同じ環境にエクスポートされているか、`~/.hermes/.env` に保存されていることを確認。
環境変更が反映されない	対話型 CLI で `/reload` を実行するか、gateway と cron セッションを再起動。
アクションツールが非表示	承認済みアクションワークフローのみ `HERMES_XAPI_ENABLE_ACTIONS=true` を設定。
エンドポイントが見つからない	ローカル開発では現在の Twexapi OpenAPI ファイルからカタログを再生成。
リスクの高い書き込み	`HERMES_XAPI_ENABLE_ACTIONS=false` を維持し、読み取りツールのみ使用。

XApiClaw との関係

XApiClaw は OpenClaw ネイティブ npm プラグインです。Hermes XAPI は Hermes ネイティブ Python プラグインです。両方とも同じ Twexapi API 契約を使用し、ライブエンドポイント呼び出し前にエージェント安全なカタログ発見を公開します。