IdentyClaw A2A Gateway Component

IdentyClaw component service: OpenClaw plugin for A2A peer messaging with RODiT / Passport JWT authentication. JWT login and validation follow the same contract as idclawserver-idc (via @rodit/rodit-auth-be — not vendored). Forked from @a2anet/openclaw-a2a-plugin. See a2afork.md and UPSTREAM.md.

Role in the IdentyClaw stack

Install this plugin when Passport-authenticated agents need to call or accept A2A peers — not for IdentyClaw API login or HOLA (use identyclaw-tools for that). Outbound A2A uses the same NEAR Passport credential file layout as clienttest-idc.

Outbound and inbound agents exchange messages and files over the A2A protocol. A2A Utils powers the tool layer. Tailscale or a reverse proxy remains the operator's choice for exposing the gateway.

Your agent gets 6 outbound tools for peer messaging without a third-party chat app or email:

• a2a_get_agents to list the agents it's connected to
• a2a_get_agent to view an agent's skills in detail
• a2a_send_message to send messages and files. The agent will respond with a context_id and task_id, which your agent can use to continue the conversation.
• a2a_get_task to poll for a response if either agent loses connection or a response hasn't been recieved in over a minute
• a2a_view_text_artifact to view large text responses that have been minimised
• a2a_view_data_artifact to view large data responses that have been minimised

The plugin also allows your agent to receive messages and files via Tailscale or reverse proxies (nginx, Caddy, etc.). With RODiT inbound auth, peers authenticate with Passport JWTs (same contract as idclawserver-idc). Legacy API-key auth remains available for dev — see IdentyClaw usage. Each inbound message creates a separate conversation identified by the sender label and context_id, so your agent can run multiple peer threads at once.

📺 Reference demo (upstream)

The upstream project published a generic OpenClaw A2A walkthrough (API-key auth): OpenClaw A2A Plugin Demo. IdentyClaw deployments use RODiT JWT peers instead of static API keys — see IdentyClaw usage below.

📦 Installation

From ClawHub:

openclaw plugins install clawhub:@identyclaw/openclaw-a2a-plugin

From npm:

openclaw plugins install @identyclaw/openclaw-a2a-plugin

During development you can also install from a local path or git URL. Upstream package: @a2anet/openclaw-a2a-plugin (API-key auth only).

Restart the gateway:

openclaw gateway restart

Follow the set up instructions in "🔐 IdentyClaw usage (RODiT peers)", "📤 Sending Messages (outbound)", and/or "📥 Receiving Messages (inbound)".

Related IdentyClaw artifacts

identyclaw-tools and this plugin can share IDENTYCLAW_ACCOUNT_ID, IDENTYCLAW_NEAR_PRIVATE_KEY, and IDENTYCLAW_BASE_URL. HOLA stays application-layer via identyclaw_* tools; A2A peer calls use Passport JWTs automatically through this component.

🔐 IdentyClaw usage (RODiT peers)

This component implements the same peer JWT model as idclawserver-idc: inbound agents validate Passport JWTs on POST /a2a and expose /api/login* for peer outbound login; outbound agents call each peer's login endpoint via @rodit/rodit-auth-be instead of pre-shared A2A API keys.

Legacy API key auth remains available for development or non-RODiT peers (inbound.auth.provider: "apiKey", or allowApiKeyFallback: true with RODiT).

Environment variables

Outbound P2P login uses the NEAR Passport credentials file (same layout as clienttest-idc):

IDENTYCLAW_* env vars remain used by identyclaw-tools (HOLA, DID, identity) on the same host — they are not required for A2A outbound JWT login.

Outbound login calls login_server against each peer's /api/login (with subjectuniqueidentifier_url set to that peer's gateway base). JWTs are cached per outbound peer and scoped to that receiver's aud.

Keep credentials in env or secrets files — not in openclaw.json.

Embedding in OpenClaw chat / gateway (quiet mode)

When this plugin is enabled, OpenClaw loads it in chat (node dist/index.js chat) as well as the gateway. @rodit/rodit-auth-be logs JSON to stdout and node-config warns on stderr at import time, which can appear inline in the chat TUI.

This plugin lazy-loads rodit-auth-be only on the first inbound JWT validation or outbound login_server call, and applies quiet embed defaults before import:

