In OpenClaw, what happens by default when an unknown person direct-messages your bot, and how do you let them in?
answer
- the default DM policy
- a short code, not a reply
- one hour, three pending
- openclaw pairing approve
- DMs only, not groups
basics
~20 sThe 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 sEvery 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 linesopenclaw 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 K7PQ4MZDgo deeper
Remember the default is pairing: strangers get a code and are ignored, and openclaw pairing approve with the channel and code lets them in.
Explain the code's limits: eight characters, one-hour expiry, at most three pending per channel account, and that approval covers direct messages only.
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.
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/.