OpenClaw allowlists, pairing, and group mention security

OpenClaw’s useful features are exactly why the security model matters. The Gateway can connect messaging channels to an agent that may run shell commands, read and write files, drive a browser, and send messages. A basic but high-impact failure path is an untrusted or compromised sender reaching an over-privileged agent; the controls below reduce that exposure alongside conventional host, dependency, credential, and network security.

OpenClaw’s own ordering is the right one (security docs):

1. Identity first — who can talk to the bot (DM pairing / allowlists / explicit open).
2. Scope next — where it can act (groups, tools, sandbox, device permissions).
3. Model last — assume the model can be manipulated; limit blast radius.

This article assumes you already installed the gateway (personal gateway setup).

dmPolicy="open" and groupPolicy="open" are last-resort settings. Prefer pairing and allowlists unless you fully trust every participant who can reach the bot. Tool-enabled open DMs are a public remote-control surface.

Every approved sender can become a path into whatever the agent can read: mail, files, browser sessions, customer data in tools. Approve people the way you would approve SSH keys — sparingly, revocably, and with a named reason.

Trust model in one paragraph

OpenClaw documents a personal assistant trust model: one trusted operator boundary per gateway. It is not a hostile multi-tenant boundary. If mutually untrusted users can message one tool-enabled agent, they share that agent’s delegated authority. Split gateways (and ideally OS users/hosts) when trust boundaries differ.

Authenticated Gateway access is operator-level. sessionKey is a routing selector, not an authorisation token. Do not invent a false sense of per-user tenancy on a shared personal gateway.

DM access: pairing, allowlist, open, disabled

Every DM-capable channel supports a DM policy (names vary slightly by channel; see current docs):

Approve deliberately:

openclaw pairing list <channel>
openclaw pairing approve <channel> <code>

Details: pairing.

Practical rule for personal use: keep pairing or strict allowlist. Approve only your own accounts and, at most, a tiny set of co-operators who share the trust boundary.

Two allowlist layers

1. DM allowlist (allowFrom / channel-specific equivalents)

Who may DM the bot. Current OpenClaw stores pending and approved sender rows in ~/.openclaw/state/openclaw.sqlite, keyed by channel and account. Older credential JSON files are legacy migration inputs, not the current authorization source (pairing state documentation). Treat the SQLite file as sensitive authorization state and back it up consistently with the gateway state.

2. Group allowlist

Which groups/channels/guilds the bot accepts at all — plus who may trigger it inside a group (groupPolicy="allowlist" + groupAllowFrom on supported channels).

Check order matters: group policy/allowlists first, then mention/reply activation. Replying to a bot message does not bypass groupAllowFrom.

Example shape (adapt stable sender IDs and agent naming to the current channel schema):

{
  channels: {
    whatsapp: {
      dmPolicy: 'allowlist',
      allowFrom: ['+15555550123'],
      groupPolicy: 'allowlist',
      groupAllowFrom: ['+15555550123'],
      groups: { '<approved-group-id>': { requireMention: true } },
    },
  },
  agents: {
    list: [{ id: 'main', groupChat: { mentionPatterns: ['@openclaw'] } }],
  },
}

Customise mention patterns so requireMention matches your bot names, not a generic string everyone types by accident.

Group mentions are a safety control

In busy groups, an always-listening agent will:

• Burn tokens on noise
• Act on prompt injection buried in jokes, pasted logs, or linked pages
• Leak context across people who share a room but not a trust boundary

Require mention (or equivalent activation) unless the room is a dedicated agent channel with a locked membership list.

Even with mention gating, untrusted content the bot fetches (web pages, attachments, emails) can carry instructions. Prompt injection is not solved by system prompts. Hard controls are tool policy, approvals, sandboxing, and who can talk to the bot at all.

Prompt injection does not require public DMs. If only you can message the bot but the bot reads the open web or shared inboxes, adversarial text can still arrive inside tool results.

Session isolation for multi-person DMs

Default behaviour can route DMs into a main session for continuity. If more than one person can DM the bot, isolate sessions:

{ session: { dmScope: 'per-channel-peer' } }

Without isolation, one person’s context can bleed into another’s turn. That is both a privacy bug and a prompt-injection amplifier.

Network exposure

