OpenClaw Pairing Explained

Pairing is one of the healthiest ideas in OpenClaw because it refuses to pretend that every inbound chat or new device should be trusted by default. The product calls it an explicit owner-approval step, and that is exactly how you should think about it: a small friction point that protects much bigger trust boundaries.

What it is

The docs split pairing into two lanes. DM pairing decides who is allowed to talk to the bot in paired channels. Node pairing decides which devices are allowed to join the gateway network as role: node. They share the same core posture, which is that unknown senders and unknown devices do not get automatic conversational or operational access just because they can reach the surface.

The important thing to understand is that OpenClaw usually separates the human-facing idea from the underlying storage and runtime machinery. Once you know where the state lives, how the gateway applies it, and which tool or config surface controls it, the feature stops feeling magical and starts feeling dependable.

How it works in practice

For DMs, unknown senders receive a short code and their message is not processed until you approve it. The docs spell out the pairing-code rules: eight characters, uppercase, ambiguous characters removed, roughly one-hour expiry, and a small cap on pending requests per channel. For nodes, the gateway creates a device pairing request that you inspect and approve. Telegram can also serve as the first-time pairing bridge for node setup through the device-pair plugin.

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

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

• DM pairing and node pairing are related ideas but distinct stores and approval flows.
• Approving a DM pairing code does not automatically grant group-command rights.
• Node upgrade requests create new pending requests instead of silently broadening an approved device.
• The relevant state files live under ~/.openclaw/credentials and ~/.openclaw/devices and should be treated as sensitive.

Operator guidance

Operationally, pairing is where you slow down on purpose. Before approving a device, compare the requested role and scopes with what is already approved. Before approving a new DM surface, confirm the channel and account you are affecting. This is not bureaucracy. It is the layer that keeps a helpful agent from becoming a casually reachable production system.

The biggest misunderstanding is assuming pairing is just a one-time welcome flow. It is actually a durable security boundary. The docs are especially clear that already paired devices do not get broader access silently, and that group authorization is separate from DM approval. If you remember those two distinctions, you avoid most of the surprising behavior people blame on the runtime.

Good pairing feels slightly inconvenient in the exact places where blind trust would have been expensive. If you want the practical operator layer on top of the official docs, The OpenClaw Playbook turns setups like this into real workflows, guardrails, and day-to-day patterns you can actually run.

I also like that OpenClaw keeps the setup code and bootstrap token story explicit for node onboarding. If something contains the gateway URL and the short-lived bootstrap credential, treat it like a password while it is valid. That mindset alone will save people from some very avoidable mistakes.

The storage paths are worth remembering because they explain a lot of “why did this stop working?” moments. DM pairing requests live under ~/.openclaw/credentials/, while device pairing lives under ~/.openclaw/devices/. Those files are effectively part of your access-control plane.

The pending-request limits matter too. DM codes expire after about an hour and pending requests are capped per channel by default, which keeps pairing from turning into an unbounded queue of forgotten approvals.