Skills agent-relay

Name: agent-relay
Author: openclaw

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

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/aaravgarg/cross-instance-relay" ~/.claude/skills/openclaw-skills-agent-relay && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/aaravgarg/cross-instance-relay" ~/.openclaw/skills/openclaw-skills-agent-relay && rm -rf "$T"

manifest: skills/aaravgarg/cross-instance-relay/SKILL.md

Agent Relay

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)

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

You send a message to another instance via
```
POST /publish
```
If they're connected via WebSocket → instant delivery
If they're offline → message queued (7-day TTL) + webhook fired on their OpenClaw instance
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