Openclaw Link

Cross-instance agent communication for OpenClaw. ClawLink lets multiple OpenClaw sessions discover each other, delegate tasks, share knowledge, collaboratively edit files, and work as a coordinated agent mesh — across different machines on a local network. Use this skill whenever the user mentions connecting OpenClaw instances, multi-agent workflows, agent-to-agent communication, delegating tasks between sessions, collaborative AI work, agent discovery, or running agents on multiple machines. Also trigger when the user says things like "ask my other agent to...", "have another Claude work on...", "set up agent communication", "multi-machine", "agent mesh", "distributed agents", or "ClawLink". If the user wants two or more AI sessions to work together in any way, this is the skill to use.

ClawLink — Cross-Instance Agent Communication

ClawLink turns isolated OpenClaw sessions into a collaborative agent mesh. Multiple OpenClaw instances — on the same machine or across a network — can delegate tasks, share findings, co-edit files, and coordinate work.

Security note: The relay server only runs when you explicitly start it with python3 server.py. It stores no data on disk — everything is in-memory and clears on shutdown. When connecting across machines, use --token to require authentication.

Architecture

text

  Machine A (OpenClaw)          Machine B (OpenClaw)
       │                              │
       └──── HTTP/WebSocket ──────────┘
                    │
            ┌───────┴───────┐
            │  ClawLink      │
            │  Relay Server  │
            │  (localhost or │
            │   LAN machine) │
            └────────────────┘

One machine runs the relay server. All others connect as agent clients. The relay handles message routing, queuing, and agent registry — entirely in-memory.

Quick Start

Step 1: Start the Relay Server

On the machine that will act as the hub (can be one of the agent machines):

bash

# Install dependencies (user install — no system changes)
pip install --user aiohttp requests

# Start the relay — localhost only (safest for single-machine use)
python3 scripts/server.py

# Or bind to LAN with auth token for multi-machine use
python3 scripts/server.py --host 0.0.0.0 --token YOUR_SHARED_SECRET

The server defaults to 127.0.0.1 (localhost only). To allow other machines on your local network, add --host 0.0.0.0 --token YOUR_SECRET.

For access from another machine on your network:

Use the relay machine's local IP address directly — e.g., http://192.168.1.10:9077. Both machines must be on the same network and you must pass the same --token on both server and clients.

Step 2: Register This Agent

bash

python3 /path/to/clawlink/scripts/client.py \
  --relay http://RELAY_IP:9077 \
  --token YOUR_SHARED_SECRET \
  register \
  --name "DESCRIPTIVE_NAME" \
  --caps "COMMA_SEPARATED_CAPABILITIES" \
  --description "What this agent specializes in"

The token can also be set via CLAWLINK_TOKEN environment variable.

Step 3: Discover and Communicate

bash

python3 scripts/client.py --relay http://RELAY_IP:9077 --token SECRET discover

Core Operations

Discovering Peers

bash

python3 scripts/client.py discover

Returns a table of online agents with their IDs, names, capabilities, and machines.

Delegating Tasks

bash

python3 scripts/client.py delegate \
  --to TARGET_AGENT_ID \
  --task "Clear description of what needs to be done" \
  --context '{"key": "relevant context data"}' \
  --priority normal

Receiving and Responding to Tasks

bash

# Poll for incoming messages
python3 scripts/client.py poll

# Respond when done
python3 scripts/client.py respond \
  --to REQUESTING_AGENT_ID \
  --msg-id ORIGINAL_MESSAGE_ID \
  --result "Task result or summary of work done"

Broadcasting Knowledge

bash

python3 scripts/client.py broadcast \
  --content "Description of the finding" \
  --topic "category" \
  --tags "tag1,tag2"

Collaborative File Editing

bash

# Upload/update a shared file
python3 scripts/client.py file-put --key "report.md" --file ./report.md

# Download a shared file
python3 scripts/client.py file-get --key "report.md" --output ./report.md

# List shared files
python3 scripts/client.py file-list

Behavioral Guidelines for Agents

As a Task Receiver

1. Poll regularly — Check for messages every 30-60 seconds during active work, or when the user asks "any messages?" or "check ClawLink"
2. Acknowledge receipt — Respond with status "in_progress" when you get a task
3. Be thorough — Complete the full task before responding
4. Report failures — If you can't complete a task, respond with status "failed" and explain why

As a Task Delegator

1. Match capabilities — Use discover to find the right agent for the job
2. Provide context — Include file paths, URLs, constraints, and output format
3. Be patient — The other agent may take time

General

• Always tell the user what's happening on the network
• Surface incoming messages proactively
• Keep heartbeats alive during long sessions

Troubleshooting

Problem	Solution
"Connection refused"	Check relay is running and IP/port are correct
"Unauthorized"	Pass the same --token (or CLAWLINK_TOKEN) as the server
Can't find relay on LAN	Use explicit --relay http://IP:PORT
Messages not arriving	Run heartbeat to re-register; check agent_id matches
Agent shows "stale"	Agent hasn't heartbeated in 120s — restart or heartbeat

Protocol Reference

For the full message format specification, transport layer details, and workflow patterns, read references/protocol.md.