A2A Gateway Setup

---

name: a2a-setup

description: "Install and configure the Claw Crony A2A Gateway plugin for cross-server agent communication. Use when: (1) setting up A2A between two or more OpenClaw instances, (2) user says 'configure A2A', 'set up A2A gateway', 'connect two OpenClaw servers', 'agent-to-agent communication', (3) adding a new A2A peer to an existing setup. Covers: plugin installation, Agent Card configuration, security tokens, peer registration, network setup (Tailscale/LAN), TOOLS.md template for agent awareness, and end-to-end verification."

---

# A2A Gateway Setup

Configure the Claw Crony A2A Gateway plugin for cross-server agent-to-agent communication using the A2A v0.3.0 protocol.

Prerequisites

Step 1: Install the Plugin

mkdir -p <WORKSPACE>/plugins
cd <WORKSPACE>/plugins
git clone https://github.com/ccccl8/claw-crony.git claw-crony
cd claw-crony
npm install --production

Replace `<WORKSPACE>` with the agent workspace path. Find it with:

openclaw config get agents.defaults.workspace

Step 2: Register Plugin in OpenClaw

Get current allowed plugins first to avoid overwriting:

openclaw config get plugins.allow

Then add `claw-crony` to the existing array (do NOT drop existing plugin ids):

# Example only — include your existing plugins too
openclaw config set plugins.allow '["<existing...>", "claw-crony"]'
openclaw config set plugins.load.paths '["<ABSOLUTE_PATH>/plugins/claw-crony"]'
openclaw config set plugins.entries.claw-crony.enabled true

**Critical:** Use the absolute path in `plugins.load.paths`. Relative paths will fail.

Step 3: Configure Agent Card

openclaw config set plugins.entries.claw-crony.config.agentCard.name '<AGENT_NAME>'
openclaw config set plugins.entries.claw-crony.config.agentCard.description '<DESCRIPTION>'
openclaw config set plugins.entries.claw-crony.config.agentCard.url 'http://<REACHABLE_IP>:18800/a2a/jsonrpc'
openclaw config set plugins.entries.claw-crony.config.agentCard.skills '[{"id":"chat","name":"chat","description":"Bridge chat/messages to OpenClaw agents"}]'

URL field rules

| Field | Points to | Example |

|-------|-----------|---------|

| `agentCard.url` | JSON-RPC endpoint (default) | `http://100.x.x.x:18800/a2a/jsonrpc` |

| `peers[].agentCardUrl` | Agent Card discovery (preferred) | `http://100.x.x.x:18800/.well-known/agent-card.json` |

**Do NOT confuse these two.** `agentCard.url` tells peers where to send messages. `agentCardUrl` tells you where to discover the peer.

Note: this plugin also serves the legacy alias `/.well-known/agent.json`, but the official SDK default is `/.well-known/agent-card.json`.

Step 4: Configure Server

openclaw config set plugins.entries.claw-crony.config.server.host '0.0.0.0'
openclaw config set plugins.entries.claw-crony.config.server.port 18800

Step 5: Configure Security

TOKEN=$(openssl rand -hex 24)
echo "Save this token: $TOKEN"

openclaw config set plugins.entries.claw-crony.config.security.inboundAuth 'bearer'
openclaw config set plugins.entries.claw-crony.config.security.token "$TOKEN"

Share this token with peers who need to send you messages.

Step 6: Configure Routing

openclaw config set plugins.entries.claw-crony.config.routing.defaultAgentId 'main'

Step 7: Add Peers

openclaw config set plugins.entries.claw-crony.config.peers '[
  {
    "name": "<PEER_NAME>",
    "agentCardUrl": "http://<PEER_IP>:18800/.well-known/agent-card.json",
    "auth": {
      "type": "bearer",
      "token": "<PEER_INBOUND_TOKEN>"
    }
  }
]'

For multiple peers, include all in one JSON array.

Step 8: Restart and Verify

openclaw gateway restart

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

# Verify peer connectivity
curl -s http://<PEER_IP>:18800/.well-known/agent-card.json | python3 -m json.tool

Step 9: Configure TOOLS.md

**This step is critical.** Without it, the agent won't know how to use A2A.

Read `references/tools-md-template.md` and append the A2A section to the agent's `TOOLS.md`, replacing placeholders with actual peer info.

For outbound messaging, use the SDK script (`scripts/a2a-send.mjs`).

To use the SDK script, ensure `@a2a-js/sdk` is installed in the plugin directory:

cd <WORKSPACE>/plugins/claw-crony && npm ls @a2a-js/sdk

Step 10: End-to-End Test

node <WORKSPACE>/plugins/claw-crony/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --message "Hello, what is your name?"

The script uses `@a2a-js/sdk` ClientFactory to auto-discover the Agent Card, handle authentication, and print the peer agent's response.

Async task mode (recommended for long-running prompts)

For prompts that may take longer than a typical request timeout (e.g., multi-round discussions, long summaries), use non-blocking mode + polling:

node <WORKSPACE>/plugins/claw-crony/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 and provide final conclusion"

This sends `configuration.blocking=false` and then polls `tasks/get` until the task reaches a terminal state.

Server-side timeout configuration (OpenClaw dispatch)

If you still see `Request accepted (no agent dispatch available)`, the underlying OpenClaw agent run may be timing out. Increase:

Optional: Route to a specific OpenClaw agentId (OpenClaw extension)

By default, the peer will route inbound A2A messages to `routing.defaultAgentId`.

To route a single request to a specific agentId (e.g., `coder`) on the peer, pass `--agent-id`:

node <WORKSPACE>/plugins/claw-crony/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --agent-id coder \
  --message "Run tests and summarize failures"

Note: this uses a non-standard `message.agentId` field understood by the Claw Crony A2A Gateway plugin. It is most reliable over JSON-RPC/REST. gRPC transport may drop unknown Message fields.

Network: Tailscale Setup (if needed)

When servers are on different networks, use Tailscale:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Authenticate via the printed URL (use same account on all servers)
tailscale ip -4  # Get the 100.x.x.x IP

Use Tailscale IPs in all A2A configuration. Verify with:

ping <OTHER_SERVER_TAILSCALE_IP>

Mutual Peering Checklist

For two-way communication, repeat Steps 1-9 on BOTH servers:

Troubleshooting

| Symptom | Cause | Fix |

|---------|-------|-----|

| "no agent dispatch available" | (1) No AI provider configured, or (2) OpenClaw agent dispatch timed out | Check `openclaw config get auth.profiles`; for long prompts use async mode (`--non-blocking --wait`) or increase `config.timeouts.agentResponseTimeoutMs` |

| "plugin not found: claw-crony" | Load path missing or wrong | Verify `plugins.load.paths` uses absolute path |

| Agent Card 404 | Plugin not loaded | Check `plugins.allow` includes `claw-crony` |

| Port 18800 connection refused | Gateway not restarted | Run `openclaw gateway restart` |

| Peer auth fails | Token mismatch | Verify peer config token matches target's `security.token` |

| Agent doesn't know about A2A | TOOLS.md not configured | Add A2A section from the template (Step 9) |