Pairing
“Pairing” is WednesdayAI’s explicit owner approval step.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.- DM pairing (who is allowed to talk to the bot)
- Node pairing (which devices/nodes are allowed to join the gateway network)
1) DM pairing (inbound chat access)
When a channel is configured with DM policypairing, unknown senders get a short code and their message is not processed until you approve.
Default DM policies are documented in: Security
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
--identity <name> links the approved sender (<channel>:<id>) to that person after approval, so
turns from that account are attributed to them (see Identities). 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 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
- Default account:
- Non-default accounts read/write only their scoped allowlist file.
- Default account uses the channel-scoped unscoped allowlist file.
2) Node device pairing (iOS/Android/macOS/headless nodes)
Nodes connect to the Gateway as devices withrole: node. The Gateway
creates a device pairing request that must be approved.
Pair via Telegram (recommended for iOS)
If you use thedevice-pair plugin, you can do first-time device pairing entirely from Telegram:
- In Telegram, message your bot:
/pair - The bot replies with two messages: an instruction message and a separate setup code message (easy to copy/paste in Telegram).
- On your phone, open the OpenClaw iOS app → Settings → Gateway.
- Paste the setup code and connect.
- Back in Telegram:
/pair approve
url: the Gateway WebSocket URL (ws://...orwss://...)token: a short-lived pairing token
Approve a node device
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.
Notes
- The legacy
node.pair.*API (CLI:wednesdayai nodes pending/approve) is a separate gateway-owned pairing store. WS nodes still require device pairing.