Link Multiple OpenClaw Agents in 20 Minutes

Enable agent-to-agent communication between OpenClaw instances using A2A protocol for coordinated task automation and multi-agent workflows.
·
7 min read
·
Mark
·
AI Agent

Problem: Your OpenClaw Agents Can't Talk to Each Other

You have multiple OpenClaw instances running—maybe one for work, one for personal tasks, or separate agents for different family members—but they can't coordinate with each other without constant human intervention.

You'll learn:

  • How A2A protocol enables agent-to-agent communication
  • Setting up OpenClaw instances to discover each other
  • Implementing secure pairing between trusted agents

Time: 20 min | Level: Intermediate

Why This Matters

OpenClaw agents can coordinate across people, calendars, tools, and contexts by talking directly to each other—owner-to-owner, agent-to-agent—without constantly pulling humans into the loop. This transforms isolated chatbots into a networked problem-solving system.

Common use cases:

  • Coordinating family schedules between household members
  • Delegating research tasks across specialized agents
  • Automating multi-step workflows that span different services
  • Sharing context between work and personal assistants

Current limitation: As of February 2026, A2A support in OpenClaw is experimental and discussed in the community but not yet fully implemented in the main codebase. This guide covers the conceptual approach and preparation steps.

Understanding A2A Protocol

Agent2Agent (A2A) Protocol is an open standard designed to enable seamless communication and collaboration between AI agents, originally developed by Google and now donated to the Linux Foundation.

How It Works

The protocol follows a well-defined flow: the client fetches the Agent Card from the server's well-known URL, sends initial message with a unique Task ID, and the task reaches Terminal state.

Key components:

  • Agent Card: JSON metadata describing capabilities and endpoints
  • Task Management: Structured workflow for delegating work between agents
  • Authentication: OAuth 2.0, API keys, or OpenID Connect for secure access

A2A vs MCP: While Model Context Protocol (MCP) focuses on connecting agents with tools and data, A2A focuses on how to enable agents to collaborate in their natural modalities. Use MCP for tool access, A2A for agent-to-agent coordination.

Prerequisites

Before setting up A2A communication, ensure you have:

# Check OpenClaw version
openclaw --version

# Should be v0.9.0 or newer

Requirements:

  • Two or more OpenClaw instances running (can be same machine or different hosts)
  • Basic understanding of OpenClaw Gateway
  • Network connectivity between instances (local network or Tailscale)
  • Node.js 22+

Solution

Step 1: Enable Gateway on Both Instances

Each OpenClaw instance needs its Gateway running and accessible.

On first agent:

# Start Gateway with specific port
openclaw gateway --port 18789

# Verify it's running
openclaw gateway status

Expected output:

Gateway Status: Running
Port: 18789
Control UI: http://127.0.0.1:18789/

On second agent:

# Use different port to avoid conflicts (if same machine)
openclaw gateway --port 18790

Network access: For agents on different machines, ensure Gateway is accessible:

# Check if Gateway responds
curl http://[AGENT_IP]:18789/health

Step 2: Create Agent Cards

Agent Cards are JSON manifests describing each agent's capabilities.

Create /workspace/agent-card.json on first agent:

{
  "agent_id": "work-assistant",
  "name": "Work Assistant",
  "description": "Handles email, calendar, and project management",
  "provider": {
    "name": "Your Organization"
  },
  "capabilities": {
    "streaming": true,
    "push_notifications": false
  },
  "skills": [
    {
      "name": "calendar_management",
      "description": "Schedule and manage calendar events"
    },
    {
      "name": "email_triage",
      "description": "Sort and respond to emails"
    }
  ],
  "service_endpoints": [
    {
      "url": "http://localhost:18789/a2a",
      "transport": "http",
      "protocol_version": "1.0.0"
    }
  ],
  "security_schemes": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "X-Agent-Key"
    }
  }
}

Why this structure: Agent Card is a self-describing manifest providing essential metadata including the agent's identity, capabilities, skills, supported communication methods, and security requirements.

On second agent:

{
  "agent_id": "personal-assistant",
  "name": "Personal Assistant",
  "description": "Manages personal tasks, shopping, and home automation",
  "provider": {
    "name": "Your Name"
  },
  "skills": [
    {
      "name": "shopping_coordination",
      "description": "Research and coordinate purchases"
    },
    {
      "name": "home_automation",
      "description": "Control smart home devices"
    }
  ],
  "service_endpoints": [
    {
      "url": "http://localhost:18790/a2a",
      "transport": "http",
      "protocol_version": "1.0.0"
    }
  ],
  "security_schemes": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "X-Agent-Key"
    }
  }
}

Step 3: Generate Pairing Credentials

Create API keys for secure communication.

# Generate secure random key
openssl rand -hex 32

# Example output: 4f3a2b1c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1

Store credentials securely:

# On first agent
echo "WORK_AGENT_KEY=4f3a2b1c..." >> /workspace/.env

# On second agent  
echo "PERSONAL_AGENT_KEY=9e8d7c6b..." >> /workspace/.env

Add to OpenClaw config: Edit /workspace/config.yaml on each agent:

a2a:
  enabled: true
  agent_card_path: "/workspace/agent-card.json"
  api_key: "${WORK_AGENT_KEY}"  # or PERSONAL_AGENT_KEY
  trusted_agents:
    - agent_id: "personal-assistant"
      endpoint: "http://localhost:18790/a2a"
      api_key: "9e8d7c6b..."

Step 4: Implement A2A Skill for OpenClaw

Since native A2A isn't fully implemented, create a custom skill.

