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#

• OpenClaw ≥ 2026.3.0 installed and running on each server
• Network connectivity between servers (Tailscale recommended, LAN or public IP also work)
• Node.js ≥ 22

Step 1: Install the Plugin#

bash

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:

bash

openclaw config get agents.defaults.workspace

Step 2: Register Plugin in OpenClaw#

Get current allowed plugins first to avoid overwriting:

bash

openclaw config get plugins.allow

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

bash

# 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#

bash

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#

FieldPoints toExampleagentCard.urlJSON-RPC endpoint (default)http://100.x.x.x:18800/a2a/jsonrpc``peers[].agentCardUrlAgent 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#

bash

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#

bash

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#

bash

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

Step 7: Add Peers#

bash

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#

bash

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:

bash

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

Step 10: End-to-End Test#

bash

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:

bash

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:

• plugins.entries.claw-crony.config.timeouts.agentResponseTimeoutMs (default: 300000)

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:

bash

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:

bash

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:

bash

ping <OTHER_SERVER_TAILSCALE_IP>

Mutual Peering Checklist#

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

• Server A: plugin installed, Agent Card configured, token generated
• Server B: plugin installed, Agent Card configured, token generated
• Server A: has Server B in peers (with B's token)
• Server B: has Server A in peers (with A's token)
• Server A: TOOLS.md updated with Server B peer info
• Server B: TOOLS.md updated with Server A peer info
• Both: openclaw gateway restart done
• Both: Agent Cards accessible ( curl /.well-known/agent-card.json)
• Test: A → B message/send works
• Test: B → A message/send works

Troubleshooting#

SymptomCauseFix"no agent dispatch available"(1) No AI provider configured, or (2) OpenClaw agent dispatch timed outCheck 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 wrongVerify plugins.load.paths uses absolute pathAgent Card 404Plugin not loadedCheck plugins.allow includes claw-cronyPort 18800 connection refusedGateway not restartedRun openclaw gateway restartPeer auth failsToken mismatchVerify peer config token matches target's security.tokenAgent doesn't know about A2ATOOLS.md not configuredAdd A2A section from the template (Step 9)