a2a-setup

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