Discord: add PluralKit sender identity resolver (#5838)

thewilloftheshadow · web-flow · commit 8e2b17e0c519 · 2026-01-31T19:50:06.000-06:00
* Discord: add PluralKit sender identity resolver * fix: resolve PluralKit sender identities (#5838) (thanks @thewilloftheshadow)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Discord: resolve PluralKit proxied senders for allowlists and labels. (#5838) Thanks @thewilloftheshadow.
 - Telegram: restore draft streaming partials. (#5543) Thanks @obviyus.
 - fix(lobster): block arbitrary exec via lobsterPath/cwd injection (GHSA-4mhr-g7xj-cg8j). (#5335) Thanks @vignesh07.
 
diff --git a/docs/channels/discord.md b/docs/channels/discord.md
@@ -340,6 +340,7 @@ ack reaction after the bot replies.
 - `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20; falls back to `messages.groupChat.historyLimit`; `0` disables).
 - `dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `dms["<user_id>"].historyLimit`.
 - `retry`: retry policy for outbound Discord API calls (attempts, minDelayMs, maxDelayMs, jitter).
+- `pluralkit`: resolve PluralKit proxied messages so system members appear as distinct senders.
 - `actions`: per-action tool gates; omit to allow all (set `false` to disable).
   - `reactions` (covers react + read reactions)
   - `stickers`, `emojiUploads`, `stickerUploads`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
@@ -355,6 +356,34 @@ Reaction notifications use `guilds.<id>.reactionNotifications`:
 - `all`: all reactions on all messages.
 - `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
 
+### PluralKit (PK) support
+
+Enable PK lookups so proxied messages resolve to the underlying system + member.
+When enabled, OpenClaw uses the member identity for allowlists and labels the
+sender as `Member (PK:System)` to avoid accidental Discord pings.
+
+```json5
+{
+  channels: {
+    discord: {
+      pluralkit: {
+        enabled: true,
+        token: "pk_live_..." // optional; required for private systems
+      }
+    }
+  }
+}
+```
+
+Allowlist notes (PK-enabled):
+
+- Use `pk:<memberId>` in `dm.allowFrom`, `guilds.<id>.users`, or per-channel `users`.
+- Member display names are also matched by name/slug.
+- Lookups use the **original** Discord message ID (the pre-proxy message), so
+  the PK API only resolves it within its 30-minute window.
+- If PK lookups fail (e.g., private system without a token), proxied messages
+  are treated as bot messages and are dropped unless `channels.discord.allowBots=true`.
+
 ### Tool action defaults
 
 | Action group   | Default  | Notes                              |
diff --git a/src/config/schema.ts b/src/config/schema.ts
@@ -328,6 +328,8 @@ const FIELD_LABELS: Record<string, string> = {
   "channels.discord.maxLinesPerMessage": "Discord Max Lines Per Message",
   "channels.discord.intents.presence": "Discord Presence Intent",
   "channels.discord.intents.guildMembers": "Discord Guild Members Intent",
+  "channels.discord.pluralkit.enabled": "Discord PluralKit Enabled",
+  "channels.discord.pluralkit.token": "Discord PluralKit Token",
   "channels.slack.dm.policy": "Slack DM Policy",
   "channels.slack.allowBots": "Slack Allow Bot Messages",
   "channels.discord.token": "Discord Bot Token",
@@ -674,6 +676,10 @@ const FIELD_HELP: Record<string, string> = {
     "Enable the Guild Presences privileged intent. Must also be enabled in the Discord Developer Portal. Allows tracking user activities (e.g. Spotify). Default: false.",
   "channels.discord.intents.guildMembers":
     "Enable the Guild Members privileged intent. Must also be enabled in the Discord Developer Portal. Default: false.",
+  "channels.discord.pluralkit.enabled":
+    "Resolve PluralKit proxied messages and treat system members as distinct senders.",
+  "channels.discord.pluralkit.token":
+    "Optional PluralKit token for resolving private systems or members.",
   "channels.slack.dm.policy":
     'Direct message access control ("pairing" recommended). "open" requires channels.slack.dm.allowFrom=["*"].',
 };
diff --git a/src/config/types.discord.ts b/src/config/types.discord.ts
@@ -6,6 +6,7 @@ import type {
   OutboundRetryConfig,
   ReplyToMode,
 } from "./types.base.js";
+import type { DiscordPluralKitConfig } from "../discord/pluralkit.js";
 import type { ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
 import type { DmConfig, ProviderCommandsConfig } from "./types.messages.js";
 import type { GroupToolPolicyBySenderConfig, GroupToolPolicyConfig } from "./types.tools.js";
@@ -150,6 +151,8 @@ export type DiscordAccountConfig = {
   execApprovals?: DiscordExecApprovalConfig;
   /** Privileged Gateway Intents (must also be enabled in Discord Developer Portal). */
   intents?: DiscordIntentsConfig;
+  /** PluralKit identity resolution for proxied messages. */
+  pluralkit?: DiscordPluralKitConfig;
 };
 
 export type DiscordConfig = {
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
@@ -276,6 +276,13 @@ export const DiscordAccountSchema = z
       })
       .strict()
       .optional(),
+    pluralkit: z
+      .object({
+        enabled: z.boolean().optional(),
+        token: z.string().optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict();
 
diff --git a/src/discord/monitor.test.ts b/src/discord/monitor.test.ts
@@ -149,6 +149,16 @@ describe("discord allowlist helpers", () => {
     expect(allowListMatches(allow, { name: "friends-of-openclaw" })).toBe(true);
     expect(allowListMatches(allow, { name: "other" })).toBe(false);
   });
+
+  it("matches pk-prefixed allowlist entries", () => {
+    const allow = normalizeDiscordAllowList(["pk:member-123"], ["discord:", "user:", "pk:"]);
+    expect(allow).not.toBeNull();
+    if (!allow) {
+      throw new Error("Expected allow list to be normalized");
+    }
+    expect(allowListMatches(allow, { id: "member-123" })).toBe(true);
+    expect(allowListMatches(allow, { id: "member-999" })).toBe(false);
+  });
 });
 
 describe("discord guild/channel resolution", () => {
diff --git a/src/discord/monitor/allow-list.ts b/src/discord/monitor/allow-list.ts
@@ -141,7 +141,7 @@ export function resolveDiscordUserAllowed(params: {
   userName?: string;
   userTag?: string;
 }) {
-  const allowList = normalizeDiscordAllowList(params.allowList, ["discord:", "user:"]);
+  const allowList = normalizeDiscordAllowList(params.allowList, ["discord:", "user:", "pk:"]);
   if (!allowList) {
     return true;
   }
@@ -161,7 +161,7 @@ export function resolveDiscordCommandAuthorized(params: {
   if (!params.isDirectMessage) {
     return true;
   }
-  const allowList = normalizeDiscordAllowList(params.allowFrom, ["discord:", "user:"]);
+  const allowList = normalizeDiscordAllowList(params.allowFrom, ["discord:", "user:", "pk:"]);
   if (!allowList) {
     return true;
   }
@@ -409,7 +409,7 @@ export function shouldEmitDiscordReactionNotification(params: {
     return Boolean(params.botId && params.messageAuthorId === params.botId);
   }
   if (mode === "allowlist") {
-    const list = normalizeDiscordAllowList(params.allowlist, ["discord:", "user:"]);
+    const list = normalizeDiscordAllowList(params.allowlist, ["discord:", "user:", "pk:"]);
     if (!list) {
       return false;
     }
diff --git a/src/discord/monitor/message-handler.preflight.ts b/src/discord/monitor/message-handler.preflight.ts
@@ -1,8 +1,5 @@
 import { ChannelType, MessageType, type User } from "@buape/carbon";
-import type {
-  DiscordMessagePreflightContext,
-  DiscordMessagePreflightParams,
-} from "./message-handler.preflight.types.js";
+
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
 import { shouldHandleTextCommands } from "../../auto-reply/commands-registry.js";
 import {
@@ -27,6 +24,7 @@ import {
   upsertChannelPairingRequest,
 } from "../../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { fetchPluralKitMessageInfo } from "../pluralkit.js";
 import { sendMessageDiscord } from "../send.js";
 import {
   allowListMatches,
@@ -45,13 +43,19 @@ import {
   resolveDiscordSystemLocation,
   resolveTimestampMs,
 } from "./format.js";
+import type {
+  DiscordMessagePreflightContext,
+  DiscordMessagePreflightParams,
+} from "./message-handler.preflight.types.js";
 import { resolveDiscordChannelInfo, resolveDiscordMessageText } from "./message-utils.js";
+import { resolveDiscordSenderIdentity, resolveDiscordWebhookId } from "./sender-identity.js";
 import { resolveDiscordSystemEvent } from "./system-events.js";
 import { resolveDiscordThreadChannel, resolveDiscordThreadParentInfo } from "./threading.js";
 
 export type {
   DiscordMessagePreflightContext,
   DiscordMessagePreflightParams,
+  DiscordSenderIdentity,
 } from "./message-handler.preflight.types.js";
 
 export async function preflightDiscordMessage(
@@ -65,12 +69,33 @@ export async function preflightDiscordMessage(
   }
 
   const allowBots = params.discordConfig?.allowBots ?? false;
-  if (author.bot) {
+  if (author.bot && params.botUserId && author.id === params.botUserId) {
     // Always ignore own messages to prevent self-reply loops
-    if (params.botUserId && author.id === params.botUserId) {
-      return null;
+    return null;
+  }
+
+  const pluralkitConfig = params.discordConfig?.pluralkit;
+  const webhookId = resolveDiscordWebhookId(message);
+  const shouldCheckPluralKit = Boolean(pluralkitConfig?.enabled) && !webhookId;
+  let pluralkitInfo: Awaited<ReturnType<typeof fetchPluralKitMessageInfo>> = null;
+  if (shouldCheckPluralKit) {
+    try {
+      pluralkitInfo = await fetchPluralKitMessageInfo({
+        messageId: message.id,
+        config: pluralkitConfig,
+      });
+    } catch (err) {
+      logVerbose(`discord: pluralkit lookup failed for ${message.id}: ${String(err)}`);
     }
-    if (!allowBots) {
+  }
+  const sender = resolveDiscordSenderIdentity({
+    author,
+    member: params.data.member,
+    pluralkitInfo,
+  });
+
+  if (author.bot) {
+    if (!allowBots && !sender.isPluralKit) {
       logVerbose("discord: drop bot message (allowBots=false)");
       return null;
     }
@@ -100,14 +125,14 @@ export async function preflightDiscordMessage(
     if (dmPolicy !== "open") {
       const storeAllowFrom = await readChannelAllowFromStore("discord").catch(() => []);
       const effectiveAllowFrom = [...(params.allowFrom ?? []), ...storeAllowFrom];
-      const allowList = normalizeDiscordAllowList(effectiveAllowFrom, ["discord:", "user:"]);
+      const allowList = normalizeDiscordAllowList(effectiveAllowFrom, ["discord:", "user:", "pk:"]);
       const allowMatch = allowList
         ? resolveDiscordAllowListMatch({
             allowList,
             candidate: {
-              id: author.id,
-              name: author.username,
-              tag: formatDiscordUserTag(author),
+              id: sender.id,
+              name: sender.name,
+              tag: sender.tag,
             },
           })
         : { allowed: false };
@@ -148,7 +173,7 @@ export async function preflightDiscordMessage(
           }
         } else {
           logVerbose(
-            `Blocked unauthorized discord sender ${author.id} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
+            `Blocked unauthorized discord sender ${sender.id} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
           );
         }
         return null;
@@ -349,7 +374,7 @@ export async function preflightDiscordMessage(
   const historyEntry =
     isGuildMessage && params.historyLimit > 0 && textForHistory
       ? ({
-          sender: params.data.member?.nickname ?? author.globalName ?? author.username ?? author.id,
+          sender: sender.label,
           body: textForHistory,
           timestamp: resolveTimestampMs(message.timestamp),
           messageId: message.id,
@@ -372,22 +397,26 @@ export async function preflightDiscordMessage(
   const hasControlCommandInMessage = hasControlCommand(baseText, params.cfg);
 
   if (!isDirectMessage) {
-    const ownerAllowList = normalizeDiscordAllowList(params.allowFrom, ["discord:", "user:"]);
+    const ownerAllowList = normalizeDiscordAllowList(params.allowFrom, [
+      "discord:",
+      "user:",
+      "pk:",
+    ]);
     const ownerOk = ownerAllowList
       ? allowListMatches(ownerAllowList, {
-          id: author.id,
-          name: author.username,
-          tag: formatDiscordUserTag(author),
+          id: sender.id,
+          name: sender.name,
+          tag: sender.tag,
         })
       : false;
     const channelUsers = channelConfig?.users ?? guildInfo?.users;
     const usersOk =
       Array.isArray(channelUsers) && channelUsers.length > 0
         ? resolveDiscordUserAllowed({
             allowList: channelUsers,
-            userId: author.id,
-            userName: author.username,
-            userTag: formatDiscordUserTag(author),
+            userId: sender.id,
+            userName: sender.name,
+            userTag: sender.tag,
           })
         : false;
     const useAccessGroups = params.cfg.commands?.useAccessGroups !== false;
@@ -408,7 +437,7 @@ export async function preflightDiscordMessage(
         log: logVerbose,
         channel: "discord",
         reason: "control command (unauthorized)",
-        target: author.id,
+        target: sender.id,
       });
       return null;
     }
@@ -452,12 +481,12 @@ export async function preflightDiscordMessage(
     if (Array.isArray(channelUsers) && channelUsers.length > 0) {
       const userOk = resolveDiscordUserAllowed({
         allowList: channelUsers,
-        userId: author.id,
-        userName: author.username,
-        userTag: formatDiscordUserTag(author),
+        userId: sender.id,
+        userName: sender.name,
+        userTag: sender.tag,
       });
       if (!userOk) {
-        logVerbose(`Blocked discord guild sender ${author.id} (not in channel users allowlist)`);
+        logVerbose(`Blocked discord guild sender ${sender.id} (not in channel users allowlist)`);
         return null;
       }
     }
@@ -501,6 +530,7 @@ export async function preflightDiscordMessage(
     client: params.client,
     message,
     author,
+    sender,
     channelInfo,
     channelName,
     isGuildMessage,
diff --git a/src/discord/monitor/message-handler.preflight.types.ts b/src/discord/monitor/message-handler.preflight.types.ts
@@ -4,6 +4,7 @@ import type { ReplyToMode } from "../../config/config.js";
 import type { resolveAgentRoute } from "../../routing/resolve-route.js";
 import type { DiscordChannelConfigResolved, DiscordGuildEntryResolved } from "./allow-list.js";
 import type { DiscordChannelInfo } from "./message-utils.js";
+import type { DiscordSenderIdentity } from "./sender-identity.js";
 import type { DiscordThreadChannel } from "./threading.js";
 
 export type LoadedConfig = ReturnType<typeof import("../../config/config.js").loadConfig>;
@@ -32,6 +33,7 @@ export type DiscordMessagePreflightContext = {
   client: Client;
   message: DiscordMessageEvent["message"];
   author: User;
+  sender: DiscordSenderIdentity;
 
   channelInfo: DiscordChannelInfo | null;
   channelName?: string;
diff --git a/src/discord/monitor/message-handler.process.ts b/src/discord/monitor/message-handler.process.ts
@@ -57,6 +57,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     ackReactionScope,
     message,
     author,
+    sender,
     data,
     client,
     channelInfo,
@@ -125,12 +126,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
         channelName: channelName ?? message.channelId,
         channelId: message.channelId,
       });
-  const senderTag = formatDiscordUserTag(author);
-  const senderDisplay = data.member?.nickname ?? author.globalName ?? author.username;
-  const senderLabel =
-    senderDisplay && senderTag && senderDisplay !== senderTag
-      ? `${senderDisplay} (${senderTag})`
-      : (senderDisplay ?? senderTag ?? author.id);
+  const senderLabel = sender.label;
   const isForumParent =
     threadParentType === ChannelType.GuildForum || threadParentType === ChannelType.GuildMedia;
   const forumParentSlug =
diff --git a/src/discord/monitor/native-command.ts b/src/discord/monitor/native-command.ts
diff --git a/src/discord/monitor/reply-context.ts b/src/discord/monitor/reply-context.ts
diff --git a/src/discord/monitor/sender-identity.ts b/src/discord/monitor/sender-identity.ts
diff --git a/src/discord/pluralkit.test.ts b/src/discord/pluralkit.test.ts
diff --git a/src/discord/pluralkit.ts b/src/discord/pluralkit.ts

Original file line number	Diff line number	Diff line change
`@@ -141,7 +141,7 @@ export function resolveDiscordUserAllowed(params: {`
`141`	`141`	`userName?: string;`
`142`	`142`	`userTag?: string;`
`143`	`143`	`}) {`
`144`		`- const allowList = normalizeDiscordAllowList(params.allowList, ["discord:", "user:"]);`
	`144`	`+ const allowList = normalizeDiscordAllowList(params.allowList, ["discord:", "user:", "pk:"]);`
`145`	`145`	`if (!allowList) {`
`146`	`146`	`return true;`
`147`	`147`	`}`
`@@ -161,7 +161,7 @@ export function resolveDiscordCommandAuthorized(params: {`
`161`	`161`	`if (!params.isDirectMessage) {`
`162`	`162`	`return true;`
`163`	`163`	`}`
`164`		`- const allowList = normalizeDiscordAllowList(params.allowFrom, ["discord:", "user:"]);`
	`164`	`+ const allowList = normalizeDiscordAllowList(params.allowFrom, ["discord:", "user:", "pk:"]);`
`165`	`165`	`if (!allowList) {`
`166`	`166`	`return true;`
`167`	`167`	`}`
`@@ -409,7 +409,7 @@ export function shouldEmitDiscordReactionNotification(params: {`
`409`	`409`	`return Boolean(params.botId && params.messageAuthorId === params.botId);`
`410`	`410`	`}`
`411`	`411`	`if (mode === "allowlist") {`
`412`		`- const list = normalizeDiscordAllowList(params.allowlist, ["discord:", "user:"]);`
	`412`	`+ const list = normalizeDiscordAllowList(params.allowlist, ["discord:", "user:", "pk:"]);`
`413`	`413`	`if (!list) {`
`414`	`414`	`return false;`
`415`	`415`	`}`