From f5375d95476fbff78b65b5eede41195f3540991d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 29 Apr 2026 18:43:31 +0100 Subject: [PATCH] fix(discord): document mention formatting in agent prompt --- docs/channels/discord.md | 2 ++ extensions/discord/src/channel.test.ts | 8 ++++++++ extensions/discord/src/channel.ts | 1 + 3 files changed, 11 insertions(+) diff --git a/docs/channels/discord.md b/docs/channels/discord.md index ac324dcd426..804aab4a864 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -579,6 +579,8 @@ Example: - configured mention patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - implicit reply-to-bot behavior in supported cases + When writing outbound Discord messages, use `<@USER_ID>` to link a user. Do not use the legacy `<@!USER_ID>` nickname mention form. Use `<#CHANNEL_ID>` for channels and `<@&ROLE_ID>` for roles. + `requireMention` is configured per guild/channel (`channels.discord.guilds...`). `ignoreOtherMentions` optionally drops messages that mention another user/role but not the bot (excluding @everyone/@here). diff --git a/extensions/discord/src/channel.test.ts b/extensions/discord/src/channel.test.ts index 60563c66e26..33c0c77f54e 100644 --- a/extensions/discord/src/channel.test.ts +++ b/extensions/discord/src/channel.test.ts @@ -119,6 +119,14 @@ describe("discordPlugin outbound", () => { expect(discordPlugin.outbound?.preferFinalAssistantVisibleText).toBe(true); }); + it("adds Discord mention formatting to agent prompt hints", () => { + const hints = discordPlugin.agentPrompt?.messageToolHints?.({} as never) ?? []; + + expect(hints).toContain( + "- Discord mentions: link users with `<@USER_ID>` only. Do not use the legacy `<@!USER_ID>` nickname form. Link channels as `<#CHANNEL_ID>` and roles as `<@&ROLE_ID>`.", + ); + }); + it("preserves normalized explicit Discord targets for delivery routing", () => { const parseExplicitTarget = discordPlugin.messaging?.parseExplicitTarget; if (!parseExplicitTarget) { diff --git a/extensions/discord/src/channel.ts b/extensions/discord/src/channel.ts index 4a373828c55..466bc5fb626 100644 --- a/extensions/discord/src/channel.ts +++ b/extensions/discord/src/channel.ts @@ -213,6 +213,7 @@ export const discordPlugin: ChannelPlugin }, agentPrompt: { messageToolHints: () => [ + "- Discord mentions: link users with `<@USER_ID>` only. Do not use the legacy `<@!USER_ID>` nickname form. Link channels as `<#CHANNEL_ID>` and roles as `<@&ROLE_ID>`.", "- Discord components: set `components` when sending messages to include buttons, selects, or v2 containers.", "- Forms: add `components.modal` (title, fields). OpenClaw adds a trigger button and routes submissions as new messages.", ],