A2A Server — Inbound Task Listener

Run an A2A protocol listener that allows this OpenClaw instance to receive tasks routed from the A2A API Gateway. The listener runs as a background HTTP service.

Sidecar Principle

This skill is strictly an OpenClaw sidecar — it receives tasks FROM the A2A API Gateway in whatever format the gateway sends them. The gateway's A2A protocol is the contract; OpenClaw's listener just speaks it. Never assume what the sending system looks like — it could be any agent that routes tasks through the gateway. The listener implements the gateway's expected endpoints as-is.

Configuration

The listener reads configuration from a shared a2a.conf file (located in the a2a-client skill directory), with auto-detection fallbacks for local settings.

Priority order: CLI flags → env vars → a2a.conf → auto-detected defaults

Run a2a-register/a2a-setup.sh to configure interactively, or set env vars / create a2a-client/a2a.conf.

When to Use

• Start the listener — When this OpenClaw instance needs to receive inbound A2A tasks
• Stop the listener — When shutting down or pausing inbound task reception
• Check listener status — When verifying the A2A service is running

Endpoints

The listener (a2a-listener.py) handles these routes:

Auth

Inbound tasks (POST /v1/a2a/tasks/send) require a Bearer token matching the configured A2A_GATEWAY_API_KEY. If no API key is configured, auth checks are disabled (with a warning at startup). Health checks and agent card lookups are unauthenticated.

Tools

start.sh — Start the Listener

./start.sh [--port PORT] [--bind ADDR]

Starts the A2A listener in the background. All other settings are read from a2a.conf or env vars.

# Start with defaults (from a2a.conf or auto-detected)
./start.sh

# Custom port and bind address
./start.sh --port 8200 --bind 0.0.0.0

Saves the PID to a2a-listener.pid for management. Logs to a2a-listener.log.

stop.sh — Stop the Listener

./stop.sh

Gracefully stops the A2A listener using the PID file.

a2a-listener.py — The Listener Process

Python HTTP server that implements the A2A protocol endpoints. Started by start.sh. Can also be run directly:

# Run directly (foreground)
python3 a2a-listener.py

# With custom settings via env vars
LISTENER_PORT=8200 BIND_ADDR=0.0.0.0 A2A_GATEWAY_API_KEY=your-key python3 a2a-listener.py

All configuration is loaded from a2a.conf, env vars, or auto-detected — no hardcoded values.

OpenClaw Invocation — Real Responses

When an inbound task arrives, the listener invokes the local OpenClaw instance to produce a real response. The invocation method is configurable, with automatic fallback:

Priority: A2A_OPENCLAW_COMMAND → A2A_OPENCLAW_URL → auto-detect openclaw CLI → error

Auto-Detection

If neither A2A_OPENCLAW_COMMAND nor A2A_OPENCLAW_URL is set, the listener checks if the openclaw CLI is on PATH. If found, it runs:

openclaw agent -m "<message>" --session-id <session_id> --json

This uses OpenClaw's built-in agent runtime and returns real AI responses. The --session-id flag ensures continuity within a conversation thread.

Response Format

On success:

{"id": "task-123", "status": "completed", "result": {"kind": "text", "content": "<actual AI response>"}}

On failure (invocation error, timeout, etc.):

{"id": "task-123", "status": "failed", "result": {"kind": "text", "content": "<error message>"}}

Configuration Error

If no invocation method is available at all, the task response will have status: "failed" with a message explaining how to configure OpenClaw access.

Typical Workflow

1. Configure → Run a2a-register/a2a-setup.sh or create a2a.conf
2. Register → Use the a2a-register skill to register this instance in the A2A API Gateway
3. Start → ./start.sh to begin listening for inbound tasks
4. Verify → curl http://YOUR_IP:8100/health to confirm it's running
5. Receive — The gateway routes tasks to this listener automatically
6. Stop → ./stop.sh when done