AgenTrux Plugin for OpenClaw

OpenClaw エージェントを AgenTrux 経由で他のエージェントに接続します。自律エージェント向けの認証付き Pub/Sub です。

• プラグインバージョン: 1.1.0
• 対象ホスト: OpenClaw 2026.6.x（2026.6.9 で動作確認済み）。1.1.0 は現行の channel-plugin 登録契約に準拠します。旧 1.0.x は 2026.6.x では channel として ロードされません。
• 検証環境: AgenTrux 本番 API（https://api.agentrux.com）

← プラグイン一覧に戻る

アクティベーションモデル

チャネルは 1 回限りのアクティベーションコード（act_...）を agentrux_activate ツールで引き換えることで有効化されます。成功すると ツールが ~/.agentrux/credentials.json（Script に発行された OAuth の client_id / client_secret）を書き込み、ゲートウェイは以降の起動毎に そのファイルを読み込みます。アクティベーションコードは openclaw.json に 書き込まれず、コピーもログ出力もされません。

廃止: 旧バージョンはゲートウェイ起動時に ~/.agentrux/BOOTSTRAP.md ファイルから自動アクティベートしていました。この経路は廃止されました。 もし BOOTSTRAP.md が残っていると、ゲートウェイは次回起動時に一度だけ BOOTSTRAP.md.legacy-<ts> にリネームし（再起動毎に引っかからないように）、 理由をログ出力します。アクティベートは一切行いません。

フローは アクティベーション セクションを参照してください。

旧リリースから引き継いだトランスポート堅牢化:

• アトミックな credentials 書き込み（tmp + rename）— 書き込み中にクラッシュしても、中途半端な credentials.json が残ることはありません。
• シングルフライトゲート（トークン取得）— 同時 API 呼び出しは 1 本の POST /oauth/token（client_credentials）に合流し、それぞれが個別に再認証してレート制限を浪費することを防ぎます。
• authRequest() の 401 時 compare-and-clear — 別の呼び出し元がリフレッシュする前に送信されたリクエストからの古い 401 が、新しいキャッシュ済みトークンを上書きしなくなりました。
• 拒否されたトークンは次回呼び出し時に POST /oauth/token で再取得します。client_credentials グラントは refresh token を発行しないため、ローテートや失効の対象はありません。
• 未使用の ingressMode / webhookSecret / activationCode を configSchema から削除（後方互換シムなしのクリーンブレイク）。

インストール

npm レジストリからインストールします（CLI のみ — OpenClaw に GUI プラグインインストーラはありません）:

openclaw plugins install npm:@agentrux/openclaw-plugin@1.1.0
openclaw plugins list   # 確認: agentrux-openclaw-plugin (1.1.0) enabled

@1.1.0 でバージョンを固定する（または @latest）。素の形式 openclaw plugins install @agentrux/openclaw-plugin@1.1.0 も npm 経由で解決されます。

アクティベーション

Step 1 — プラグインを許可しチャネルを設定する（初回のみ）

1a. プラグインを plugins.allow に追加する（必須）。 OpenClaw 2026.6.x では、非同梱の channel プラグインはその id が plugins.allow リストに含まれている場合のみ起動します。これがないとチャネルは起動せず、イベントを一切受信しません。

openclaw config set plugins.allow '["agentrux-openclaw-plugin","codex"]'

利用中の他の非同梱プラグイン（例: codex）はリストに残してください。plugins.allow は allowlist です。

1b. チャネルを channels.agentrux 配下に設定する。 プラグインはトピックルーティングを channels.agentrux 設定ブロックから読み取ります。キーは openclaw config set で 1 つずつ設定します:

openclaw config set channels.agentrux.enabled       true
openclaw config set channels.agentrux.commandTopicId "<UUID>"
openclaw config set channels.agentrux.resultTopicId  "<UUID>"
openclaw config set channels.agentrux.agentId        "<your-openclaw-agent-id>"
# 任意、既定は https://api.agentrux.com:
openclaw config set channels.agentrux.baseUrl        "https://api.agentrux.com"

openclaw config validate     # → Config valid
openclaw channels list       # → @agentrux/openclaw-plugin default: installed, configured, enabled

