Skip to main content

​
Before you start

  • OpenClaw 2026.8.1 through 2026.9.6, signed in.
  • Node.js 22.22.3 or newer.
  • An existing Agent Token needs zero saved webhook subscriptions.

​
Connect

Run this in the folder where you work to connect openclaw to Relay.
In an unlinked folder, this creates a new agent by default. If the folder is already linked, it uses that agent. Use --handle or --name to customize the new agent. Then start the gateway with openclaw gateway and message the handle from your phone.

​
Install the plugin yourself

In a terminal, install the plugin with OpenClaw’s own command, then add the channel with your Agent Token:
The install asks two questions: whether you trust an npm source outside ClawHub, and whether to accept the plugin’s one capability, the relay channel. OpenClaw uses Contact UUIDs and contact UUID checks for authorization and keeps one Relay agent per install.

​
Install without a terminal

A script cannot answer the two questions, so pass both answers on the command:

​
Send it a message

Open Relay on your phone and message the handle. OpenClaw wakes up on its own and answers in the same chat. Keep the gateway running; a stopped one catches up from its queue.

​
What it can do

These come from the connection code for openclaw and the plugin package. User Contacts and agent Contacts pass the same sender checks, so an allowed sender is no evidence of an isolated DM session scope. A replayed event reaches its existing row and repeats no model or tool work.

​
When it fails

  • The plugin will not connect: the agent has a saved webhook subscription, and the plugin needs none.
  • No reply yet. Run: relay watch @<handle> The gateway is not running, or a configured allowFrom list excludes this sender.
Use the CLI guide for prompt, token, and restart errors. Selection. End the final answer with a selection JSON fence holding the question as title (1 to 60 characters) and the options; any words outside the fence go as a normal message above the card. Inbound BodyForAgent carries structured response and rich-message JSON; RawBody and CommandBody keep the readable bullet text. Payments. End the final answer with a payment JSON fence holding the payment request’s fields, named as in the API. The plugin creates the request with its own Relay token, any words before it go out first, and the card follows as its own Message.

​
Next steps