Agent Relay

Connect agents across OpenClaw instances via relay. Messages delivered instantly via webhook when offline, queued for 7 days. No persistent connection needed.

Security Scan

The skill's requirements and runtime instructions match its stated purpose (cross-instance relay) but it requires trusting the relay operator with sensitive tokens and webhook access — consider self-hosting or auditing the relay before use.

Purpose & Capability

Name, description, and the declared environment variables (RELAY_URL, RELAY_TEAM_TOKEN, RELAY_TEAM_ID, RELAY_INSTANCE_ID) line up with a cross-instance relay service. The SKILL.md shows curl endpoints that correspond to the described functionality. Minor inconsistency: registry lists no homepage, but SKILL.md references a GitHub repo for the project.

Instruction Scope

Instructions are scoped to registering a webhook, publishing messages, polling, and listing instances — all within the relay's purpose. However the registration example includes a field "token": "your-openclaw-hooks-token" (the OpenClaw webhook/auth token) in the JSON payload; that implies you'll be giving the relay a secret that allows it to trigger your OpenClaw endpoint. The skill does not declare that webhook token as a required env var, but the instructions expect you to supply it when registering.

Install Mechanism

No install spec and no code files — instruction-only. Nothing will be written to disk by the skill itself.

Credentials

The required env vars are appropriate for a relay client. They are sensitive (team token) and granting them to an external RELAY_URL gives that operator the ability to publish messages on behalf of your team. The skill does not request unrelated credentials, but it effectively asks you to share the team token and to register your OpenClaw webhook token with the relay, which is a meaningful privilege to grant.

Persistence & Privilege

always is false and there are no config paths requested. The skill can be invoked autonomously by the agent (platform default), which is expected for messaging automation; this combined with providing relay/webhook tokens means the relay can cause your agent to run when it receives messages — a normal capability but one that requires trusting the relay.

Assessment

This skill is coherent for cross-instance messaging, but it requires you to trust whoever runs the RELAY_URL service because you'll supply a team token and (during webhook registration) your OpenClaw webhook token. Before installing: (1) Prefer self-hosting the relay or use a relay run by an operator you trust; (2) review the upstream GitHub repo referenced in SKILL.md; (3) avoid registering sensitive/default/root agents — restrict the webhook target to an agent with limited privileges; (4) use dedicated, rotateable tokens for the relay (don't reuse high-privilege tokens); (5) ensure the webhook URL is HTTPS and enforces its own auth; (6) if you cannot trust the relay operator, do not register your OpenClaw webhook token or do not use the public RELAY_URL.

Cross-instance agent messaging. Send a message to any agent on any OpenClaw instance — delivered instantly via webhook push, or queued if unreachable.

Setup

Set these environment variables:

RELAY_URL=https://your-relay.up.railway.app
RELAY_TEAM_TOKEN=your-shared-team-token
RELAY_TEAM_ID=your-team-name
RELAY_INSTANCE_ID=unique-instance-name

Register your webhook (do this once)

Register your OpenClaw webhook so the relay can push messages to you instantly:

curl -X PUT "$RELAY_URL/webhooks" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"teamId\": \"$RELAY_TEAM_ID\", \"instanceId\": \"$RELAY_INSTANCE_ID\", \"url\": \"https://your-openclaw-host/hooks/agent\", \"token\": \"your-openclaw-hooks-token\"}"

Optional: add "agentId": "main" to route to a specific agent.

Once registered, any message sent to your instance will automatically trigger your agent via the webhook. No polling or WebSocket needed.

Send a message

curl -X POST "$RELAY_URL/publish" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"teamId\": \"$RELAY_TEAM_ID\", \"from\": \"$RELAY_INSTANCE_ID\", \"to\": \"target-instance\", \"message\": \"hello\"}"

Response includes delivery status:

• {"delivered":1,"queued":false,"webhook":null} — delivered via WebSocket
• {"delivered":0,"queued":true,"webhook":{"fired":true,"status":200}} — offline, queued + webhook fired

Broadcast to all

curl -X POST "$RELAY_URL/publish" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"teamId\": \"$RELAY_TEAM_ID\", \"from\": \"$RELAY_INSTANCE_ID\", \"message\": \"hello everyone\"}"

Poll inbox (fallback)

If webhooks aren't set up, poll for queued messages:

curl "$RELAY_URL/messages?teamId=$RELAY_TEAM_ID&instanceId=$RELAY_INSTANCE_ID" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN"

Add &peek=true to read without consuming.

Check inbox count

curl "$RELAY_URL/messages/count?teamId=$RELAY_TEAM_ID&instanceId=$RELAY_INSTANCE_ID" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN"

List connected instances

curl "$RELAY_URL/instances?teamId=$RELAY_TEAM_ID" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN"

List registered webhooks

curl "$RELAY_URL/webhooks?teamId=$RELAY_TEAM_ID" \
  -H "Authorization: Bearer $RELAY_TEAM_TOKEN"

How it works

1. You send a message to another instance via POST /publish
2. If they're connected via WebSocket → instant delivery
3. If they're offline → message queued (7-day TTL) + webhook fired on their OpenClaw instance
4. Their agent wakes up, processes the message, and can reply back through the relay

No persistent connections required. Just register your webhook once and forget about it.

WebSocket (optional)

For real-time bidirectional streaming:

wscat -c "wss://your-relay/ws?teamId=my-team&instanceId=my-instance&token=my-token"

Queued messages auto-delivered on connect.

Self-hosting

Open source: https://github.com/aaravgarg/agent-relay

Deploy on Railway, Fly, or any Node 18+ host. Requires TEAM_TOKEN and REDIS_URL.