agent-relay

What This Skill Does

The agent-relay skill enables seamless cross-instance communication between OpenClaw AI agents. It acts as a lightweight, robust message broker that bridges geographically or infrastructure-separated instances. By utilizing a webhook-first architecture, the relay ensures that messages are delivered instantly if an agent is active, or safely queued with a 7-day TTL (Time-To-Live) if the target instance is offline. This eliminates the need for persistent, resource-heavy WebSocket connections while maintaining high reliability for inter-agent workflows.

Installation

To install this skill, run the following command in your terminal: clawhub install openclaw/skills/skills/aaravgarg/cross-instance-relay. After installation, you must configure your environment variables including RELAY_URL, RELAY_TEAM_TOKEN, RELAY_TEAM_ID, and RELAY_INSTANCE_ID. Crucially, you must perform a one-time registration of your instance's webhook via the relay API using your unique team token. This ensures that the relay knows where to push incoming messages directed at your specific instance, allowing your agent to wake up and process requests on demand.

Use Cases

1. Distributed Task Execution: Offload heavy computational tasks to a specialized high-performance OpenClaw instance while maintaining a lightweight 'controller' agent on a different server.
2. Multi-Agent Systems: Coordinate complex workflows where one agent manages data collection, a second manages processing, and a third handles user interaction across different network boundaries.
3. Reliable Webhook Notifications: Ensure that cross-service events are never lost, even if an agent instance is undergoing maintenance, by utilizing the relay’s persistent message queue.

Example Prompts

1. "Send a request to the research-instance to summarize the current market trends and relay the result back to me."
2. "Broadcast to all active instances that the system update is beginning, then report which nodes are currently unreachable."
3. "Check the agent-relay inbox for pending messages and execute any tasks labeled as 'priority' from the primary data instance."

Tips & Limitations

• Security: Always treat your RELAY_TEAM_TOKEN as a sensitive secret. Do not commit it to version control systems.
• Queue Management: While the 7-day TTL is generous, ensure your agent regularly polls or processes its inbox to prevent overflow during high-traffic periods.
• Fallback: If you are operating in a restricted network where webhooks are blocked, the system gracefully falls back to a polling-based retrieval mechanism, ensuring parity in functionality.
• Debugging: If messages are not being delivered, use the /messages/count endpoint to verify if the relay is successfully receiving data from the sender, then verify your webhook URL connectivity.