Skip to main content
Decide when an inbound message counts as a mention, without reimplementing the shared policy. Part of the Building channel plugins guide.

Inbound mention policy

Keep inbound mention handling split in two layers:
  • plugin-owned evidence gathering
  • shared policy evaluation
Use openclaw/plugin-sdk/channel-mention-gating for mention-policy decisions. Use openclaw/plugin-sdk/channel-inbound only when you need the broader inbound helper barrel. Good fit for plugin-local logic:
  • reply-to-bot detection
  • quoted-bot detection
  • thread-participation checks
  • service/system-message exclusions
  • platform-native caches needed to prove bot participation
Good fit for the shared helper:
  • requireMention
  • explicit mention result
  • implicit mention allowlist
  • command bypass
  • final skip decision
Preferred flow:
  1. Compute local mention facts.
  2. Pass those facts into resolveInboundMentionDecision({ facts, policy }).
  3. Use decision.effectiveWasMentioned, decision.shouldBypassMention, and decision.shouldSkip in your inbound gate.
matchesMentionWithExplicit(...) returns a boolean. hasAnyMention, isExplicitlyMentioned, and canResolveExplicit come from the channel’s own native mention metadata (message entities, reply-to-bot flags, and similar); supply false/undefined values when your platform cannot detect them. api.runtime.channel.mentions exposes the same shared mention helpers for bundled channel plugins that already depend on runtime injection: buildMentionRegexes, matchesMentionPatterns, matchesMentionWithExplicit, implicitMentionKindWhen, resolveInboundMentionDecision. If you only need implicitMentionKindWhen and resolveInboundMentionDecision, import from openclaw/plugin-sdk/channel-mention-gating to avoid loading unrelated inbound runtime helpers.