Who can talk to your bot?

In OpenClaw, pairing means an explicit approval step before trust is granted. There are two different pairing stories people mix up:

• DM pairing (chat access) — who is allowed to talk to your assistant over a messenger (Telegram, WhatsApp, Discord, Slack, Signal, Matrix, etc.). Unknown senders can receive a short code; their messages stay queued until you approve.
• Node / device pairing (gateway access) — which phones, laptops, or headless nodes may join your Gateway as a device with the node role (and optional scope upgrades later). This is not the same as “someone messaged my bot.”

Both exist because a self-hosted assistant is a security boundary: you want defaults that fail closed. Read Security for DM defaults, sandboxing, and exec policy alongside this page.

When a channel uses DM policy pairing, unknown senders get a pairing code and their traffic is not processed until you approve.

• Codes — eight uppercase characters without ambiguous glyphs (no 0O1I confusion). Codes expire after about one hour. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
• Backpressure — pending DM pairing requests are capped per channel (default: three). Further requests wait until one expires or is approved.
• open vs pairing — dmPolicy: "open" is only truly public when the effective allowlist includes the wildcard "*". If you see open with concrete allowFrom entries, runtime still only admits those senders; pairing-store approvals do not widen access beyond that.

Approve from the CLI

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Use --channel / --account when you run multiple accounts on one channel type; --json helps scripts. pairing approve can send a confirmation back with --notify when you want the user to see approval on-channel.

First owner bootstrap

If commands.ownerAllowFrom is still empty when you approve a DM pairing code, OpenClaw also records the approved sender as the command owner (for example telegram:123456789). That owner can run privileged commands and act on dangerous operations later. Only the first approval does this—later pairing approvals add DM access but do not keep expanding the owner list.

If you paired before owner bootstrap existed, run openclaw doctor; it warns when no owner is configured and suggests a openclaw config set commands.ownerAllowFrom ... fix.

Groups are separate

Approving a DM pairing code does not automatically authorize someone in group chats. Group delivery still follows groupAllowFrom, groups, or per-channel overrides. Plan both surfaces if your bot sits in DMs and large rooms.

Reusable sender groups

When the same people should be trusted across several channels, define top-level accessGroups with type: "message.senders" and reference accessGroup:yourGroup from each channel allowlist. Details and JSON examples live in the upstream access-groups doc linked below.

Where DM pairing state lives

Under ~/.openclaw/credentials/ you will find pairing and allowlist files (names vary by channel and account). Treat them as sensitive: they gate who can talk to your assistant. Non-default accounts use scoped filenames; the default account uses the channel-wide file.

Nodes connect to the Gateway with role: node. The Gateway creates a device pairing request you approve explicitly unless you have opted into a narrow auto-approve rule (see below).

CLI approval

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

If a device reconnects asking for broader scopes or a different role, OpenClaw keeps the old approval and opens a new pending upgrade request—compare devices list output before you approve.

Telegram-first flow (common on iOS)

With the device-pair plugin you can drive first-time pairing from Telegram: message /pair, copy the setup payload the bot sends, paste it into the mobile app’s Gateway settings, then use /pair pending in Telegram to review IDs and approve. Treat the setup payload like a password while it is valid—it encodes the WebSocket URL and a short-lived bootstrap token.

Optional auto-approve (locked-down LANs only)

For tightly controlled networks you may configure gateway.nodes.pairing.autoApproveCidrs with explicit CIDRs so first-time node requests with no extra scopes auto-approve. Operator clients, browsers, Control UI, and WebChat still require manual approval; scope or key changes still require human review.

Where node pairing state lives

Under ~/.openclaw/devices/: pending.json (short-lived requests) and paired.json (approved devices and tokens). The pairing record is the durable contract for roles; stray token rows cannot silently widen access.

Legacy note: the older node.pair.* API (openclaw nodes pending|approve|...) is a separate gateway-owned store; WebSocket nodes still expect the device pairing flow above.

• “I approved pairing but groups still fail” — DM approval does not grant group rights. Check groupAllowFrom / group policies for that channel.
• “Node keeps asking again” — new scopes or keys spawn a new pending request; approve or reject explicitly after reading devices list.
• “I only run one channel but CLI says pick a channel” — pass the channel id positionally or with --channel; multi-account Telegram/WhatsApp needs --account.

Policy names, per-channel quirks, and bootstrap rules evolve. Use the project docs when you need verbatim JSON keys or the newest channel list:

• Pairing (channels + nodes) — canonical pairing narrative.
• CLI: openclaw pairing — every flag for list/approve.
• Gateway pairing — gateway-owned pairing details.
• Access groups — shared allowlists across channels.
• Security — defaults, prompt-injection context, DM policies.

Pairing is one layer; combine it with exec approvals, sandboxing and DM policy, and safe remote access when you expose the Gateway beyond loopback.