---
title: "Hermes Agent 向け Hermes XAPI"
description: "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
- [ダッシュボード](https://twexapi.io/dashboard) から取得した Twexapi API キー

Hermes プラグインはオプトインです。`hermes-xapi` ツールセットが表示されることを期待する前に、プラグインをインストールして有効化してください。

## インストール

公開 GitHub リポジトリに Hermes のプラグインインストーラーを使用します。

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

対話型インストール中、Hermes は `TWEXAPI_KEY` を要求し、`~/.hermes/.env` に保存します。非対話型インストールはプロンプトをスキップします。`xapi_read` を呼び出す前に、プロセス環境または `~/.hermes/.env` にキーを設定してください。

パッケージインストールを自分で管理する場合は、Hermes Python 環境に PyPI パッケージを直接インストールできます。

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

Hermes Python 環境に `pip` が含まれる場合、この方法も有効です。

```bash
~/.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 キーを設定してください。

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

永続的な Hermes セッション用に、`~/.hermes/.env` にキーを追加します。

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

オプションの環境変数:

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

無人セッションでは `HERMES_XAPI_ENABLE_ACTIONS=false` を維持してください。明示的な承認ステップがあるワークフローのみでアクションを有効化します。

```bash
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` から始め、エージェントが適切なメソッド、パス、パラメータ、レスポンス形状を発見してからエンドポイントを呼び出せるようにします。

```txt
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` を返します。

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

### トレンドリサーチ

`xapi_explore` でトレンドルートを見つけ、`xapi_read` で国、トピック、コンテンツ、トレンドエンドポイントを呼び出します。

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

### フォロワーエクスポート

`xapi_explore` でフォロワーエンドポイントを見つけます。境界付き読み取りには `xapi_read` を、カタログが非公開、有料バルク、アクション系とマークするルートには `xapi_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.
```

### 制御された書き込みアクション

承認後にのみ `xapi_action` を使用します。無人セッションではアクションツールを無効のままにしてください。

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

## ランタイム診断

スクリプト可能な確認には `hermes tools list` を使用します。引数なしの `hermes tools` は対話型ツール UI を開き、TTY が必要です。

```bash
hermes tools list
```

プラグイン有効化後、非変更のワンショットプローブを実行します。

```bash
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 契約から同梱カタログを再生成します。

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

Twexapi OpenAPI ファイル変更後、`hermes-xapi` リポジトリからこのコマンドを実行してください。

## 検証

インストール、有効化、`TWEXAPI_KEY` 設定後に実行:

```txt
/xstatus
```

スクリプト可能な診断には、プラグインツールセットを一覧表示:

```bash
hermes tools list
```

読み取りワークフローをテスト:

```txt
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 契約を使用し、ライブエンドポイント呼び出し前にエージェント安全なカタログ発見を公開します。

## 参考資料

- [Hermes XAPI GitHub repo](https://github.com/twexapi-dev/hermes-xapi)
- [Hermes XAPI on PyPI](https://pypi.org/project/hermes-xapi/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
- サイドバーの API Reference
- [MCP Server](/mcp/overview)