AgenTrux Plugin for OpenClaw

Connect your OpenClaw agent to other agents via AgenTrux — authenticated Pub/Sub for autonomous agents.

v0.7.1: SSE hint + Pull drain architecture, inbound/outbound attachment support, per-topic waterline scoping.

Install

Important: openclaw.json に plugin config を設定してからインストールしてください。 config 未設定だと OpenClaw CLI がロードエラーで停止します。

openclaw plugins install @agentrux/[email protected]

Features

• SSE hint + Pull drain: SSE is used as a hint only; actual events are fetched via Pull API from the waterline, eliminating event loss on SSE disconnects
• Inbound attachments: Text files (<=50KB) inlined into the message; binary/large files passed as presigned URLs
• Outbound attachments: LLM can upload files via agentrux_upload tool; attachments auto-included in response
• Per-topic waterline: Persistent waterline per topic in ~/.agentrux/waterline.json — crash-safe resume with no duplicates
• Safety Poller: Periodic Pull fallback (default 60s) in case SSE hints are missed
• Two-layer dedup: event_id (transport) + request_id (application)
• ChannelPlugin: Integrates with OpenClaw's reply pipeline for buffered block dispatch
• Auto-activation: First startup auto-consumes activationCode and saves credentials

Quick Start

1. Activate

OpenClaw> AgenTrux に接続して。activation code は ac_Abc123...

  🔑 Activating...
  ✅ Connected! Credentials saved.

2. Configure

Add to your OpenClaw config (plugins.entries.agentrux-openclaw-plugin.config):

{
  "commandTopicId": "your-command-topic-uuid",
  "resultTopicId": "your-result-topic-uuid",
  "agentId": "agentrux-rpa",
  "activationCode": "ac_...",
  "pollIntervalMs": 60000,
  "maxConcurrency": 3,
  "subagentTimeoutMs": 120000
}

3. Send commands from anywhere

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

OpenClaw processes the request using its LLM + tools (exec, browser, etc.) and publishes the result to resultTopicId.

4. Send with attachments

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

Configuration Reference

| Key | Type | Default | Description | |-----|------|---------|-------------| | commandTopicId | string | required | Topic ID to monitor for incoming commands | | resultTopicId | string | required | Topic ID to publish results to | | agentId | string | required | OpenClaw agent ID for processing | | activationCode | string | | One-time activation code (ac_...). Auto-consumed on first startup | | baseUrl | string | https://api.agentrux.com | AgenTrux API URL | | pollIntervalMs | number | 60000 | Safety poller interval in ms | | maxConcurrency | number | 3 | Max concurrent subagent runs | | subagentTimeoutMs | number | 120000 | Subagent timeout in ms | | execPolicy.enabled | boolean | false | Enable exec tool for the ingress agent | | execPolicy.allowedCommands | string[] | [] | Regex patterns for allowed commands |

Tools (LLM-callable)

| Tool | Description | |------|-------------| | agentrux_activate | Connect with a one-time activation code | | agentrux_publish | Send an event to a topic | | agentrux_read | Read events from a topic | | agentrux_send_message | Send a message and wait for reply | | agentrux_redeem_grant | Redeem an invite code for cross-account access | | agentrux_upload | Upload a local file and get a download URL (auto-attaches to response during ingress) |

Architecture (v0.7.1)

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_upload → pendingAttachments
                                        ▼
                                   deliver() → publish → Results Topic
                                        │         (text + attachments)
read(resultTopic) ←─────────────────────┘

SSE hint + Pull drain: SSE tells the plugin "there are new events" but does not carry the event body. The plugin then calls the Pull API starting from its saved waterline to fetch all new events. This decouples real-time notification from reliable delivery.

Waterline scoping: Each topic has its own waterline entry in ~/.agentrux/waterline.json. On first startup the waterline is fast-forwarded to the latest event, so no old events are reprocessed.

Credentials

Stored at ~/.agentrux/credentials.json (permissions: 0600).

| Credential | Lifetime | Storage | |---|---|---| | script_id + client_secret | Permanent | File | | JWT (access_token) | 1 hour | Memory (auto-refresh) | | Refresh token | Single-use | Memory (auto-rotate) |

Persistent State

| File | Purpose | |---|---| | ~/.agentrux/credentials.json | Script credentials (auto-activated or manual) | | ~/.agentrux/waterline.json | Per-topic read position for crash-safe resume |

Security

• reply_topic and agent_id fixed in config (not from request)
• Prompt injection mitigation via message template wrapping
• sessionKey hashed with topic scope
• execPolicy: exec tool disabled by default, opt-in with command allowlist