Problem

Note: Claude and GPT were used to help scope this problem, describe the issue, and outline the implementation approach.

OpenClaw currently has two layers for group chats:

1. Access control — groupPolicy / allowlists determine if a message is permitted at all
2. Trigger gating — requireMention + mentionPatterns + native mention metadata + reply-to-bot detection determine if a permitted message actually triggers a response

For DMs, only the first layer exists:

1. Access control — dmPolicy (pairing / allowlist / open / disabled) determines if a sender can reach the bot

There is no second trigger-gating layer for DMs. This means once a sender is authorized, every DM triggers a reply. There is no way to say "this sender can reach the bot, but only messages matching specific patterns should trigger processing."

Use case

Someone running OpenClaw wants authorized DM contacts to be able to chat in the DM thread, but only have the bot respond when explicitly addressed via mention patterns like @openclaw. Without DM trigger gating, the bot responds to every single message from an authorized sender.

This is the same problem requireMention solves for groups — it just doesn't exist for DMs yet.

Proposed solution

Add an optional dmRequireMention flag at the channel config level that reuses the existing mentionPatterns infrastructure.

Config surface

{
  "channels": {
    "whatsapp": {
      "dmRequireMention": true
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": {
          "mentionPatterns": ["@openclaw"]
        }
      }
    ]
  }
}

Behavior

• If DM is unauthorized → blocked by dmPolicy (unchanged)
• If DM is authorized and dmRequireMention is not set or false → process normally (unchanged, backwards compatible)
• If DM is authorized and dmRequireMention: true and no text pattern matches → no reply (new)
• If DM is authorized and dmRequireMention: true and a pattern matches → normal reply (new)

MVP scope

• No reply-to-bot shortcut in DMs (every message in a DM is "to the bot," so this would collapse the gate)
• No pending-history buffering for skipped DMs (silently skip; can be revisited later)
• Reuses existing mentionPatterns from agent config — no new pattern list needed
• Applies to all DM-capable channels (WhatsApp initially, extensible to others)

Implementation areas

1. Config schema — add dmRequireMention boolean to ExtensionChannelConfig and validation
2. Channel runtime — in the DM processing branch (e.g., WhatsApp on-message.ts), check the flag and run mention pattern matching before processing
3. Reuse existing infrastructure — resolveMentionGating() from src/channels/mention-gating.ts and buildMentionRegexes() from mention pattern utilities already do the heavy lifting

Design decisions