OpenClaw DM pairing: the boundary it creates, and the gaps it leaves

This is a documentation-led boundary analysis. The configuration shown is a starting point, and the validation steps are proposed checks rather than reported hands-on results.

When an AI assistant sits behind a phone number or chat account, the first security question is simple: who is allowed to start a conversation with it? OpenClaw answers that question with channel-level DM policies, including pairing, allowlists, open access, and disabled access.

Short answer: DM pairing protects the agent from processing messages from unapproved senders. It gives an operator an explicit approval step before a sender can trigger the bot. It does not prove that the sender is safe, separate users on the same Gateway, filter hostile content, or provide approval for every file, command, browser action, or outbound message.

Start with the ingress decision

OpenClaw's pairing documentation defines DM pairing as an explicit access approval step. When a channel uses dmPolicy: pairing, an unknown sender receives a short pairing code and the message is not processed until an operator approves the request.

That makes pairing a trigger gate. It decides whether this sender can start an agent turn through this channel. It does not decide what the agent may do after the turn starts. The distinction matters because the agent may have access to tools, files, credentials, or other sessions that live behind the same Gateway.

The access-control documentation describes these policies as checks that happen before the inbound message is processed. Pairing is therefore useful against unsolicited activation and accidental exposure. It is better understood as controlled sender enrollment than as a full identity system. That last description is an editorial inference from the scope of the documented control.

What DM pairing does protect

It blocks the first agent turn

An unknown account does not get a normal answer simply by sending a message. Until approval, the message should not reach the normal agent-processing path. That reduces the chance that a stranger can immediately spend model tokens, ask for private information, or trigger an available tool.

The protection is narrow but useful. It applies to the DM ingress path for channels that implement OpenClaw's pairing API. It does not automatically cover every other path into the Gateway, such as groups, webhooks, the Control UI, or a separately configured node.

It makes approval visible to an operator

The Control UI shows pending requests with the sender ID and metadata before the operator chooses Approve or Dismiss. Codes expire after one hour, and pending requests are capped at three per channel account. Repeated DMs do not produce a new code until a new request is created.

Those limits create useful failure signals. A flood of unknown senders can fill the queue, and a legitimate request can wait until an old request expires or is cleared. A missing reply from an unknown sender may therefore be the expected result of pairing, not evidence that the model or channel is broken.

It grants a limited kind of access

Approval grants direct-message access only. The pairing documentation is explicit that it does not grant group access. A sender approved for a Telegram or WhatsApp DM still needs to pass the channel's group rules before it can trigger the assistant in a group.

DM pairing is also separate from linking a WhatsApp account or pairing a device node. A WhatsApp login QR connects an account to OpenClaw. DM approval controls people who message that account. Node pairing controls devices allowed to join the Gateway network. Similar words describe different trust decisions.

It records a durable sender decision

For channels using the pairing API, the current documentation says pending requests and approved senders are stored in the shared SQLite state database, keyed by channel and account. The database is sensitive because those records help decide who may reach the assistant.

That persistence is useful for normal restarts, but it does not remove the need for file protection. OpenClaw's security audit checks include permissions on the state directory, credentials directory, and session store. A logically correct pairing decision can still be exposed if another local user can read or modify the files that hold it.

It is not the same as command ownership

The approval path can interact with command ownership during first-time setup, but the concepts are separate. The Control UI offers an explicit option to make a sender the first command owner in a limited situation. The CLI can bootstrap an owner when no owner exists. Later pairing approvals grant DM access; they do not silently turn every approved sender into an administrator.

That distinction is worth checking before an assistant receives control-plane tools. A paired sender may be allowed to talk to the agent while still lacking owner-only commands.

What pairing leaves outside the boundary

Group access is a different check

Pairing an individual DM sender does not authorize that person inside a group. Group access has its own policy and allowlist, and many channels add a mention requirement. The order matters: group membership and sender checks happen before mention or reply activation.

A common operational mistake is to approve a DM request and then treat a silent group as a pairing failure. The group may still be correctly blocked. Test the DM and group paths separately, and keep public or mixed-membership rooms away from agents with broad tools.

A shared Gateway remains one trust boundary

OpenClaw's security trust model says that one Gateway is intended for one operator or a mutually trusting team. Everyone who can message a tool-enabled agent shares that agent's delegated tool authority inside the Gateway's trust model.

Pairing does not create a private host for each approved sender. It does not turn a shared Gateway into hostile multi-tenant infrastructure. If users are mutually adversarial, the documented answer is to split the trust boundary with separate Gateways and, preferably, separate OS users or hosts.

Session separation needs its own setting

The default DM session scope is main, which puts all direct messages into one session. For a multi-person inbox, the access-control guide recommends session.dmScope: per-channel-peer, or per-account-channel-peer for multi-account channels.

This separates conversation context. It does not create host-admin isolation. The same page also distinguishes trigger authorization from context visibility. With the default context behavior, quoted text, reply bodies, forwarded metadata, or thread history may still reach the model according to the channel's rules. Pairing answers who may trigger the turn; it does not decide every piece of context the turn can see.