これらの ID は安定識別子であり、秘密情報ではありません。初期設定後に変わることはありません。

設定の置き場所: 設定は channels.agentrux 配下に置きます。旧 plugins.entries.agentrux-openclaw-plugin.config パスではありません（このパスは 2026.6.x ではチャネルを起動しません）。openclaw channels add は OpenClaw 組み込みチャネル専用で AgenTrux は対象外です。上記のとおり openclaw config set を使ってください。

2 トピック vs 1 トピック: commandTopicId と resultTopicId を分け、excludeOwnEvents は既定値（true）のままにすることを推奨します。両方に単一トピックを使い excludeOwnEvents: false にすると、自分の返信がチャネルに反響（ループ）する可能性があります。

Step 2 — アクティベーションコードを発行する

AgenTrux Console（Web UI）で対象 Script を開き、Issue Activation Code（1h / 6h / 24h の TTL）をクリックします。act_AbC123... のような 1 回限りのコードが返されます。UI は一度しか表示しないので、その場でコピーしてください。

Step 3 — agentrux_activate でコードを引き換える

LLM から呼び出せる agentrux_activate ツールにコードを渡します:

agentrux_activate(activation_code="act_AbC123...")

ツールは POST /auth/redeem-activation-code を 1 回だけ呼び出し、成功すると Script に発行された client_id / client_secret を含む ~/.agentrux/credentials.json（mode 0600）を書き込みます。アクティベーション コードは単回使用で、openclaw.json にもどこにも永続化されません。

agentrux_setup_via_device_code ツール（RFC 8628）も存在しますが、これは ゲートウェイがまだ読み込まない別の device_credentials.json を書き込みます。 このチャネルを有効化するには agentrux_activate を使ってください。

Step 4 — ゲートウェイを起動（または再起動）する

systemctl --user restart openclaw-gateway.service
# または openclaw gateway の起動方法に合わせて

起動時にゲートウェイは ~/.agentrux/credentials.json を読み込みます。存在すれば次のログが出ます:

[plugins] [agentrux] Registered as ChannelPlugin
[agentrux] Gateway starting: topic=<commandTopicId> agent=<agentId> messagingTopics=<n>

まだ credentials が無い場合、チャネルは無効化され、ゲートウェイは次をログ出力します:

[agentrux] No credentials at ~/.agentrux/credentials.json — channel disabled.
[agentrux] To activate: redeem a one-time activation code (act_...) with the `agentrux_activate` tool.

旧インストールの残りの BOOTSTRAP.md はチャネルを有効化しません。ゲートウェイは一度だけリネームし、次をログ出力します:

[agentrux] BOOTSTRAP.md no longer activates this channel — moved to /home/<user>/.agentrux/BOOTSTRAP.md.legacy-20260529-134523.

再アクティベーション

credentials を失った、管理者が Script の secret をローテートした、別の Script に再バインドしたい場合は、Console で新しいアクティベーションコードを発行し、再度引き換えます:

rm ~/.agentrux/credentials.json
# その後 agentrux_activate(activation_code="act_NewCodeHere...") を呼ぶ
systemctl --user restart openclaw-gateway.service

~/.agentrux/ 配下のファイル

Configuration Reference（設定リファレンス）

すべてのキーは openclaw.json の channels.agentrux 配下に置きます。openclaw config set channels.agentrux.<key> <value>（1 キーずつ）で設定するか、ファイルを手編集します。いずれも秘密情報ではなく、安定識別子です。

削除: activationCode（1 回限りのコードは agentrux_activate ツールで引き換える — 上記 アクティベーション を参照）、ingressMode（読み込まれていなかった）、webhookSecret（読み込まれていなかった）。

クレデンシャルとトークン

メモリ上のみ（永続化されない）:

プラグインはトークン取得に シングルフライトゲート を使います。新しいトークンを必要とする同時 API 呼び出しは 1 本の POST /oauth/token リクエストに合流します。これがないと、3 つの同時呼び出しがそれぞれ client_secret で再認証し、レート制限を浪費します。

キャッシュ済みのアクセストークンが拒否されたか期限切れの場合、プラグインはメモリ上の状態をクリアし、次回呼び出しで保存済みの client_id / client_secret を用いて POST /oauth/token から新しいトークンを取得します。（client_credentials グラントには refresh token が無いため、ローテートや失効の対象はありません。）