Before you celebrate remote chat:

• Prefer gateway.bind: "loopback" for personal installs
• Require gateway auth tokens for any non-loopback access
• Treat Tailscale Serve/Funnel and reverse proxies as exposure events — walk the exposure runbook if you use one
• Never publish the Control UI (:18789) or model ports to the public internet without auth

Run:

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix   # narrow safe remediations only

Triage order from the docs: lock open DMs/groups with tools first, then public network exposure, then browser control remotes, then file permissions, then plugins.

Hardened baseline (starting point)

OpenClaw publishes a compact hardened example: local bind, token auth, messaging-oriented tool profile, deny lists for automation/runtime/fs groups, exec denied with ask: "always", elevated tools off, WhatsApp-style pairing + mention requirements. Copy the intent into your config from the live security page rather than freezing an outdated paste forever — then re-audit.

Trusted single-operator defaults may allow host exec without prompts (security="full", ask="off"). That is intentional UX for a personal assistant, not proof you should leave it on once channels widen. Tighten when your threat model includes anyone else’s messages.

Quarterly review questions

Every quarter (or after any channel expansion):

1. Who is on each allowlist, and why?
2. Which groups still have the bot, and do they still require mention?
3. Did anyone enable open DM/group policy “temporarily”?
4. Are exec/browser tools wider than last quarter’s threat model?
5. Has openclaw security audit been run since the last config change?

Write the answers down. Security posture that only exists in someone’s head fails the first vacation.

Discord / Slack / Teams notes (same principles)

Channel UIs differ; the security questions do not:

• Which guilds/workspaces/teams are allowlisted?
• Which users may DM?
• Must the bot be @mentioned in channels?
• Are bot tokens stored only on the Gateway host?

For Discord and Slack, OpenClaw documents per-surface allowlists (guilds, channels, and related keys — confirm current schema). Apply the same “closed by default” posture as WhatsApp/Telegram examples. A public Slack workspace with an open agent and exec tools is an incident waiting for a curious coworker.

Workplace chat often contains personal data of employees and customers. Connecting OpenClaw to Slack/Teams is a processing activity: know the lawful basis, who can summon the bot, and what tool outputs are retained in ~/.openclaw.

Concrete failure stories (patterns, not folklore)

These are the shapes incidents take:

Forgotten open DM policy

A bot token leaks into a public repo or a friend shares the handle. Strangers DM “summarise my ~/Documents” style prompts. With tools on, the model may try.

Group without mention

The bot reacts to every thread. Someone pastes a malicious README. The agent fetches and follows it.

Shared family WhatsApp

Teenagers and contractors share a group that can @ the bot. Session continuity mixes contexts. A joke becomes a shell command request.

Remote UI without auth

:18789 bound on LAN “so the phone can reach it.” Guest Wi-Fi users get a control plane.

Each story is prevented by pairing/allowlists, mention rules, session isolation, and bind/auth — not by a sterner system prompt.

Revocation and offboarding

Build a tiny runbook:

1. Remove the identity from allowFrom or revoke its pairing entry using the current CLI/UI; verify the canonical SQLite authorization row is gone through supported tooling, not by editing the database directly.
2. Rotate channel bot tokens if the person ever saw them.
3. Review ~/.openclaw sessions for sensitive remnants.
4. Re-run openclaw security audit.
5. If they had node pairing, unpair the device.

Treat this like recovering an SSH key, not like unfollowing a bot.

Operator checklist

• DM policy is pairing or strict allowlist
• allowFrom contains only trusted identities
• Groups require mention; group allowlists set
• dmScope isolated if multiple DM senders exist
• Gateway loopback (or authenticated remote only)
• openclaw security audit clean enough to sleep
• High-risk tools off until identity is locked
• State dir permissions not world-readable
• Offboarding steps documented for your channels

Revoke pairing and allowlist entries when a phone number, Slack user, or contractor engagement ends. Forgotten allowlist rows are standing invitations. Export or delete session history that contains other people’s personal data when the lawful basis ends.

Allowlists and pairing are not bureaucracy. They are the difference between a personal gateway and an unauthenticated agent API attached to your shell. Configure them before skills, heartbeat, and convenience automations — covered next in skills, heartbeat, and approvals.