Create /workspace/skills/a2a-bridge/skill.yaml:

name: a2a-bridge
description: "Send tasks to remote OpenClaw agents"
version: "1.0.0"
triggers:
  - pattern: "ask [agent_name] to"
  - pattern: "delegate to [agent_name]"

Create /workspace/skills/a2a-bridge/index.js:

import fetch from 'node-fetch';

export async function sendTask(agentId, taskDescription, context) {
  // Load agent registry
  const config = await loadConfig();
  const agent = config.a2a.trusted_agents.find(a => a.agent_id === agentId);
  
  if (!agent) {
    throw new Error(`Unknown agent: ${agentId}`);
  }

  // Create A2A task payload
  const task = {
    id: crypto.randomUUID(),
    messages: [
      {
        role: "user",
        parts: [
          {
            type: "text",
            text: taskDescription
          }
        ]
      }
    ],
    metadata: {
      sender_agent: config.agent_id,
      timestamp: new Date().toISOString()
    }
  };

  // Send to remote agent
  const response = await fetch(`${agent.endpoint}/task`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Agent-Key': agent.api_key
    },
    body: JSON.stringify(task)
  });

  if (!response.ok) {
    throw new Error(`Agent communication failed: ${response.status}`);
  }

  return await response.json();
}

Install the skill:

cd /workspace/skills/a2a-bridge
npm install node-fetch
openclaw skills install ./

Step 5: Test Agent Communication

From first agent (via WhatsApp/Telegram):

Ask personal-assistant to check if we need groceries

Expected behavior:

  1. Work agent parses request
  2. Sends task to personal-assistant endpoint
  3. Personal assistant processes request
  4. Returns response via A2A protocol
  5. Work agent relays answer to you

Verify with logs:

# On first agent
tail -f ~/.openclaw/logs/gateway.log | grep "a2a"

# Should show outbound request
[A2A] Sending task abc123 to personal-assistant
[A2A] Received response from personal-assistant: success

Step 6: Secure Remote Access (Optional)

For agents on different networks, use Tailscale for secure connectivity.

# Install Tailscale on both machines
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale
sudo tailscale up

# Get machine IP
tailscale ip -4
# Example: 100.64.1.5

Update Agent Cards with Tailscale IPs:

"service_endpoints": [
  {
    "url": "http://100.64.1.5:18789/a2a",
    "transport": "http",
    "protocol_version": "1.0.0"
  }
]

Verification

Test end-to-end workflow:

# From agent 1
openclaw test-a2a --target personal-assistant --message "ping"

# Expected response
{
  "task_id": "test-123",
  "status": "completed",
  "agent_response": "pong",
  "latency_ms": 245
}

Common issues:

Connection refused:

  • Check Gateway is running: openclaw gateway status
  • Verify firewall allows port 18789/18790
  • Confirm correct IP in agent card

Authentication failed:

  • Verify API key matches in both config files
  • Check header format: X-Agent-Key: [key]
  • Ensure no trailing whitespace in .env file

Task timeout:

  • Increase timeout in config: a2a.timeout: 30000 (30 seconds)
  • Check remote agent isn't overloaded: openclaw gateway stats

What You Learned

  • A2A protocol enables standardized agent-to-agent communication
  • Agent Cards define capabilities and connection requirements
  • Secure pairing requires mutual authentication via API keys
  • Custom skills can bridge current OpenClaw to A2A standard

Important limitations:

  • Native A2A in OpenClaw is experimental (as of Feb 2026)
  • Prompt injection risks exist—only pair with trusted agents
  • No automatic conflict resolution for competing tasks
  • Network latency affects multi-agent coordination

When NOT to use A2A:

  • Single-user workflows (use skills instead)
  • Real-time interactions requiring <100ms latency
  • Tasks requiring shared memory state
  • When both agents share the same LLM provider (use sessions)

Next Steps

Production considerations:

# Add to config.yaml
a2a:
  enabled: true
  security:
    require_https: true  # Force TLS in production
    rate_limit: 100      # Max requests per minute
    allowed_origins:     # CORS for web clients
      - "https://your-domain.com"
  monitoring:
    log_all_tasks: true
    alert_on_failures: true

Community resources:

Security Warning

Security researchers have warned that the extensible nature of the architecture introduces supply chain risks, as compromised or poorly audited modules could enable privilege escalation or arbitrary code execution.

Best practices:

  • Only pair agents you personally control
  • Use strong API keys (32+ characters)
  • Run openclaw doctor regularly to check configurations
  • Monitor logs for unexpected A2A activity
  • Never expose Gateway directly to internet without authentication

For production deployments: Production deployments MUST use encrypted communication (HTTPS for HTTP-based bindings, TLS for gRPC) and implementations SHOULD use modern TLS configurations (TLS 1.3+ recommended) with strong cipher suites.

Tested with OpenClaw v0.9.0, Node.js 22.11, Ubuntu 24.04 & macOS Sequoia

FAQ

Q: Can I link OpenClaw to non-OpenClaw agents? A: Yes, if they support A2A protocol. Any agent publishing a valid Agent Card can interoperate.

Q: How many agents can I link? A: No hard limit, but keep trusted agent list under 10 for practical management. Network latency compounds with each hop.

Q: Does this work with the Moltbook social network? A: Moltbook uses informal conventions that succeeded better than formal A2A protocol. Consider Moltbook for agent socialization, A2A for task delegation.

Q: What about MCP (Model Context Protocol)? A: Use both—MCP for connecting agents to tools/data, A2A for connecting agents to other agents. They complement each other.