A2a Server

Run an A2A inbound task listener that lets this OpenClaw instance receive tasks from other agents via the A2A API Gateway. Use when: (1) starting/stopping th...

Security Scan

The skill's files, instructions, and runtime behavior are coherent with its stated purpose (an inbound A2A listener that invokes a local OpenClaw instance); nothing in the bundle appears to be performing unrelated or hidden actions, but it does expose configuration choices that have security implications if misconfigured.

Purpose & Capability

Name/description match the actual code and scripts: a background HTTP listener that accepts inbound A2A tasks and forwards them to a local OpenClaw invocation method (shell command, HTTP URL, or CLI). Required runtime (python3), start/stop scripts, and config file lookups are all consistent with that purpose.

Instruction Scope

SKILL.md and start/stop scripts limit behavior to starting/stopping the HTTP listener and describing expected endpoints. However, the listener will (by design) run arbitrary configured invocation methods: a shell command template (A2A_OPENCLAW_COMMAND), or POST to any A2A_OPENCLAW_URL. Those invocation options mean inbound message content may be passed to external commands or remote HTTP endpoints — expected for the skill's function but a potential exfiltration vector if misconfigured. Also, if no API key is configured the code intentionally disables auth checks (explicit in doc and code), which is a security-sensitive configuration option.

Install Mechanism

No install script or remote download; repo is instruction+script based. All files are local Python and shell scripts. No network install or extraction from untrusted URLs is present in the bundle.

Credentials

The skill does not require any credentials up-front, but reads several env vars (A2A_GATEWAY_API_KEY, A2A_OPENCLAW_URL, A2A_OPENCLAW_URL_API_KEY, A2A_OPENCLAW_COMMAND, AGENT_*, etc.) which are appropriate for its role. Important behavioral notes: if A2A_GATEWAY_API_KEY is empty auth checks are disabled; A2A_OPENCLAW_URL or A2A_OPENCLAW_COMMAND can route task payloads (including message content and metadata) to remote endpoints or arbitrary shell commands — expected but sensitive.

Persistence & Privilege

The skill does not request permanent 'always' inclusion, does not change other skills' configs, and only writes PID/log files within its own directory. It reads a shared a2a-client/a2a.conf if present (for config sharing), but does not modify other skill configurations.

Assessment

This skill appears to do what it says, but take these safety steps before enabling it: (1) Set A2A_GATEWAY_API_KEY to require bearer auth — leaving it empty disables authentication. (2) Prefer invoking a local openclaw CLI over configuring A2A_OPENCLAW_URL to a remote endpoint unless you trust that endpoint; any configured command or URL will receive incoming message content and metadata. (3) Review and control the A2A_OPENCLAW_COMMAND value (it can execute arbitrary shell commands). (4) Check any shared a2a-client/a2a.conf the skill may read to avoid unintentionally sharing credentials or endpoints. (5) Bind the listener to a restricted interface (e.g., localhost or private IP) and firewall the port if you do not want it publicly reachable. (6) Inspect logs (a2a-listener.log) — they may contain message snippets and metadata. If you want stronger guarantees, keep the listener on an isolated network, or only start it when you explicitly need to receive tasks.

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

Setting	Auto-detected Default	Description
Port	8100	Listen port (LISTENER_PORT)
Bind Address	Tailscale IP or first NIC	Local bind address (BIND_ADDR)
Agent Slug	hostname -s (lowercase)	Agent identifier (AGENT_SLUG)
Agent Name	Slug (capitalized)	Display name (AGENT_NAME)
Agent URL	http://{bind_addr}:{port}	Agent endpoint (AGENT_URL)
Capabilities	chat,code,research	Comma-separated (AGENT_CAPABILITIES)
Auth Type	bearer	Auth method (AGENT_AUTH_TYPE)
API Key	empty	Bearer token — if empty, auth checks are disabled (A2A_GATEWAY_API_KEY)
OpenClaw Command	auto	Shell command template; {message} and {session_id} placeholders (A2A_OPENCLAW_COMMAND)
OpenClaw URL	empty	HTTP API URL for chat completions (A2A_OPENCLAW_URL)
OpenClaw URL API Key	empty	Bearer token for HTTP API (A2A_OPENCLAW_URL_API_KEY)
OpenClaw Timeout	60	Max seconds to wait for response (A2A_OPENCLAW_TIMEOUT)

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:

Method	Path	Description
GET	/health	Health check — returns {"status": "ok", "agent": "<slug>"}
GET	/v1/a2a/agents/{slug}	Returns the agent card for this OpenClaw instance
POST	/v1/a2a/tasks/send	Receives an inbound A2A task (requires Bearer auth if API key is set)

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

Env Var	Description	Example
A2A_OPENCLAW_COMMAND	Shell command template; {message} and {session_id} are replaced	openclaw agent -m "{message}" --session-id {session_id} --json
A2A_OPENCLAW_URL	HTTP API URL to POST the task to	(any HTTP chat/completions endpoint)
A2A_OPENCLAW_URL_API_KEY	Bearer token for the HTTP URL	(optional, only used with A2A_OPENCLAW_URL)
A2A_OPENCLAW_TIMEOUT	Max seconds to wait for a response	60 (default)

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