Authorized messages can still contain hostile instructions

The prompt-injection guidance makes the wider problem clear: prompt injection does not require a public DM. Web pages, email, documents, attachments, fetched content, pasted logs, and code can all carry instructions that try to steer the model.

An approved sender can paste such content into a DM. A trusted sender can also ask for an unsafe action by mistake. Pairing filters the sender at the entrance; it does not label every sentence inside the conversation as safe. Treat external content as untrusted, keep secrets out of prompts, and use a restricted reader agent when the job is only to summarize material.

Pairing is not per-action approval

Tool access is a separate decision. OpenClaw's tool-permissions documentation keeps the gateway and cron tools sensitive because they can expose configuration or create persistent automation. A paired sender does not receive a blank cheque for those operations.

Node pairing has the same boundary lesson. It establishes device identity and token issuance, but it is not a per-command approval surface. The Gateway's node command policy and the node's own execution approvals still matter. Plugins run in process with the Gateway and should be treated as trusted code. Sandboxing, narrow filesystem access, and denied or approval-gated host execution provide the next layer.

A safer design for a small support bot

Consider a hypothetical Telegram assistant that reads a bounded support folder and drafts replies. The requirement is that one approved operator can ask for a draft, while the bot cannot run shell commands, change its configuration, or send the final reply without a separate review.

The pairing decision covers the first requirement: which Telegram sender may start the DM workflow. The rest needs additional configuration. The documented Gateway exposure runbook gives this shape as a starting baseline:

{
  gateway: { bind: "loopback", auth: { mode: "token", token: "<long-random-token>" } },
  session: { dmScope: "per-channel-peer" },
  agents: { defaults: { sandbox: { mode: "non-main" } } },
  tools: {
    profile: "messaging",
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false }
  },
  channels: { telegram: { dmPolicy: "pairing" } }
}

This is not a complete channel configuration, and the placeholder token must never be replaced with a real secret in an article or chat transcript. The important point is the separation: pairing chooses who can reach the agent, while sandboxing and tool policy limit what the agent can do.

Proposed checks at the edge

These are validation ideas, not tests performed for this article.

1. Send a DM from an unknown account. Confirm that a pairing request is created and that the message does not produce a normal agent response before approval.
2. Approve the sender. Confirm that the DM works, then verify that the same approval does not open a group that has its own allowlist or mention rule.
3. With an existing command owner configured, check an owner-only command from the newly paired sender. This distinguishes DM access from administrator status.
4. Add a second sender and inspect the session behavior. If users should not share context, verify per-channel-peer or the account-specific variant instead of relying on the pairing store.
5. Send an attachment or forwarded text containing an instruction to reveal a file. Confirm that the agent's tool policy, sandbox, and approval rules hold even though the sender is approved.
6. Run openclaw security audit --deep --json and review findings about open DMs, shared main sessions, executable tools, credentials, and Gateway exposure.

The security CLI documentation says the plain audit follows a read-only configuration and filesystem path, while --deep adds best-effort live Gateway probes and plugin-owned collectors. A clean output is evidence about the checks that ran. It is not proof that every content or deployment risk has disappeared.

Failure paths worth recognizing

• No reply from an unknown sender: this can be the intended pairing behavior. Check the pending queue before changing the model or channel.
• No new code: codes expire after an hour, repeated DMs do not resend one indefinitely, and the three-request cap can block new entries. Clear or wait for stale requests.
• DM works but a privileged command does not: inspect command ownership and tool policy. Do not broaden the pairing rule to solve an administrator-policy problem.
• DM works but a group stays silent: inspect group membership, sender rules, and mention gating separately.
• Several approved users see mixed context: inspect session.dmScope and contextVisibility. Pairing does not repair a shared main session.
• A Gateway may be overexposed: the runbook recommends returning to loopback, disabling channel DMs, rotating affected credentials, removing unexpected senders, reviewing logs and tool calls, and re-running the audit.

Which boundary do you need?

For one operator or a small group that already trusts one another, DM pairing is a sensible first gate. Give the resulting agent only the tools and data that group can safely share.

For a cooperative shared inbox, add per-peer session scope, a narrow tool profile, workspace limits, and explicit review around side effects. Treat the people as sharing a delegated authority model even when their conversations are separated.

For mutually untrusted users, pairing is insufficient. Use separate Gateways and operating-system boundaries. If the assistant reads public or external material, keep prompt injection in scope even when every human sender is approved.

DM pairing earns its place because it stops an unknown account at the first message boundary. It becomes dangerous only when that small success is mistaken for a complete security design.

Sources

1. OpenClaw: Pairing. Accessed 2026-09-13.
2. OpenClaw: Access control and allowlists. Accessed 2026-09-13.
3. OpenClaw: Security trust model. Accessed 2026-09-13.
4. OpenClaw: Prompt injection. Accessed 2026-09-13.
5. OpenClaw: Tool and agent permissions. Accessed 2026-09-13.
6. OpenClaw: Gateway exposure runbook. Accessed 2026-09-13.
7. OpenClaw: Security audit checks. Accessed 2026-09-13.