skip to content

DM & Group Access

dmPolicy decides whether strangers get a pairing code, are blocked or can talk freely; group rules decide who can trigger the bot in a room. Interviewers treat a wrong policy as a breach.

part ofAI coding toolsread it →
on this pageshow

explore

questions

5

In OpenClaw, what happens by default when an unknown person direct-messages your bot, and how do you let them in?

level: juniorimportance: must knowfreq 22%

answer

  1. the default DM policy
  2. a short code, not a reply
  3. one hour, three pending
  4. openclaw pairing approve
  5. DMs only, not groups

basics

~20 s

The default dmPolicy is pairing: an unknown sender receives an 8-character pairing code and the agent ignores the message. The operator admits them with openclaw pairing approve <channel> <code> or the Control UI, within one hour.

solid answer

~30 s

Every DM-capable channel has a `dmPolicy`, and its default is `pairing`. A sender who is not on the channel's allowlist gets a short pairing code (8 uppercase characters, ambiguous ones left out) and their message is **not processed**. The operator lists pending requests with `openclaw pairing list telegram` and approves one with `openclaw pairing approve telegram <CODE>` (`--notify` tells the requester), or uses **DM access requests** in the Control UI. Codes expire after one hour, and pending requests are capped at three per channel account. Approval admits that sender to direct messages only; group triggering still follows the group allowlists.

code

bash · 6 lines
bash
openclaw pairing list telegram
openclaw pairing approve telegram K7PQ4MZD --notify

# multi-account channel
openclaw pairing list --channel telegram --account work
openclaw pairing approve --channel telegram --account work K7PQ4MZD

go deeper

for a junior

Remember the default is pairing: strangers get a code and are ignored, and openclaw pairing approve with the channel and code lets them in.

for a middle

Explain the code's limits: eight characters, one-hour expiry, at most three pending per channel account, and that approval covers direct messages only.

for a senior

Show you know the side effects: the first CLI approval can bootstrap the command owner, and the pairing store is sensitive state kept apart from openclaw.json allowlists.

for a principal

Weigh pairing against a written allowlist: pairing suits an operator who meets new contacts ad hoc, while a fixed team is better served by allowFrom kept in reviewed config.