Host env vars always win — IdentyClaw agents can set these in .env (e.g. via sync_quiet_plugin_env on bootstrap). Override per-plugin with inbound.auth.logLevel or outbound.auth.logLevel in openclaw.json until upstream rodit-auth-be defaults to library-quiet mode.

Outbound: call a RODiT peer

Configure the remote agent's Agent Card URL and enable dynamic JWT login. Do not set custom_headers.Authorization for RODiT peers; the plugin obtains and caches the Bearer token automatically (refreshes once on HTTP 401).

{
    "plugins": {
        "entries": {
            "identyclaw-a2a": {
                "enabled": true,
                "config": {
                    "outbound": {
                        "auth": {
                            "provider": "rodit",
                            "jwtCacheTtlSeconds": 300
                        },
                        "agents": {
                            "agent-b": {
                                "url": "http://openclaw-agent-b:18789/.well-known/agent-card.json"
                            }
                        }
                    }
                }
            }
        }
    }
}

When resolvePeersByTokenId is enabled, a2a_send_message can target a bare Passport token_id not listed in outbound.agents. The plugin tries GET /api/identity/token/{tokenId}/full (authenticated with your NEAR creds), reads metadata.webhook_url, and falls back to NEAR chain lookup (nearorg_rpc_tokenfromroditid) when the API is unavailable or has no webhook. It then registers {webhook_url}/.well-known/agent-card.json before normal P2P login. DN contactUri is not used for A2A discovery — it is identity contact metadata (often email:…). Use identyclaw_get_agent_identity when you need DN traits.

Peer identity: key outbound.agents by Passport token_id (recommended). The a2a_* tools expose and accept token_id for peers; legacy config aliases without a Passport token (e.g. dev self-loop self) use agent_id instead. | auth.logLevel | string | error | Winston level for rodit-auth-be when loaded | | agents.*.loginBaseUrl | string | derived from Agent Card URL | Override P2P login target when it differs from the card origin |

Non-auth custom_headers on individual agents still work (e.g. tracing headers).

Inbound: accept RODiT peer JWTs

{
    "plugins": {
        "entries": {
            "identyclaw-a2a": {
                "enabled": true,
                "config": {
                    "inbound": {
                        "publicBaseUrl": "https://agent-a.diholai.io",
                        "auth": {
                            "provider": "rodit",
                            "issuer": "https://api.identyclaw.com",
                            "audience": "<own passport owner_id>",
                            "identityClaim": "token_id"
                        },
                        "roditLogin": {
                            "loginMode": "p2p"
                        },
                        "agentCard": {
                            "name": "Juanelo",
                            "description": "IdentyClaw agent"
                        }
                    }
                }
            }
        }
    }
}

Verified peer JWTs map to a sender label (e.g. Passport token_id) used for inbound conversation routing, the same role apiKeys[].label plays for API-key auth.

publicBaseUrl and reverse proxies

By default, Agent Card URLs are derived from the incoming request (Host, X-Forwarded-Host, X-Forwarded-Proto). Behind a reverse proxy or when internal container DNS differs from the public hostname, set inbound.publicBaseUrl so discovery advertises the URL peers actually use:

"inbound": {
    "publicBaseUrl": "https://agent-a.diholai.io"
}

Set auth.audience to your own passport owner_id (the aud your agent mints on /api/login). See docs/jwt-audience-alignment.md for Tier 2 discovery. publicBaseUrl is for Agent Card discovery and is separate from JWT aud.

Example Agent Card endpoint after configuration:

https://agent-a.diholai.io/a2a

(publicBaseUrl + /a2a for single-agent mode; multi-agent mode appends /a2a/<agentId>.)

Internal vs external peer URLs

Use different URLs depending on who is calling:

Outbound peers use the discovery URL from their config (outbound.agents.<id>.url). Inbound agents use publicBaseUrl (when set) for the URL embedded in their own Agent Card.

External URL layout (same host)

A2A shares the gateway host with OpenClaw hooks but uses separate paths:

agent-a.example.com/hooks/agent              → OpenClaw hooks (unchanged)
agent-a.example.com/a2a                      → A2A JSON-RPC
agent-a.example.com/.well-known/agent-card.json  → A2A discovery

Do not mount A2A under /hooks/a2a unless you rewrite Agent Card URLs at the proxy.

Development fallback

For local testing without Passport JWTs, use API keys as upstream does, or enable RODiT with API key fallback:

