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

# Pairing

# Pairing

"Pairing" is WednesdayAI's explicit **owner approval** step.

> [!NOTE]
>
> CLI commands use `wednesdayai` as the primary binary name. `openclaw` remains a backward-compatible legacy alias and both work interchangeably. Removal is staged under ADR 2057 and announced in advance.

It is used in two places:

1. **DM pairing** (who is allowed to talk to the bot)
2. **Node pairing** (which devices/nodes are allowed to join the gateway network)

Security context: [Security](https://docs.wednesdayai.dev/next/admin/gateway/security.md)

## 1) DM pairing (inbound chat access)

When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.

Default DM policies are documented in: [Security](https://docs.wednesdayai.dev/next/admin/gateway/security.md)

Pairing codes:

* 8 characters, uppercase, no ambiguous chars (`0O1I`).
* **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
* Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.

### Approve a sender

```bash theme={"dark"}
wednesdayai pairing list telegram
wednesdayai pairing approve telegram <CODE>
wednesdayai pairing approve telegram <CODE> --identity Alice
```

`--identity <name>` links the approved sender (`<channel>:<id>`) to that person after approval, so
turns from that account are attributed to them (see [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity)). The person
must already exist; `identity add` never runs implicitly.

Senders can also link their own chat account without an approval: a linked person sends `/link` to
the bot in a direct message, then enters the one-hour code in the web client under
**Account menu → Linked accounts**. That path is gated by `gateway.webClient.accountLinking`
(default `true`).

Supported built-in channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`, `feishu`. Extension channels (for example `matrix`, `msteams`, `zalo`, `bluebubbles`) that implement pairing also appear in `wednesdayai pairing list`. See [Channels](https://docs.wednesdayai.dev/next/admin/channels.md) for the full list of available channels.

### Where the state lives

Stored under `~/.openclaw/credentials/`:

* Pending requests: `<channel>-pairing.json`
* Approved allowlist store:
  * Default account: `<channel>-allowFrom.json`
  * Non-default account: `<channel>-<accountId>-allowFrom.json`

Account scoping behavior:

* Non-default accounts read/write only their scoped allowlist file.
* Default account uses the channel-scoped unscoped allowlist file.

Treat these as sensitive (they gate access to your assistant).

## 2) Node device pairing (iOS/Android/macOS/headless nodes)

Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
creates a device pairing request that must be approved.

### Pair via Telegram (recommended for iOS)

If you use the `device-pair` plugin, you can do first-time device pairing entirely from Telegram:

1. In Telegram, message your bot: `/pair`
2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
4. Paste the setup code and connect.
5. Back in Telegram: `/pair approve`

The setup code is a base64-encoded JSON payload that contains:

* `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
* `token`: a short-lived pairing token

Treat the setup code like a password while it is valid.

### Approve a node device

```bash theme={"dark"}
wednesdayai devices list
wednesdayai devices approve <requestId>
wednesdayai devices reject <requestId>
```

### Node pairing state storage

Pairing state lives in the session database (`pairing_*` tables), not in JSON files. On first
start, legacy `~/.openclaw/devices/*.json` and `~/.openclaw/nodes/*.json` files are imported once
and moved into `devices/.imported-<ts>/` and `nodes/.imported-<ts>/`; files added afterwards are
ignored. See [Gateway pairing storage](https://docs.wednesdayai.dev/next/admin/gateway/pairing.md#storage).

### Notes

* The legacy `node.pair.*` API (CLI: `wednesdayai nodes pending/approve`) is a
  separate gateway-owned pairing store. WS nodes still require device pairing.

## Related docs

* Security model + prompt injection: [Security](https://docs.wednesdayai.dev/next/admin/gateway/security.md)
* Updating safely (run doctor): [Updating](https://docs.wednesdayai.dev/next/admin/install/updating.md)
* Channel configs:
  * Telegram: [Telegram](https://docs.wednesdayai.dev/next/admin/channels/telegram.md)
  * WhatsApp: [WhatsApp](https://docs.wednesdayai.dev/next/admin/channels/whatsapp.md)
  * Signal: [Signal](https://docs.wednesdayai.dev/next/admin/channels/signal.md)
  * BlueBubbles (iMessage): [BlueBubbles](https://docs.wednesdayai.dev/next/admin/channels/bluebubbles.md)
  * iMessage (legacy): [iMessage](https://docs.wednesdayai.dev/next/admin/channels/imessage.md)
  * Discord: [Discord](https://docs.wednesdayai.dev/next/admin/channels/discord.md)
  * Slack: [Slack](https://docs.wednesdayai.dev/next/admin/channels/slack.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.