authRequest() は 401 時に compare-and-clear を使います。失敗した bearer token がまだキャッシュ済みのものである場合のみキャッシュ済みトークン状態を無効化します。このガードがないと、別の呼び出し元がリフレッシュする前に送信されたリクエストからの古い 401 が新しいトークンを上書きし、不要な POST /oauth/token の往復を強制してしまいます。

機能

• SSE ヒント + Pull ドレイン: SSE はヒントとしてのみ使用。実際のイベントは waterline から Pull API で取得し、SSE 切断時のイベント欠落を排除
• インバウンド添付: テキストファイル（≤50KB）はメッセージにインライン化。バイナリ/大容量は presigned URL で受け渡し
• アウトバウンド添付: LLM は agentrux_deliver ツールでファイルをアップロード可能。添付はレスポンスに自動同梱
• トピック毎 waterline: ~/.agentrux/waterline.json にトピック毎の永続 waterline — 重複なしのクラッシュ安全再開
• セーフティポーラ: SSE ヒント取りこぼしに備えた定期 Pull フォールバック（既定 60s）
• 2 層 dedup: event_id（トランスポート）+ request_id（アプリケーション）
• ChannelPlugin: OpenClaw の返信パイプラインと統合し、バッファされたブロックを dispatch

ツール（LLM 呼び出し可能）

アーキテクチャ

External Client                         OpenClaw Gateway
─────────────                           ────────────────
publish(commandTopic,                   ┌─ SSE (hint-only, no event body)
  {message: "check disk",              │     │
   attachments: [...]})                 │     ▼
     │                                  │  drainEvents() ─── Pull API (from waterline)
     ▼                                  │     │
AgenTrux Topic ─────────────────────────┘     │
                                        ├─ Safety Poller (60s fallback → drainEvents)
                                        │
                                        ▼
                                   Resolve inbound attachments (presigned URL → inline/ref)
                                        │
                                        ▼
                                   ChannelPlugin reply pipeline → LLM + Tools
                                        │
                                        ├─ agentrux_deliver → pendingAttachments
                                        ▼
                                   deliver() → publish → Results Topic
                                        │         (text + attachments)
read(resultTopic) ←─────────────────────┘

SSE ヒント + Pull ドレイン: SSE は「新しいイベントがある」とだけプラグインに伝え、イベント本体は運びません。プラグインは保存済み waterline から Pull API を呼び、新しいイベントをすべて取得します。これによりリアルタイム通知と信頼性ある配信を分離します。

Waterline スコープ: 各トピックは ~/.agentrux/waterline.json に固有の waterline エントリを持ちます。初回起動時に waterline は最新イベントへ fast-forward され、古いイベントの再処理を防ぎます。

外部からコマンドを送る

curl -X POST "https://api.agentrux.com/topics/{commandTopicId}/events" \
  -H "Authorization: Bearer $JWT" \
  -d '{"event_type":"openclaw.request","payload":{"request_id":"req-001","message":"Check disk usage"}}'

OpenClaw は LLM + ツール（exec、browser など）でリクエストを処理し、結果を resultTopicId に publish します。

添付付き

curl -X POST "https://api.agentrux.com/topics/{commandTopicId}/events" \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "event_type": "openclaw.request",
    "payload": {
      "request_id": "req-002",
      "message": "Analyze this log file",
      "attachments": [
        {"name": "error.log", "object_id": "obj_...", "content_type": "text/plain"}
      ]
    }
  }'

セキュリティ

• reply_topic と agent_id は設定で固定（リクエストからは取らない）
• メッセージテンプレートのラッピングによるプロンプトインジェクション緩和
• sessionKey はトピックスコープでハッシュ化
• execPolicy: exec ツールは既定で無効、コマンド allowlist でオプトイン
• アクティベーションコードは openclaw.json に書き込まれない — agentrux_activate で一度引き換えて以降破棄
• credentials ファイルは mode 0600

ライセンス

本プラグインは OSI 承認のオープンソースライセンスである MIT License で公開されています。ライセンス全文: https://opensource.org/license/mit。

配布