## What happens to a stranger's first message OpenClaw connects one Gateway to chat apps such as WhatsApp, Telegram, Slack, Discord and Signal. Each DM-capable channel carries a **direct-message policy**, `dmPolicy`, which the Gateway checks before a message ever reaches the agent. Its default is **`pairing`**. Under `pairing`, a sender who is not on the channel's allowlist does not get an answer from the agent. Instead: - the bot replies with a short **pairing code**; - the sender's message is **not processed** at all, so the model never sees it; - a pending request appears for the operator to approve or dismiss. This is the safe default for a personal assistant: anyone can find your bot's number or handle, but nobody can spend your tokens or reach your tools until you say so. ## The pairing code and its limits The code is designed to be read aloud or retyped without mistakes, and it is deliberately short-lived: - **8 characters**, uppercase, with ambiguous characters (`0`, `O`, `1`, `I`) left out; - it **expires after 1 hour**; - the bot sends the pairing message only when a new request is created, so a sender who keeps writing does not get a fresh code every time (roughly once per hour per sender); - pending requests are capped at **3 per channel account**; further requests are ignored until one expires or is approved. The cap matters on a bot whose number has leaked: a flood of strangers cannot fill the queue with hundreds of requests. ## Approving a request The operator has two equivalent ways in: 1. From the CLI on the Gateway host: `openclaw pairing list telegram` shows pending requests, and `openclaw pairing approve telegram <CODE>` admits the sender. `--notify` sends a confirmation back on the same channel, and `--account <id>` selects one account on a multi-account channel. 2. From the Control UI: **Settings → Channels → DM access requests** lists pending requests from every channel account whose policy is `pairing`, with **Approve** and **Dismiss**. **Dismiss** removes the current request, but it is not a permanent block: the same sender can ask again later. ## What approval grants, and what it does not Approval admits that sender to **direct messages on that channel account**. It does not: - let them trigger the bot in groups — group access is a separate layer with its own allowlists; - make them an administrator in general. There is one exception worth knowing. When no command owner exists yet (`commands.ownerAllowFrom` is empty), the CLI approval also records the approved sender as the **first command owner**, with an entry such as `telegram:123456789`. Owners can run owner-only commands and answer exec approval prompts. Later approvals never add or replace owners. The Control UI shows this elevation as a separate checkbox that needs `operator.admin` rather than applying it automatically. ## Where approvals are stored In OpenClaw 2026.9.9, pairing requests and approved senders live in the Gateway's SQLite state database, `~/.openclaw/state/openclaw.sqlite`, keyed by channel and account. Older Gateways wrote JSON files such as `<channel>-allowFrom.json` under `~/.openclaw/credentials/`; `openclaw doctor --fix` imports those into the database. Either way the store is sensitive, because its rows decide who can talk to your assistant, and it is kept apart from the `allowFrom` lists you write in `openclaw.json`. ## Mistakes operators make with pairing Most pairing trouble on a live install comes from a handful of habits: - **Approving codes nobody asked for.** A code arriving out of the blue is a stranger knocking. Check the sender ID and metadata in `openclaw pairing list` or the Control UI before approving. - **Approving on the wrong account.** On a multi-account channel the request belongs to one account; `approve` uses the account of the matching request, and `--account` narrows `list` to one of them. - **Expecting the bot to nag.** Because the code is sent only when a request is created, a sender who missed it will not get a reminder; they wait until the request lapses and write again. - **Treating the queue as unlimited.** With three pending requests already waiting on one account, a fourth person is simply ignored, which looks like a broken bot from their side. - **Assuming pairing is the only door.** Senders written into `allowFrom` in config are admitted without a code, and they are not automatically command owners either. ## A distinction that trips people up DM pairing is not the WhatsApp login QR code and not device pairing. The QR code links a WhatsApp account to the Gateway; `openclaw devices` approves phones and other nodes joining the Gateway; `openclaw pairing` approves *people* who message an account that is already connected. Three different flows, three different commands.

  • Does approving a pairing code from the CLI ever make that sender an administrator?
    Only once. If `commands.ownerAllowFrom` is empty, the CLI approval also records the sender as the first command owner, for example `telegram:123456789`, so first-time setups get someone who can run owner-only commands and answer exec approvals. After an owner exists, later approvals grant DM access only. The Control UI offers the same elevation as an explicit checkbox that needs `operator.admin`.
  • A stranger keeps messaging the bot; why don't they get a new code each time?
    The bot sends a pairing message only when a new request is created, so repeated DMs do not resend it while the request is pending; codes expire after an hour. Pending requests are also capped at three per channel account, and extra requests are ignored until one expires or is approved. Dismissing a request clears it but does not block the sender for good.

  • The bot answers any stranger until you configure an allowlist.
  • DM pairing means scanning the WhatsApp login QR code.
  • Approving a DM pairing code also lets that person trigger the bot in groups.
  • Pairing codes never expire, so an old one can be approved weeks later.
  • Dismissing a pairing request blocks that sender permanently.

Assumes OpenClaw 2026.9.9, where pairing approvals live in the SQLite state database instead of the older JSON files under ~/.openclaw/credentials/.

open as a page

What do OpenClaw's four `dmPolicy` values do, and why does `open` need `"*"` in `allowFrom`?

level: middleimportance: should knowfreq 12%

basics

~20 s

pairing (default) sends unknown senders a code to approve, allowlist blocks anyone not in allowFrom, open admits everyone, and disabled ignores all DMs. open is public only when allowFrom includes "*", so opening a bot is an explicit opt-in.

open as a page

In an OpenClaw group chat, what does `requireMention` change about when the agent answers, and what counts as a mention?

level: middleimportance: should knowfreq 9%

basics

~20 s

requireMention, on by default, makes an allowed group message trigger the agent only when it mentions the bot; other messages are kept as context. Native mentions, configured or name-derived mentionPatterns, and channel-specific replies or quotes of the bot count.

open as a page

Your OpenClaw bot, added to a busy community group, starts answering strangers; which settings decide who can trigger it, in what order, and what do you change?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Group access is checked as groupPolicy first, then group allowlists (rooms via groups, senders via groupAllowFrom), then mention gating. Strangers get answers when the policy is open or senders are unrestricted; restrict groupAllowFrom and keep requireMention on.

open as a page

How would you set OpenClaw's access policy for a bot serving a public community, and when would you refuse to share its Gateway?

level: principalimportance: nice to knowfreq 5%

basics

~20 s

Decide by what the agent can do: give a public bot minimal tools, mention-gated rooms and closed or allowlisted DMs. Because one Gateway is one trust boundary, run untrusted communities on a separate Gateway rather than beside private agents.

open as a page