"inbound": {
    "auth": { "provider": "rodit", "issuer": "…", "audience": "…", "allowApiKeyFallback": true },
    "apiKeys": [{ "label": "dev-peer", "key": "…" }]
}

Full rollout plan and staging test tiers: a2afork.md.

💡 Use Cases

• Connect IdentyClaw-managed OpenClaw agents across hosts using Passport token_id discovery and P2P JWT login
• Expose an agent's skills on the public A2A wire while keeping authentication aligned with idclawserver-idc
• Message peer agents by Passport identity without exchanging static API keys
• Bridge a sandboxed local agent to a production IdentyClaw agent over HTTPS with RODiT-scoped JWTs
• Continue multi-turn A2A tasks with file attachments between operator-run Passport peers
• Fall back to upstream API-key auth for local dev or non-RODiT peers

✨ Features

• Send messages to remote agents — 6 outbound tools (a2a_get_agents, a2a_get_agent, a2a_send_message, a2a_get_task, a2a_view_text_artifact, a2a_view_data_artifact) for communicating with any A2A agent
• Receive messages from remote agents — expose your OpenClaw agent as an A2A server with Agent Card discovery, JSON-RPC 2.0 endpoint, and SSE streaming
• Host multiple agents — expose several agents from one gateway, each with its own /a2a/<agentId> endpoint, Agent Card discovery URL, and card metadata
• Send and receive files — outbound messages can include local file paths (up to 1MB) or URLs; inbound files are saved locally
• Multi-turn conversations — continue conversations across multiple messages using context_id
• Long-running task support — if a2a_send_message times out, use a2a_get_task to monitor until the task reaches a terminal state
• Automatic artifact minimization — large text and data artifacts are automatically minimized for LLM context windows, with dedicated tools for detailed navigation
• Inbound authentication — RODiT / Passport JWT validation (IdentyClaw fork), plus API key-based auth with timing-safe comparison, per-key labels, and CLI key management
• Outbound RODiT login — dynamic JWT acquisition and cache refresh for IdentyClaw peers (no static Authorization headers in config)
• Public base URL — inbound.publicBaseUrl for correct Agent Card URLs behind reverse proxies
• Live Agent Card updates — update your agent's name, description, and skills at runtime with a2a_update_agent_card without restarting
• Tailscale integration — expose your agent to the internet via Tailscale Funnel, or restrict to your tailnet with Tailscale Serve
• Custom headers and outbound auth — per-agent custom headers with ${ENV_VAR} substitution for secrets
• Configurable timeouts and limits — control character limits, timeouts, poll intervals, and whether to enable task and file storage

🤖 A2A Core Concepts

The A2A protocol is a protocol for agent-to-agent communication supported by AWS, Azure, GCP, and 150+ enterprises.

• Agent Card — A JSON object at a publicly available URL (e.g. /.well-known/agent-card.json) that describes an agent (name, description, skills, etc).
• Message — a single communication turn between agents, containing one or more Parts. Each message has a role (user or agent).
• Part — content within a Message, Task, or Artifact: text (TextPart), JSON data (DataPart), or files (FilePart).
• Task — a unit of work with a unique ID. Useful for long-running tasks, agents can disconnect and poll intermittently.
• Artifact — output produced by a task (e.g. generated text, JSON data, files).

📤 Sending Messages (outbound)

Set Up

Configure at least one remote agent in your OpenClaw config. You just need the remote agent's Agent Card URL (and API key, if required). No Tailscale or port exposure needed.

