> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Relay API base URL is https://api.relayapp.im. Never use workers.dev origins.
> The contract is raw HTTPS and JSON at https://api.relayapp.im. The one optional published package is @relaymessenger/cli. Import nothing else.
> One send is one message. Mint a message_id (msg_ plus a lowercase Crockford ULID) before sending; it is the message's canonical id and the send's idempotency key, so a retry with the same id replays the stored message.
> Message content is immutable. There is no edit, unsend, or delete route, and no message versions or tombstones.
> A reply is a pointer: reply_to is { message_id, part_id? } and the client draws the quote from the target.
> Verify webhooks with the Standard Webhooks signature over the exact raw request body before parsing it.
> Webhooks and GET /v1/events read the same durable log and can run at once. The pull is plain: after is the last sequence you processed, and nothing is acknowledged.
> An agent in a group is an ordinary member. It receives every message from the sequence it joined at; there are no invocations and no invocation_id.

# OpenClaw

> Install Relay as a native OpenClaw channel so OpenClaw keeps the runtime and Relay carries the conversation.

Give an agent your OpenClaw gateway already runs a Relay conversation people can
message. OpenClaw keeps the runtime. Relay becomes one of its messaging channels.

Relay ships this as a native plugin. The plugin runs inside OpenClaw's gateway
lifecycle and uses OpenClaw's own routing, session, and outbound APIs.

## Requirements

| Requirement | Detail                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| OpenClaw    | 2026.4.5 or newer. The installer runs `openclaw plugins install --force`, and that option first shipped in 2026.4.5 |
| Node.js     | 22.18 or newer for the `relaymessenger` CLI                                                                         |

```bash theme={null}
npm install -g @relaymessenger/cli
relaymessenger pair
relaymessenger install-openclaw
```

`pair` asks you to approve the pairing in the Relay app, then leaves the Agent
Token on this computer.

On an older OpenClaw the third command stops with
`relaymessenger: OpenClaw plugin installation failed: error: unknown option '--force'`.
Upgrade OpenClaw and run it again.

## What the installer touches

* **Persists the bundled OpenClaw plugin archive.**
* **Runs OpenClaw's own plugin installer.**
* **Adds only the Relay plugin and channel fields** to `~/.openclaw/openclaw.json`. Unrelated OpenClaw configuration is preserved.
* **Stores the token in an owner-only file.** A different existing Relay identity is never overwritten.

## Current scope

| Surface | State                                                              |
| :-----: | ------------------------------------------------------------------ |
|    ✅    | Direct conversations                                               |
|    ⚠️   | Inbound media and voice memos arrive as a fetchable capability URL |
|    ❌    | Reactions and receipts do not start agent turns                    |
|    ❌    | Group conversations                                                |

<Warning>
  Treat capability URLs as secrets. Keep them out of analytics, public logs,
  model-training corpora, and any response outside the conversation that supplied
  them.
</Warning>

## How it behaves

| Area                              | Behavior                                                                                                                                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Network-free setup discovery      | Setup discovery makes no network calls. Installed packages load built JavaScript runtime entrypoints rather than resolving anything at setup time. |
| Ingress and envelopes             | Inbound events use OpenClaw's stable ingress and envelope helpers, so Relay messages enter the same routing path as any other OpenClaw channel.    |
| Replies survive a gateway restart | Replies go out through OpenClaw's own outbound path, so a reply that Relay accepted still sends after the gateway restarts.                        |

## Troubleshooting

```bash theme={null}
relaymessenger doctor
```

See [integration troubleshooting](/integrations/troubleshooting) for the
symptoms shared with every other integration. These are specific to this one.

| Symptom                                             | Cause and fix                                                                                                                                       |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| The installer fails with `unknown option '--force'` | Your OpenClaw predates 2026.4.5, where `plugins install --force` first shipped. Upgrade OpenClaw, then run `relaymessenger install-openclaw` again. |
| The agent cannot read an attachment                 | Media arrives as a capability URL rather than inline content, so the agent has to fetch the URL. See [Attachments](/guides/attachments).            |
| The installer refuses to overwrite                  | A different Relay identity is already configured, and that refusal is deliberate. Remove the existing identity first if you intend to replace it.   |

## Next steps

* [The relaymessenger CLI](/integrations/cli) for pairing and the approval guarantees
* [Your own runtime](/integrations/channel-plugin) for the same contract in a host runtime you maintain
* [Attachments](/guides/attachments) for how capability URLs work
* [Delivery model](/guides/delivery-model) for long polling, cursors, and recovery