A2A Register — Agent Registration Management#

Register and manage this OpenClaw instance as an A2A agent in the A2A API Gateway. Other agents discover this instance through the gateway registry, so registration is required before receiving inbound tasks.

Sidecar Principle#

This skill is strictly an OpenClaw sidecar — it uses the A2A API Gateway's existing admin API to register, deregister, heartbeat, and check status. The gateway's admin endpoints are the contract; OpenClaw is just a participant. Never assume what other registered agents look like or how they connect — they could be MC2, another OpenClaw, or anything else that speaks A2A. These scripts call the gateway's admin API as-is.

Configuration#

All scripts read from a shared a2a.conf file (located in the a2a-client skill directory). The gateway URL must be configured — there are no hardcoded defaults.

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

SettingAuto-detected DefaultDescriptionGateway URL_none — required_A2A API Gateway URL ( A2A_GATEWAY_URL)Agent Namehostname -s (lowercase)Display name ( AGENT_NAME)Agent Slughostname -s (lowercase)URL-safe identifier ( AGENT_SLUG)Agent URLhttp://{Tailscale IP}:{port}Agent endpoint ( AGENT_URL)Capabilitieschat,code,researchComma-separated ( AGENT_CAPABILITIES)Auth TypebearerAuth method ( AGENT_AUTH_TYPE)API Key_empty_For listener auth ( A2A_GATEWAY_API_KEY)

Quick Setup#

bash

# Interactive setup — creates a2a.conf for you
./a2a-setup.sh

# Non-interactive (env vars required)
A2A_GATEWAY_URL=http://GATEWAY_IP:8090 A2A_GATEWAY_API_KEY=your-key ./a2a-setup.sh --non-interactive

When to Use#

• Setup — First time configuring this instance for A2A
• Register — When this OpenClaw instance needs to be discoverable by other A2A agents
• Deregister — When going offline or removing this instance from the gateway
• Heartbeat — Periodically signal that this instance is alive and reachable
• Status — Check whether this instance is registered and view its current configuration

Tools#

a2a-setup.sh — Interactive Configuration#

bash

./a2a-setup.sh [--non-interactive] [--conf PATH]

Creates or updates the shared a2a.conf file. In interactive mode, prompts for all values with auto-detected defaults. In non-interactive mode, reads from environment variables.

bash

# Interactive (recommended first time)
./a2a-setup.sh

# Non-interactive (for scripting)
A2A_GATEWAY_URL=http://GATEWAY_IP:8090 \
A2A_GATEWAY_API_KEY=your-key \
AGENT_SLUG=my-agent \
./a2a-setup.sh --non-interactive

register.sh — Register This Agent#

bash

./register.sh [--gateway-url URL] [--name NAME] [--slug SLUG] [--url URL] [--capabilities CAPS]

Registers this OpenClaw instance in the A2A API Gateway. The script:

1. Obtains a JWT via GET /v0/admin/bootstrap
2. Checks if the agent slug already exists ( GET /v0/admin/agents)
3. If new → POST /v0/admin/agents to create it
4. If exists → PUT /v0/admin/agents/{id} to update it

Idempotent — safe to run multiple times.

bash

# Register with defaults (from a2a.conf / auto-detected)
./register.sh

# Override specific values
./register.sh --name "My Agent" --slug my-agent --url http://MY_IP:8100

# Override gateway URL
./register.sh --gateway-url http://GATEWAY_LAN_IP:8090

deregister.sh — Remove This Agent#

bash

./deregister.sh [--gateway-url URL] [--slug SLUG]

Removes this OpenClaw instance from the gateway registry. Other agents will no longer be able to discover or route tasks to it.

bash

./deregister.sh

heartbeat.sh — Send Liveness Signal#

bash

./heartbeat.sh [--gateway-url URL] [--slug SLUG]

Sends a heartbeat to the gateway ( PATCH /v0/admin/agents/{id}/heartbeat) to signal that this instance is alive and reachable. Useful for cron jobs or periodic health checks.

bash

# One-time heartbeat
./heartbeat.sh

# In a cron (every 5 minutes)
*/5 * * * * /path/to/skills/a2a-register/heartbeat.sh

status.sh — Check Registration Status#

bash

./status.sh [--gateway-url URL] [--slug SLUG]

Checks whether this OpenClaw instance is registered in the gateway and shows its current configuration (URL, capabilities, status).

bash

./status.sh

Typical Workflow#

1. Setup → ./a2a-setup.sh to create your a2a.conf
2. Register → ./register.sh to add this instance to the gateway
3. Start listener → Use a2a-server skill's start.sh to begin receiving tasks
4. Heartbeat → Run ./heartbeat.sh periodically (or set up a cron)
5. Status → ./status.sh to verify registration
6. Deregister → ./deregister.sh when going offline

Gateway API#

EndpointMethodPurpose/v0/admin/bootstrapGETObtain admin JWT/v0/admin/agentsGETList all registered agents/v0/admin/agentsPOSTRegister a new agent/v0/admin/agents/{id}PUTUpdate an existing agent/v0/admin/agents/{id}DELETERemove an agent/v0/admin/agents/{id}/heartbeatPATCHSignal liveness

Environment Variables#

VariableDescriptionA2A_GATEWAY_URLGateway URL (required if not in a2a.conf)A2A_GATEWAY_API_KEYAPI key for listener authAGENT_NAMEAgent display nameAGENT_SLUGAgent identifierAGENT_URLAgent endpoint URLAGENT_CAPABILITIESComma-separated capabilitiesLISTENER_PORTListener port (default: 8100)