{
    "tools": {
        "profile": "full"
    },
    "plugins": {
        "entries": {
            "identyclaw-a2a": {
                "enabled": true,
                "config": {
                    "outbound": {
                        "agents": {
                            "weather": {
                                "url": "https://weather-agent.example.com/.well-known/agent-card.json"
                            },
                            "search": {
                                "url": "https://example.com/search-agent/agent-card.json",
                                "custom_headers": {
                                    "Authorization": "Bearer ${SEARCH_API_KEY}"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "sandbox": {
        "tools": {
            "alsoAllow": [
                "a2a_get_agents",
                "a2a_get_agent",
                "a2a_send_message",
                "a2a_get_task",
                "a2a_view_text_artifact",
                "a2a_view_data_artifact"
            ]
        }
    }
}

Note: Header values support ${ENV_VAR} substitution so you can keep secrets out of your config file. The "sandbox" section is only required if sandbox is enabled.

Tools

The a2a_* tools are registered when at least one agent is configured (agents), or when RODiT outbound auth has resolvePeersByTokenId enabled (send by Passport token_id without preconfigured peers). The plugin is powered by A2A Utils, for example tool usage, results, etc. see A2A Utils JavaScript A2ATools.

a2a_get_agents

List all available remote A2A agents with names and descriptions.

No parameters.

Each Passport peer entry includes token_id (pass to other a2a_* tools). Legacy config aliases without a Passport token include agent_id instead. The Agent Card name is display metadata only — never use it as an identifier.

a2a_get_agent

Get detailed info about a specific agent, including skills.

a2a_send_message

Send a message to a remote agent and receive a structured response. The message is sent non-blocking — the tool streams or polls for updates until the task reaches a terminal state or the timeout is reached. If the task is still in progress after the timeout, the current task state is returned. Use a2a_get_task with the returned id to continue monitoring.

a2a_get_task

Check the progress of an A2A task that is still in progress. Monitors until the task reaches a terminal state or the timeout is reached. If still in progress, returns the current task state — call again to continue monitoring.

a2a_view_text_artifact

View text content from an artifact, optionally selecting a line or character range. Can select by line range OR character range, but not both.

a2a_view_data_artifact

View structured data from an artifact with optional JSON path, row, and column filtering.

📥 Receiving Messages (inbound)

Set Up

Other agents can discover and message your OpenClaw agent through the inbound endpoint. Follow the steps below to make your agent reachable.

1. Configure Inbound

{
    "tools": {
        "profile": "full"
    },
    "plugins": {
        "entries": {
            "identyclaw-a2a": {
                "enabled": true
            }
        }
    },
    "sandbox": {
        "tools": {
            "alsoAllow": ["a2a_update_agent_card"]
        }
    }
}

Note: The "sandbox" section is only required if sandbox is enabled.

Hosting Multiple Agents

A single gateway can expose several agents, each as its own addressable A2A endpoint. Add inbound.agents, keyed by agent ID. Each key is both the URL path segment and the OpenClaw agent ID that handles the message, so a message to /a2a/swe is routed to the OpenClaw agent swe. The key must match a configured OpenClaw agent ID, or requests to it will fail to route.

{
    "plugins": {
        "entries": {
            "identyclaw-a2a": {
                "enabled": true,
                "config": {
                    "inbound": {
                        "apiKeys": [{ "label": "flynn", "key": "..." }],
                        "agents": {
                            "swe": {
                                "agentCard": {
                                    "name": "SWE",
                                    "description": "Software engineering agent",
                                    "skills": [
                                        { "id": "code", "name": "Code", "description": "Writes and reviews code" }
                                    ]
                                }
                            },
                            "pmo": {
                                "agentCard": { "name": "PMO", "description": "Project management agent" }
                            }
                        }
                    }
                }
            }
        }
    }
}

Each agent gets its own JSON-RPC endpoint and Agent Card discovery URL:

The apiKeys / allowUnauthenticated settings apply to every agent on the host. Each agent can update its own card at runtime with a2a_update_agent_card — the edit is scoped to the calling agent and persisted under its inbound.agents.<agentId>.agentCard. When inbound.agents is omitted, a single agent is exposed on the default /a2a and /.well-known/agent-card.json paths, configured via inbound.agentCard.

2. Restart the Gateway

The plugin registers its HTTP endpoints on startup, so a restart is required:

openclaw gateway restart

3. Expose Your Gateway

You need to make your gateway's HTTP port (default 18789) reachable from the internet. Tailscale Funnel is the recommended approach — it gives your machine a public HTTPS URL with automatic TLS certificates, no port forwarding or DNS configuration needed. You can also use any reverse proxy (nginx, Caddy, etc.).

Note: The commands below were verified on macOS (Apple Silicon) with the Tailscale Mac app. The overall flow is the same on Linux and Windows, but the install and daemon setup will differ — consult the Tailscale install docs for your OS.

Install Tailscale

Install the Tailscale Mac app. The GUI app ships a Network Extension that plumbs MagicDNS into macOS's system resolver, so browsers and other apps can resolve your *.ts.net hostname.

After installing, launch the app, click the Tailscale menu bar icon, and sign in. The CLI is bundled with the app.

Confirm you're online:

tailscale status

You should see your node name, tailnet IP, and user.

Provision an HTTPS Certificate

Funnel needs a LetsEncrypt cert for your node's *.ts.net name. Running tailscale cert once provisions it and also confirms that HTTPS certificates and MagicDNS are enabled on your tailnet:

cd /tmp && tailscale cert "$(tailscale status --json | jq -r '.Self.DNSName | rtrimstr(".")')"

The cd /tmp is because tailscale cert writes <host>.crt and <host>.key to the current directory.

Enable Funnel

tailscale funnel --bg http://localhost:18789

On success, Tailscale prints the public URL, e.g.:

Available on the internet:

https://your-machine.tailXXXXXX.ts.net/
|-- proxy http://localhost:18789

If the funnel command fails with a policy error, you need to add the Funnel ACL attribute in the admin console (there is no CLI equivalent for editing ACLs):

"nodeAttrs": [
  {
    "target": ["autogroup:member"],
    "attr": ["funnel"]
  }
]

It can take up to a minute or two after tailscale funnel --bg returns before the public URL actually serves traffic from the open internet, because the Funnel edge has to propagate your config and finish TLS provisioning. If an external request returns a TLS error or "broken pipe", wait ~60s and retry.

Tailscale Serve (Tailnet-Only)

If you only need agents on your tailnet to reach you (not the public internet), use Tailscale Serve instead of Funnel:

tailscale serve --bg http://localhost:18789

With Serve, traffic is restricted to your tailnet, so disabling authentication is reasonable.

Stopping Funnel

tailscale funnel --https=443 off

4. Verify

Open your Agent Card URL in a browser:

https://your-machine.tail123.ts.net/.well-known/agent-card.json

You should see the JSON Agent Card (name, description, skills, etc.).

5. Generate an API Key

The Agent Card is public, but for other people to send messages to your OpenClaw you'll need to generate an API key for them:

openclaw a2a generate-key flynn

6. Customise Your Agent Card

The Agent Card will have default values. Once you've generated an API key, ask your OpenClaw to use the a2a_update_agent_card tool to update its Agent Card:

Update your Agent Card with the a2a_update_agent_card tool

7. Share Your URL and Key

Send your Agent Card URL and the generated API key to the person you generated it for. They'll need to install the plugin and add your OpenClaw as a remote agent with the headers:

"custom_headers": {
    "Authorization": "Bearer [GENERATED API KEY]"
}

That's it! Your friend's agent should now be able to send messages and files to your OpenClaw.

Tools

The a2a_update_agent_card tool is registered when inbound is configured (apiKeys, RODiT auth, or allowUnauthenticated).

a2a_update_agent_card

Live-update this agent's A2A Agent Card name, description, or skills. Changes take effect immediately and persist to config — no restart needed. At least one field must be provided. When inbound.agents is configured, the edit is scoped to the calling agent's own card.

🌐 HTTP Endpoints

With RODiT inbound auth, the Bearer token is a Passport JWT (not a static API key). Agent Cards advertise securitySchemes with HTTP Bearer + JWT when inbound.auth.provider is rodit.

Supported JSON-RPC Methods

Error Codes

💾 Data Storage

Tasks and file artifacts are saved locally, separated by direction. Task state lives under OpenClaw's state directory; file artifacts live under OpenClaw's workspace directory so the agent can access received files.

When inbound.agents is configured, each agent's inbound tasks and files are isolated under its agent ID — <state>/a2a/inbound/<agentId>/tasks/ and <workspace>/a2a/inbound/<agentId>/files/.

Outbound task/file storage can be disabled with outbound.taskStore: false and outbound.fileStore: false.

Publish to ClawHub

See PUBLISH.md:

npm run publish:clawhub:dry-run
npm run publish:clawhub

🛠️ Development

Install the dependencies:

make install

Install git hooks:

make install-hooks

Install the plugin:

openclaw plugins install /absolute/path/to/openclaw-a2a-plugin

Restart the gateway:

openclaw gateway restart

📄 License

Apache-2.0

🔗 IdentyClaw & upstream links

• This repo: discernible-io/openclaw-a2a-idc-plugin
• Passport server reference: discernible-io/idclawserver-idc — JWT contract, token metadata, OpenClaw integration guide
• Upstream A2A plugin: a2anet/openclaw-a2a-plugin — API-key auth baseline we forked
• A2A protocol: a2a-protocol.org
• A2A Net community: a2anet.com · Discord