OpenClaw A2A Gateway Plugin

What it is – A production‑ready plugin for the OpenClaw agent platform that implements the Google A2A (Agent‑to‑Agent) v0.3.0 protocol. It lets OpenClaw agents on different machines discover each other automatically and exchange messages (text, files, JSON data) over JSON‑RPC, REST, or gRPC.

---

Core ideas

Concept	How the plugin handles it
Transport	Tries JSON‑RPC → REST → gRPC automatically; falls back if one fails. Supports Server‑Sent‑Events streaming with heartbeat for live status updates.
Message parts	Supports the three A2A part types – TextPart, FilePart (URI or base64), DataPart. File URLs found in an agent’s reply are turned into outbound FileParts automatically.
Routing	Rule‑based (regex, tags, skills) plus a bio‑inspired “Hill‑equation” affinity score that weighs skills, tags, pattern match and success rate. The best peer is chosen per‑message.
Discovery	Zero‑config peer finding via DNS‑SD (_a2a._tcp SRV/TXT), mDNS self‑advertisement, and a quorum‑sensing poller that adapts its interval based on how many peers are known.
Resilience	Four‑state circuit‑breaker (closed → desensitized → open → recovering) with exponential recovery, adaptive transport ranking, push‑notification webhooks, and a Michaelis‑Menten‑style soft‑concurrency throttle.
Security	Bearer‑token authentication (single token or rotating list), Ed25519 device identity, SSRF protection (host‑allowlist, MIME allowlist, size limits), JSON‑L audit log, optional authenticated metrics endpoint, durable on‑disk task store with TTL cleanup.

---

Quick‑start (zero‑config)

# Install from npm (recommended)
openclaw plugins install openclaw-a2a-gateway

# Or from source
mkdir -p ~/.openclaw/workspace/plugins && cd ~/.openclaw/workspace/plugins
git clone https://github.com/win4r/openclaw-a2a-gateway.git a2a-gateway
cd a2a-gateway
npm install --production
openclaw plugins install ~/.openclaw/workspace/plugins/a2a-gateway
openclaw gateway restart

# Verify the Agent Card is reachable
curl -s http://localhost:18800/.well-known/agent-card.json | python3 -m json.tool

The plugin starts with a default Agent Card (name: "OpenClaw A2A Gateway", skills: [chat]).

---

Adding and configuring peers

openclaw config set plugins.entries.a2a-gateway.config.peers '[
  {
    "name": "PeerB",
    "agentCardUrl": "http://<PEER_IP>:18800/.well-known/agent-card.json",
    "auth": {"type": "bearer", "token": "<PEER_TOKEN>"}
  }
]'
openclaw gateway restart

For two‑way communication, each side adds the other as a peer and restarts.

---

Sending a message

The plugin ships a helper script that wraps the official @a2a-js/sdk client.

node <PLUGIN_PATH>/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --message "Hello from Server A!"

Long‑running or multi‑round interactions can be run in non‑blocking mode with polling:

node <PLUGIN_PATH>/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --non-blocking --wait --timeout-ms 600000 --poll-ms 1000 \
  --message "Discuss A2A advantages in 3 rounds"

To target a specific OpenClaw agentId on the remote side (an OpenClaw‑specific extension): add --agent-id <ID>.

---

Agent‑side tooling

The plugin registers an a2a_send_file tool that agents can invoke:

Parameter	Required?	Meaning
peer	yes	Name of a configured peer
uri	yes	Public URL of the file
name	no	Filename (e.g., report.pdf)
mimeType	no	MIME type (auto‑detected if omitted)
text	no	Optional caption
agentId	no	Remote OpenClaw agent ID (extension)

Agents can be taught to use this via a TOOLS.md entry that points to the a‑2‑a‑send.mjs script.

---

Network options

Option	When to use
Tailscale (recommended)	Secure mesh between servers; no firewall changes needed.
LAN	Both machines on the same local network; just open port 18800.
Public IP	Exposed internet; must protect with bearer tokens and optional firewall rules.

---

Configuration reference (excerpt)

{
  "agentCard": {
    "name": "OpenClaw A2A Gateway",
    "description": "A2A bridge for OpenClaw agents",
    "skills": [{"id":"chat","name":"chat","description":"Chat bridge"}]
  },
  "server": {"host":"0.0.0.0","port":18800},
  "security": {"inboundAuth":"bearer","token":"<TOKEN>"},
  "routing": {"defaultAgentId":"main","rules":[]},
  "peers": []
}

Key sections include agentCard, server, security (token rotation, MIME allowlist, file‑size limits), routing (default agent ID, rule list), and peers (array of remote agents with URL and auth).

---

Who might use this?

• Multi‑agent deployments where different OpenClaw instances need to talk (e.g., a chat‑bot cluster, social‑media automation bots, or distributed tool‑calling agents).
• Researchers building large‑scale agent ecosystems who want automatic discovery and bio‑inspired routing without writing their own networking layer.
• Ops teams that already run OpenClaw and need a secure, zero‑config bridge between data‑center, edge, or cloud nodes.

---

TL;DR

The OpenClaw A2A Gateway is a ready‑to‑install Node.js plugin that gives OpenClaw agents a standards‑compliant, auto‑discovering, resilient way to call each other across machines. It handles transport fallback, part serialization, skill‑based routing, security, and observability out of the box, and can be set up in a few commands.