DM Policies & Group Behavior

+15 Mana ✨
OpenClaw DM Policies(DOCUMENTATION)OpenClaw Group Configuration(DOCUMENTATION)

Introduction

Controlling who can interact with your OpenClaw assistant is just as important as setting it up. DM policies govern how individual users gain access to direct message conversations with your bot, while group policies determine how the assistant behaves in group chats. Getting these policies right prevents unauthorized usage, manages costs, and ensures a good user experience across all your connected channels.

Key Concepts

  • DM Policy: A configuration that controls how users are authorized to have direct message conversations with your assistant. OpenClaw supports four modes: pairing, allowlist, open, and disabled.
  • Pairing Mode: The default DM policy where users must enter a time-limited code to link their account. Codes are valid for 1 hour and each channel supports a maximum of 3 active pairing codes.
  • Allowlist Mode: A DM policy where only explicitly listed user identifiers (phone numbers, usernames, or IDs) can interact with the assistant.
  • Open Mode: A DM policy where anyone can message the assistant without any authentication or authorization.
  • Disabled Mode: A DM policy that completely blocks all direct message interactions.
  • Group Policy: A configuration that controls how the assistant participates in group chats. Modes are open, allowlist, and disabled.
  • Mention-Gating: A group behavior where the assistant only responds when explicitly mentioned (e.g., @bot), preventing it from responding to every message in a busy group.
  • allowFrom / groupAllowFrom: Per-channel configuration fields that specify which users or groups are permitted to interact with the assistant.

Real World Context

A company deploys an OpenClaw assistant for internal use. They want employees to be able to DM the bot on Slack after a simple pairing process, but they do not want random people on WhatsApp messaging it. For their public Discord server, they want the bot available in specific channels but only when mentioned, so it does not drown out human conversation. This scenario uses pairing mode for Slack DMs, allowlist mode for WhatsApp DMs, and open group policy with mention-gating for Discord.

Deep Dive

DM Policies

OpenClaw provides four DM policies that can be configured globally or per channel.

Pairing (default): This is the most balanced option. When a new user messages your bot, they receive a prompt asking for a pairing code. You generate codes through the OpenClaw admin interface or CLI. Each code is valid for 1 hour and each channel supports a maximum of 3 active pairing codes at any time. Once paired, the user has persistent access.

json
{
  "dmPolicy": "pairing",
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+14155551234"]
    }
  }
}

In this configuration, the global DM policy is set to pairing. However, the WhatsApp channel also has an allowFrom field. The allowFrom field acts as an additional filter on top of the DM policy. Even in pairing mode, only the listed phone numbers can initiate a pairing flow on WhatsApp. This gives you two layers of control: the policy determines the mechanism, and allowFrom determines who can use that mechanism.

Allowlist: Only users whose identifiers appear in the allowFrom list can message the bot. No pairing flow is needed; if you are on the list, you are in.

json
{
  "dmPolicy": "allowlist",
  "channels": {
    "telegram": {
      "enabled": true,
      "allowFrom": ["alice_dev", "bob_ops"]
    }
  }
}

Here, only the Telegram users alice_dev and bob_ops can DM the bot. All other users are silently ignored. The format of identifiers in allowFrom varies by channel: phone numbers for WhatsApp, usernames or IDs for Telegram, user IDs for Discord.

Open: Anyone can message the bot without restriction. Use this only for public-facing bots where you want maximum accessibility and have controls in place for rate limiting and cost management.

json
{
  "dmPolicy": "open"
}

This single line makes your bot accessible to everyone on every enabled channel. Be cautious with this setting.

Disabled: No DM interactions are allowed on any channel. This is useful when you want your bot to operate exclusively in group contexts.

json
{
  "dmPolicy": "disabled"
}

With DMs disabled, the bot only responds in group chats where group policy allows it.

Group Policies

Group policies control how the assistant behaves in group chats. The three modes are:

Open: The bot can participate in any group it is added to.

Allowlist: Only groups whose identifiers appear in groupAllowFrom are served.

json
{
  "groupPolicy": "allowlist",
  "channels": {
    "discord": {
      "enabled": true,
      "groupAllowFrom": ["1234567890123456789", "9876543210987654321"]
    }
  }
}

The groupAllowFrom field lists Discord channel IDs (not guild IDs) where the bot is allowed to respond. Messages in unlisted channels are ignored.

Disabled: The bot does not respond in any group chat.

Mention-Gating

In busy group chats, you rarely want the bot responding to every single message. Mention-gating solves this by requiring users to explicitly mention the bot (e.g., @assistant or @botname) before it processes a message. This is independent of the group policy and can be enabled alongside any group mode.

json
{
  "groupPolicy": "open",
  "mentionGating": true
}

With mention-gating enabled and an open group policy, the bot is available in all groups but only responds when directly mentioned. This prevents the assistant from being "always-on" in conversations where it is not needed, reducing noise and API costs.

Common Pitfalls

  • Leaving DM policy on open in production: Open DM policy with no allowFrom restrictions means anyone who discovers your bot can interact with it. This can lead to unexpected API costs and potential abuse.
  • Confusing allowFrom with groupAllowFrom: The allowFrom field controls individual DM access (user identifiers), while groupAllowFrom controls group chat access (group/channel identifiers). Putting a group ID in allowFrom will not work, and vice versa.
  • Forgetting mention-gating in active groups: Without mention-gating, the bot tries to respond to every message in the group. In a busy Discord server, this creates a flood of responses and rapidly consumes API tokens.

Best Practices

  • Start with pairing mode: It is the default for a reason. Pairing gives you control over who accesses the bot while still being easy for authorized users to get started.
  • Always enable mention-gating in groups: Unless you have a dedicated channel where the bot should respond to everything, mention-gating prevents noise and saves resources.
  • Use per-channel allowFrom for fine-grained control: Even with a global DM policy, you can restrict each channel's allowFrom independently. This lets you have open access on your internal Slack but strict allowlists on public-facing channels.

Summary

  • OpenClaw supports four DM policies: pairing (default, time-limited codes), allowlist (explicit user lists), open (unrestricted), and disabled (no DMs).
  • Pairing codes are valid for 1 hour with a maximum of 3 active codes per channel.
  • Group policies come in three modes: open, allowlist (using groupAllowFrom), and disabled.
  • Mention-gating prevents the bot from responding to every group message by requiring an explicit @mention.
  • The allowFrom and groupAllowFrom fields provide per-channel control on top of global policies.
✓ Completed