Discord

OpenClaw se connecte à Discord en tant que bot via le Gateway officiel de Discord. Les messages privés et les canaux de serveur sont pris en charge.

Configuration rapide

Créez une application Discord avec un bot, ajoutez le bot à votre serveur et associez-le à OpenClaw. Utilisez si possible un serveur privé ; commencez par en créer un (Create My Own > For me and my friends) si nécessaire.

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

Recommandation : configurer un espace de travail de serveur

Une fois les messages privés fonctionnels, vous pouvez transformer votre serveur en un espace de travail complet dans lequel chaque canal dispose de sa propre session d’agent et de son propre contexte. Cette configuration est recommandée pour les serveurs privés où il n’y a que vous et votre bot.

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

Créez maintenant des canaux et commencez à discuter. L’agent voit le nom du canal, et chaque canal constitue une session isolée : configurez #coding, #home, #research ou tout autre canal adapté à votre flux de travail.

Modèle d’exécution

• Le Gateway gère la connexion à Discord.
• Le routage des réponses est déterministe : les réponses aux messages entrants de Discord sont renvoyées à Discord.
• Les métadonnées de serveur/canal Discord sont ajoutées au prompt du modèle en tant que contexte non fiable, et non comme préfixe de réponse visible par l’utilisateur. Si un modèle recopie cette enveloppe dans sa réponse, OpenClaw supprime les métadonnées copiées des réponses sortantes et du contexte des relectures ultérieures.
• Par défaut (session.dmScope=main), les discussions directes partagent la session principale de l’agent (agent:main:main).
• Les canaux de serveur utilisent des clés de session isolées (agent:<agentId>:discord:channel:<channelId>).
• Les messages privés de groupe sont ignorés par défaut (channels.discord.dm.groupEnabled=false).
• Les commandes slash natives s’exécutent dans des sessions de commande isolées (agent:<agentId>:discord:slash:<userId>), tout en transmettant CommandTargetSessionKey à la session de conversation routée.
• La diffusion sur Discord des annonces Cron/Heartbeat uniquement textuelles est réduite à la réponse finale visible de l’assistant, envoyée une seule fois. Les contenus multimédias et les charges utiles de composants structurés restent répartis sur plusieurs messages lorsque l’agent produit plusieurs charges utiles à transmettre.

Canaux de forum

Les canaux de forum et multimédias Discord acceptent uniquement les publications dans des fils de discussion. OpenClaw permet de les créer de deux manières :

• Envoyez un message au parent du forum (channel:<forumId>) pour créer automatiquement un fil. Le titre du fil correspond à la première ligne non vide du message (tronquée à la limite de 100 caractères imposée par Discord pour le nom des fils).
• Utilisez openclaw message thread create pour créer directement un fil. Ne transmettez pas --message-id pour les canaux de forum.

Envoyez un message au parent du forum pour créer un fil :

openclaw message send --channel discord --target channel:<forumId> \  --message "Titre du sujet\nCorps de la publication"

Créez explicitement un fil de forum :

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Titre du sujet" --message "Corps de la publication"

Les parents de forum n'acceptent pas les composants Discord. Si vous avez besoin de composants, envoyez-les au fil lui-même (channel:<threadId>).

Composants interactifs

OpenClaw prend en charge les conteneurs de composants v2 de Discord pour les messages des agents. Utilisez l'outil de messagerie avec une charge utile components. Les résultats des interactions sont renvoyés à l'agent comme des messages entrants normaux et respectent les paramètres Discord replyToMode existants.

Blocs pris en charge :

• text, section, separator, actions, media-gallery, file
• Les lignes d'actions autorisent jusqu'à 5 boutons ou un seul menu de sélection
• Types de sélection : string, user, role, mentionable, channel

Par défaut, les composants sont à usage unique. Définissez components.reusable=true pour permettre l'utilisation répétée des boutons, sélections et formulaires jusqu'à leur expiration.

Pour limiter les utilisateurs autorisés à cliquer sur un bouton, définissez allowedUsers sur ce bouton (identifiants d'utilisateur Discord, tags ou *). Les utilisateurs non correspondants reçoivent un refus éphémère.

Les rappels de composants expirent après 30 minutes par défaut. Définissez channels.discord.agentComponents.ttlMs pour modifier la durée de vie du registre de rappels du compte par défaut, ou channels.discord.accounts.<accountId>.agentComponents.ttlMs pour chaque compte. La valeur est exprimée en millisecondes, doit être un entier positif et est plafonnée à 86400000 (24 heures). Des durées de vie plus longues conviennent aux processus de révision ou d'approbation qui nécessitent que les boutons restent utilisables, mais elles prolongent la période pendant laquelle un ancien message Discord peut encore déclencher une action. Privilégiez la durée de vie la plus courte qui convienne et conservez la valeur par défaut si des rappels obsolètes seraient inattendus.

Les commandes slash /model et /models ouvrent un sélecteur de modèle interactif comprenant des listes déroulantes pour le fournisseur, le modèle et le runtime compatible, ainsi qu'une étape Submit. /models add est obsolète et renvoie un message d'obsolescence au lieu d'enregistrer des modèles depuis la discussion. La réponse du sélecteur est éphémère et utilisable uniquement par l'utilisateur qui l'a invoqué. Les menus de sélection Discord sont limités à 25 options ; ajoutez donc des entrées provider/* à agents.defaults.models lorsque vous souhaitez que le sélecteur affiche les modèles découverts dynamiquement uniquement pour certains fournisseurs, tels que openai ou vllm.

Pièces jointes :

• Les blocs file doivent pointer vers une référence de pièce jointe (attachment://<filename>)
• Fournissez la pièce jointe via media/path/filePath (un seul fichier) ; utilisez media-gallery pour plusieurs fichiers
• Utilisez filename pour remplacer le nom du fichier téléversé lorsqu'il doit correspondre à la référence de pièce jointe

Formulaires modaux :

• Ajoutez components.modal avec jusqu'à 5 champs
• Types de champs : text, checkbox, radio, select, role-select, user-select
• OpenClaw ajoute automatiquement un bouton de déclenchement

Exemple :

{  channel: "discord",  action: "send",  to: "channel:123456789012345678",  message: "Texte de secours facultatif",  components: {    reusable: true,    text: "Choisissez une voie",    blocks: [      {        type: "actions",        buttons: [          {            label: "Approuver",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Refuser", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Choisissez une option",          options: [            { label: "Option A", value: "a" },            { label: "Option B", value: "b" },          ],        },      },    ],    modal: {      title: "Détails",      triggerLabel: "Ouvrir le formulaire",      fields: [        { type: "text", label: "Demandeur" },        {          type: "select",          label: "Priorité",          options: [            { label: "Faible", value: "low" },            { label: "Élevée", value: "high" },          ],        },      ],    },  },}

Contrôle d'accès et routage

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{channels: {discord: {  groupPolicy: "allowlist",  guilds: {    "123456789012345678": {      requireMention: true,      ignoreOtherMentions: true,      users: ["987654321098765432"],      roles: ["123456789012345678"],      channels: {        general: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

Routage des agents fondé sur les rôles

Utilisez bindings[].match.roles pour acheminer les membres d'un serveur Discord vers différents agents selon leur identifiant de rôle. Les liaisons fondées sur les rôles acceptent uniquement des identifiants de rôles et sont évaluées après les liaisons par pair ou pair parent, mais avant les liaisons limitées au serveur. Si une liaison définit également d'autres champs de correspondance (par exemple peer + guildId + roles), tous les champs configurés doivent correspondre.

{  bindings: [    {      agentId: "opus",      match: {        channel: "discord",        guildId: "123456789012345678",        roles: ["111111111111111111"],      },    },    {      agentId: "sonnet",      match: {        channel: "discord",        guildId: "123456789012345678",      },    },  ],}

Commandes natives et autorisation des commandes

• commands.native utilise par défaut "auto" et est activé pour Discord.
• Remplacement par canal : channels.discord.commands.native.
• commands.native=false ignore l’enregistrement et le nettoyage des commandes slash Discord au démarrage. Les commandes précédemment enregistrées peuvent rester visibles dans Discord jusqu’à ce que vous les supprimiez de l’application Discord.
• L’authentification des commandes natives utilise les mêmes listes d’autorisation et stratégies Discord que le traitement normal des messages.
• Les commandes peuvent rester visibles dans l’interface de Discord pour les utilisateurs non autorisés ; leur exécution applique l’authentification OpenClaw et répond « non autorisé ».
• Paramètres par défaut des commandes slash : ephemeral: true (channels.discord.slashCommand.ephemeral).

Consultez Commandes slash pour connaître le catalogue et le comportement des commandes.

Détails des fonctionnalités

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      maxLineChars: 120,      toolProgress: true,      commentary: false,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,},},channels: {discord: {  threadBindings: {    enabled: true,    idleHours: 24,    maxAgeHours: 0,    spawnSessions: true,    defaultSpawnContext: "fork",  },},},}

{agents: {list: [  {    id: "codex",    runtime: {      type: "acp",      acp: {        agent: "codex",        backend: "acpx",        mode: "persistent",        cwd: "/workspace/openclaw",      },    },  },],},bindings: [{  type: "acp",  agentId: "codex",  match: {    channel: "discord",    accountId: "default",    peer: { kind: "channel", id: "222222222222222222" },  },  acp: { label: "codex-main" },},],channels: {discord: {  guilds: {    "111111111111111111": {      channels: {        "222222222222222222": {          requireMention: false,        },      },    },  },},},}

{channels: {discord: {  configWrites: false,},},}

{channels: {discord: {  proxy: "http://proxy.example:8080",},},}

{channels: {discord: {  accounts: {    primary: {      proxy: "http://proxy.example:8080",    },  },},},}

{channels: {discord: {  pluralkit: {    enabled: true,    token: "pk_live_...", // facultatif ; nécessaire pour les systèmes privés  },},},}

{channels: {discord: {  mentionAliases: {    SupportLead: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{channels: {discord: {  status: "idle",},},}

{channels: {discord: {  activity: "Temps de concentration",  activityType: 4,},},}

{channels: {discord: {  activity: "Programmation en direct",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "jeton épuisé",  },},},}

Outils et mécanismes d’autorisation des actions

Les actions de message Discord couvrent la messagerie, l’administration des canaux, la modération, la présence et les métadonnées.

Exemples principaux :

• messagerie : sendMessage, readMessages, editMessage, deleteMessage, threadReply
• réactions : react, reactions, emojiList
• modération : timeout, kick, ban
• présence : setPresence

L’action event-create accepte un paramètre image facultatif (URL ou chemin de fichier local) pour définir l’image de couverture de l’événement planifié.

Les mécanismes d’autorisation des actions se trouvent sous channels.discord.actions.*.

Comportement par défaut des mécanismes d’autorisation :

Interface utilisateur Components v2

OpenClaw utilise les composants Discord v2 pour les approbations d’exécution et les marqueurs intercontextes. Les actions de message Discord peuvent également accepter components pour une interface utilisateur personnalisée (avancé ; nécessite la construction d’une charge utile de composant via l’outil Discord), tandis que les anciens embeds restent disponibles, mais ne sont pas recommandés.

• channels.discord.ui.components.accentColor définit la couleur d’accentuation utilisée par les conteneurs de composants Discord (hexadécimale). Par compte : channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs contrôle la durée pendant laquelle les rappels des composants Discord envoyés restent enregistrés (valeur par défaut 1800000, maximum 86400000). Par compte : channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds est ignoré lorsque des composants v2 sont présents.
• Les aperçus d’URL simples sont supprimés par défaut. Définissez suppressEmbeds: false sur une action de message lorsqu’un seul lien sortant doit être développé.

Exemple :

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

Voix

Discord possède deux surfaces vocales distinctes : les canaux vocaux en temps réel (conversations continues) et les pièces jointes de messages vocaux (format d’aperçu de la forme d’onde). Le Gateway prend en charge les deux.

Canaux vocaux

Liste de vérification de la configuration :

1. Activez Message Content Intent dans Discord Developer Portal.
2. Activez Server Members Intent lorsque des listes d’autorisation de rôles ou d’utilisateurs sont utilisées.
3. Invitez le bot avec les portées bot et applications.commands.
4. Accordez Connect, Speak, Send Messages et Read Message History dans le canal vocal cible.
5. Activez les commandes natives (commands.native ou channels.discord.commands.native).
6. Configurez channels.discord.voice.

Utilisez /vc join|leave|status pour contrôler les sessions. La commande utilise l’agent par défaut du compte et suit les mêmes règles de liste d’autorisation et de politique de groupe que les autres commandes Discord.

/vc join channel:<voice-channel-id>/vc status/vc leave

Pour inspecter les autorisations effectives du bot avant de rejoindre le canal :

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

Exemple de connexion automatique :

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

Remarques :

• La voix Discord est optionnelle pour les configurations uniquement textuelles ; définissez channels.discord.voice.enabled=true (ou conservez un bloc channels.discord.voice existant) pour activer les commandes /vc, l’environnement d’exécution vocal et l’intention Gateway GuildVoiceStates. channels.discord.intents.voiceStates permet de remplacer explicitement l’abonnement à l’intention ; laissez cette option non définie pour suivre l’activation effective de la voix.
• voice.mode contrôle le chemin de conversation. La valeur par défaut est agent-proxy : une interface vocale en temps réel gère le minutage des tours, les interruptions et la lecture, délègue le travail de fond à l’agent OpenClaw acheminé via openclaw_agent_consult et traite le résultat comme une invite Discord saisie par cet interlocuteur. stt-tts conserve l’ancien flux STT par lots suivi de TTS. bidi permet au modèle en temps réel de converser directement tout en exposant openclaw_agent_consult pour le cerveau OpenClaw.
• voice.agentSession détermine quelle conversation OpenClaw reçoit les tours vocaux. Laissez cette option non définie pour utiliser la propre session du canal vocal, ou définissez { mode: "target", target: "channel:<text-channel-id>" } afin que le canal vocal serve d’extension microphone/haut-parleur à la session d’un canal textuel Discord existant, tel que #maintainers.
• voice.model remplace le cerveau de l’agent OpenClaw pour les réponses vocales Discord et les consultations en temps réel. Laissez cette option non définie pour hériter du modèle de l’agent acheminé. Elle est distincte de voice.realtime.model.
• voice.followUsers permet au bot de rejoindre, de suivre et de quitter les canaux vocaux Discord avec les utilisateurs sélectionnés. Consultez Suivre des utilisateurs dans les canaux vocaux.
• agent-proxy achemine la parole via discord-voice, qui préserve les autorisations normales du propriétaire et des outils pour l’interlocuteur et la session cible, mais masque l’outil tts de l’agent, car la voix Discord prend en charge la lecture. Par défaut, agent-proxy accorde à la consultation un accès aux outils entièrement équivalent à celui du propriétaire pour les interlocuteurs propriétaires (voice.realtime.toolPolicy: "owner") et privilégie fortement la consultation de l’agent OpenClaw avant les réponses de fond (voice.realtime.consultPolicy: "always"). Dans ce mode always par défaut, la couche en temps réel ne prononce pas automatiquement de phrases d’attente avant la réponse de la consultation ; elle capture et transcrit la parole, puis énonce la réponse OpenClaw acheminée. Si plusieurs réponses de consultation forcée se terminent alors que Discord lit encore la première réponse, les réponses ultérieures à prononcer exactement sont mises en file d’attente jusqu’à ce que la lecture soit inactive, au lieu de remplacer la parole en milieu de phrase.
• En mode stt-tts, la STT utilise tools.media.audio ; voice.model n’affecte pas la transcription.
• Dans les modes en temps réel, voice.realtime.provider, voice.realtime.model et voice.realtime.speakerVoice configurent la session audio en temps réel. Pour OpenAI Realtime 2.1 avec le cerveau Codex, utilisez voice.realtime.model: "gpt-realtime-2.1" et voice.model: "openai/gpt-5.6-sol".
• Par défaut, les modes vocaux en temps réel incluent les petits fichiers de profil IDENTITY.md, USER.md et SOUL.md dans les instructions du fournisseur en temps réel, afin que les tours directs rapides conservent la même identité, le même ancrage utilisateur et la même personnalité que l’agent OpenClaw acheminé. Définissez voice.realtime.bootstrapContextFiles sur un sous-ensemble pour personnaliser ce comportement, ou sur [] pour le désactiver. Seuls ces fichiers de profil sont pris en charge ; AGENTS.md reste dans le contexte normal de l’agent. Le contexte de profil injecté ne remplace pas openclaw_agent_consult pour le travail dans l’espace de travail, les faits actuels, la recherche en mémoire ou les actions reposant sur des outils.
• Dans le mode en temps réel OpenAI agent-proxy, définissez voice.realtime.requireWakeName: true pour que la voix Discord en temps réel reste silencieuse jusqu’à ce qu’une transcription commence ou se termine par un nom d’activation. Les noms d’activation configurés doivent comporter un ou deux mots. Si voice.realtime.wakeNames n’est pas défini, OpenClaw utilise le name de l’agent acheminé ainsi que OpenClaw, avec comme solution de repli l’identifiant de l’agent ainsi que OpenClaw. Le filtrage par nom d’activation désactive la réponse automatique du fournisseur en temps réel, achemine les tours acceptés par le chemin de consultation de l’agent OpenClaw et fournit un bref accusé de réception vocal lorsqu’un nom d’activation initial est reconnu à partir d’une transcription partielle avant l’arrivée de la transcription finale.
• Le fournisseur OpenAI en temps réel accepte les noms d’événements Realtime 2 actuels et les anciens alias compatibles avec Codex pour les événements de sortie audio et de transcription, afin que les instantanés de fournisseurs compatibles puissent diverger sans entraîner la perte de l’audio de l’assistant.
• voice.realtime.bargeIn détermine si les événements de début de parole Discord interrompent la lecture en temps réel active. Si cette option n’est pas définie, elle suit le paramètre d’interruption par l’audio d’entrée du fournisseur en temps réel.
• voice.realtime.minBargeInAudioEndMs contrôle la durée minimale de lecture de l’assistant avant qu’une interruption OpenAI en temps réel ne tronque l’audio. Valeur par défaut : 250. Définissez 0 pour une interruption immédiate dans les pièces à faible écho, ou augmentez cette valeur pour les configurations de haut-parleurs générant beaucoup d’écho.
• voice.tts remplace messages.tts uniquement pour la lecture vocale en mode stt-tts ; les modes en temps réel utilisent plutôt voice.realtime.speakerVoice. Pour utiliser une voix OpenAI lors de la lecture sur Discord, définissez voice.tts.provider: "openai" et choisissez une voix de synthèse vocale sous voice.tts.providers.openai.speakerVoice. cedar constitue un bon choix à sonorité masculine avec le modèle TTS OpenAI actuel.
• Les remplacements de systemPrompt Discord propres à chaque canal s’appliquent aux tours de transcription vocale de ce canal vocal.
• Les tours de transcription vocale déterminent le statut de propriétaire à partir de allowFrom (ou dm.allowFrom) de Discord pour les commandes et les actions de canal réservées au propriétaire. La visibilité des outils de l’agent suit la politique d’outils configurée pour la session acheminée.
• Si voice.autoJoin contient plusieurs entrées pour une même guilde, OpenClaw rejoint le dernier canal configuré pour cette guilde.
• voice.allowedChannels est une liste d’autorisation de résidence facultative. Laissez cette option non définie pour autoriser /vc join à rejoindre n’importe quel canal vocal Discord autorisé. Lorsqu’elle est définie, /vc join, la connexion automatique au démarrage et les déplacements de l’état vocal du bot sont limités aux entrées { guildId, channelId } répertoriées. Définissez-la sur un tableau vide pour refuser toutes les connexions aux canaux vocaux Discord. Si Discord déplace le bot hors de la liste d’autorisation, OpenClaw quitte ce canal et rejoint la cible de connexion automatique configurée lorsqu’elle est disponible.
• voice.daveEncryption et voice.decryptionFailureTolerance sont transmis aux options de connexion de @discordjs/voice ; les valeurs par défaut du projet en amont sont daveEncryption=true et decryptionFailureTolerance=24.
• OpenClaw utilise le codec libopus-wasm intégré pour la réception vocale Discord et la lecture PCM brute en temps réel. Il fournit une version WebAssembly épinglée de libopus et ne nécessite aucun module complémentaire opus natif.
• voice.connectTimeoutMs contrôle le délai d’attente initial de l’état Ready de @discordjs/voice pour /vc join et les tentatives de connexion automatique. Valeur par défaut : 30000.
• voice.reconnectGraceMs contrôle la durée pendant laquelle OpenClaw attend qu’une session vocale déconnectée commence à se reconnecter avant de la détruire. Valeur par défaut : 15000.
• En mode stt-tts, la lecture vocale ne s’arrête pas simplement parce qu’un autre utilisateur commence à parler. Pour éviter les boucles de rétroaction, OpenClaw ignore toute nouvelle capture vocale pendant la lecture TTS ; parlez une fois la lecture terminée pour passer au tour suivant. Les modes en temps réel transmettent les débuts de parole comme signaux d’interruption au fournisseur en temps réel.
• Dans les modes en temps réel, l’écho des haut-parleurs capté par un microphone ouvert peut être interprété comme une interruption et interrompre la lecture. Pour les salons Discord générant beaucoup d’écho, définissez voice.realtime.providers.openai.interruptResponseOnInputAudio: false afin d’empêcher OpenAI d’interrompre automatiquement la réponse à la réception d’audio d’entrée. Ajoutez voice.realtime.bargeIn: true si vous souhaitez néanmoins que les événements de début de parole Discord interrompent la lecture active. Le pont OpenAI en temps réel ignore les troncatures de lecture plus courtes que voice.realtime.minBargeInAudioEndMs, considérées comme un écho ou un bruit probable, et les consigne comme ignorées au lieu d’effacer la lecture Discord.
• voice.captureSilenceGraceMs contrôle la durée pendant laquelle OpenClaw attend, après que Discord a signalé l’arrêt d’un interlocuteur, avant de finaliser ce segment audio pour la STT. Valeur par défaut : 2000 ; augmentez-la si Discord découpe les pauses normales en transcriptions partielles saccadées.
• Lorsque ElevenLabs est le fournisseur TTS sélectionné, la lecture vocale Discord utilise la TTS en flux continu et démarre à partir du flux de réponse du fournisseur. Les fournisseurs sans prise en charge du flux continu utilisent à la place le chemin fondé sur un fichier temporaire synthétisé.
• OpenClaw surveille les échecs de déchiffrement à la réception et effectue une récupération automatique en quittant puis en rejoignant le canal vocal après plusieurs échecs sur une courte période.
• Si les journaux de réception affichent de manière répétée DecryptionFailed(UnencryptedWhenPassthroughDisabled) après une mise à jour, recueillez un rapport de dépendances et les journaux. La version intégrée de @discordjs/voice inclut le correctif de remplissage en amont issu de la PR discord.js #11449, qui a résolu le ticket discord.js #11419.
• Les événements de réception The operation was aborted sont attendus lorsqu’OpenClaw finalise un segment d’interlocuteur capturé ; il s’agit de diagnostics détaillés, et non d’avertissements.
• Les journaux détaillés de la voix Discord incluent un aperçu limité à une ligne de la transcription STT pour chaque segment d’interlocuteur accepté, afin que le débogage affiche à la fois le côté utilisateur et le côté réponse de l’agent sans produire un volume illimité de texte de transcription.
• En mode agent-proxy, la solution de repli de consultation forcée ignore les fragments de transcription probablement incomplets, tels que le texte se terminant par ... ou par un connecteur final comme « et », ainsi que les formules de clôture manifestement non exploitables comme « je reviens tout de suite » ou « au revoir ». Les journaux affichent forced agent consult skipped reason=... lorsque cela empêche une réponse obsolète mise en file d’attente.

Suivre des utilisateurs dans les canaux vocaux

Utilisez voice.followUsers lorsque vous souhaitez que le bot vocal Discord reste avec un ou plusieurs utilisateurs Discord connus, au lieu de rejoindre un canal fixe au démarrage ou d’attendre /vc join.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

Comportement :

• followUsers accepte les identifiants utilisateur Discord bruts et les valeurs discord:<id>. OpenClaw normalise les deux formes avant de les faire correspondre aux événements d’état vocal.
• followUsersEnabled prend la valeur true par défaut lorsque followUsers est configuré. Définissez-la sur false pour conserver la liste enregistrée tout en interrompant le suivi vocal automatique.
• Lorsqu’un utilisateur suivi rejoint un canal vocal autorisé, OpenClaw rejoint ce canal. Lorsque l’utilisateur change de canal, OpenClaw le suit. Lorsque l’utilisateur suivi actif se déconnecte, OpenClaw quitte le canal.
• Si plusieurs utilisateurs suivis se trouvent dans la même guilde et que l’utilisateur suivi actif la quitte, OpenClaw rejoint le canal d’un autre utilisateur suivi avant de quitter la guilde. Si plusieurs utilisateurs suivis changent de canal simultanément, le dernier événement d’état vocal observé prévaut.
• allowedChannels continue de s’appliquer. Un utilisateur suivi dans un canal non autorisé est ignoré, et une session appartenant au suivi rejoint un autre utilisateur suivi ou quitte le canal.
• OpenClaw réconcilie les événements d’état vocal manqués au démarrage et à intervalles limités. La réconciliation échantillonne les guildes configurées et limite les recherches REST par exécution ; les très grandes listes followUsers peuvent donc nécessiter plus d’un intervalle pour converger.
• Si Discord ou un administrateur déplace le bot alors qu’il suit un utilisateur, OpenClaw reconstruit la session vocale et préserve la propriété du suivi lorsque la destination est autorisée. Si le bot est déplacé hors de allowedChannels, OpenClaw quitte le canal et rejoint la cible configurée lorsqu’elle existe.
• La récupération de réception DAVE peut quitter puis rejoindre le même canal après plusieurs échecs de déchiffrement. Les sessions appartenant au suivi conservent cette propriété pendant ce chemin de récupération, de sorte que la déconnexion ultérieure d’un utilisateur suivi entraîne toujours la sortie du canal.

Choisissez parmi les modes de connexion :

• Utilisez followUsers pour les configurations personnelles ou d’opérateur dans lesquelles le bot doit automatiquement être présent dans un canal vocal lorsque vous y êtes.
• Utilisez autoJoin pour les bots de salons fixes qui doivent être présents même lorsqu’aucun utilisateur suivi ne se trouve dans un canal vocal.
• Utilisez /vc join pour les connexions ponctuelles ou les salons dans lesquels une présence vocale automatique serait inattendue.

Codec vocal Discord :

• Les journaux de réception vocale affichent discord voice: opus decoder: libopus-wasm.
• La lecture en temps réel encode le PCM stéréo brut à 48 kHz en Opus avec le même paquet libopus-wasm intégré avant de transmettre les paquets à @discordjs/voice.
• La lecture de fichiers et de flux de fournisseurs transcode les données en PCM stéréo brut à 48 kHz avec ffmpeg, puis utilise libopus-wasm pour le flux de paquets Opus envoyé à Discord.

Pipeline STT suivi de TTS :

• La capture PCM de Discord est convertie en fichier WAV temporaire.
• tools.media.audio gère la reconnaissance vocale (STT), par exemple openai/gpt-4o-mini-transcribe.
• La transcription est transmise via l’entrée et le routage Discord tandis que le LLM de réponse s’exécute avec une politique de sortie vocale qui masque l’outil tts de l’agent et demande le renvoi de texte, car le canal vocal Discord prend en charge la lecture TTS finale.
• voice.model, lorsqu’il est défini, remplace uniquement le LLM de réponse pour cette interaction sur le canal vocal.
• voice.tts est fusionné par-dessus messages.tts ; les fournisseurs capables de diffuser en continu alimentent directement le lecteur, sinon le fichier audio obtenu est lu dans le canal rejoint.

Exemple de session de canal vocal avec proxy d’agent par défaut :

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

En l’absence de bloc voice.agentSession, chaque canal vocal dispose de sa propre session OpenClaw routée. Par exemple, /vc join channel:234567890123456789 communique avec la session de ce canal vocal Discord. Le modèle temps réel constitue uniquement l’interface vocale ; les demandes substantielles sont transmises à l’agent OpenClaw configuré. Si le modèle temps réel produit une transcription finale sans appeler l’outil de consultation, OpenClaw force la consultation en solution de repli afin que le comportement par défaut reste équivalent à une conversation avec l’agent.

Exemple hérité de STT avec TTS :

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

Exemple bidirectionnel en temps réel :

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Voix comme extension d’une session de canal Discord existante :

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.6-sol",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

En mode agent-proxy, le bot rejoint le canal vocal configuré, mais les interactions de l’agent OpenClaw utilisent la session routée et l’agent habituels du canal cible. La session vocale en temps réel restitue oralement le résultat renvoyé dans le canal vocal. L’agent superviseur peut toujours utiliser les outils de messagerie habituels conformément à sa politique d’outils, notamment envoyer un message Discord séparé si cette action est appropriée.

Pendant l’exécution d’une tâche OpenClaw déléguée, les nouvelles transcriptions vocales Discord sont traitées comme des commandes de contrôle de l’exécution en cours avant de démarrer une autre interaction de l’agent. Les phrases telles que « état », « annule cela », « utilise le correctif le plus petit » ou « lorsque tu as terminé, vérifie également les tests » sont classées comme une demande d’état, une annulation, une instruction d’orientation ou une demande de suivi pour la session active. Les résultats des demandes d’état, des annulations, des instructions d’orientation acceptées et des suivis sont restitués oralement dans le canal vocal afin que l’appelant sache si OpenClaw a traité la demande.

Formes de cible utiles :

• target: "channel:123456789012345678" effectue le routage via une session de canal textuel Discord.
• target: "123456789012345678" est traité comme une cible de canal.
• target: "dm:123456789012345678" ou target: "user:123456789012345678" effectue le routage via cette session de message direct.

Exemple OpenAI Realtime dans un environnement générant beaucoup d’écho :

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Utilisez cette configuration lorsque le modèle entend sa propre lecture Discord via un microphone ouvert, mais que vous souhaitez toujours pouvoir l’interrompre en parlant. OpenClaw empêche OpenAI d’interrompre automatiquement la réponse en cas d’audio d’entrée brut, tandis que bargeIn: true permet aux événements de début de prise de parole de Discord et à l’audio d’un locuteur déjà actif d’annuler les réponses en temps réel actives avant que la prochaine intervention capturée n’atteigne OpenAI. Les signaux d’interruption très précoces dont la valeur audioEndMs est inférieure à minBargeInAudioEndMs sont considérés comme de l’écho ou du bruit probable et ignorés afin que le modèle ne s’interrompe pas dès la première trame de lecture.

Journaux vocaux attendus :

• Lors de la connexion : discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Au démarrage du temps réel : discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Lors de l’audio du locuteur : discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... et discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Lorsqu’une parole obsolète est ignorée : discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... ou reason=non-actionable-closing ...
• À la fin de la réponse en temps réel : discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Lors de l’arrêt ou de la réinitialisation de la lecture : discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Lors d’une consultation en temps réel : discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Lors de la réponse de l’agent : discord voice: agent turn answer ...
• Lorsqu’une parole exacte est mise en file d’attente : discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., suivi de discord voice: realtime exact speech dequeued reason=player-idle ...
• Lors de la détection d’une interruption : discord voice: realtime barge-in detected source=speaker-start ... ou discord voice: realtime barge-in detected source=active-speaker-audio ..., suivi de discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Lors d’une interruption en temps réel : discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, suivi soit de discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=..., soit de discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Lorsqu’un écho ou un bruit est ignoré : discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Lorsque l’interruption est désactivée : discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Lorsque la lecture est inactive : discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Pour diagnostiquer un son interrompu, lisez les journaux vocaux en temps réel comme une chronologie :

1. realtime audio playback started signifie que Discord a commencé à lire l’audio de l’assistant. À partir de cet instant, la passerelle commence à compter les fragments de sortie de l’assistant, les octets PCM Discord, les octets temps réel du fournisseur et la durée de l’audio synthétisé.
2. realtime speaker turn opened signale qu’un locuteur Discord devient actif. Si la lecture est déjà active et que bargeIn est activé, ce message peut être suivi de barge-in detected source=speaker-start.
3. realtime input audio started signale la première trame audio réellement reçue pour cette intervention du locuteur. Une valeur outputActive=true ou une valeur outputAudioMs non nulle à cet endroit signifie que le microphone envoie une entrée alors que la lecture de l’assistant est encore active.
4. barge-in detected source=active-speaker-audio signifie qu’OpenClaw a détecté l’audio en direct d’un locuteur pendant que la lecture de l’assistant était active. Cela permet de distinguer une véritable interruption d’un événement de début de prise de parole Discord dépourvu d’audio utile.
5. barge-in requested reason=... signifie qu’OpenClaw a demandé au fournisseur temps réel d’annuler ou de tronquer la réponse active. Le message inclut outputAudioMs, outputActive et playbackChunks afin que vous puissiez voir la quantité d’audio de l’assistant qui avait réellement été lue avant l’interruption.
6. realtime audio playback stopped reason=... est le point de réinitialisation de la lecture Discord locale. La raison indique l’origine de l’arrêt de la lecture : barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close ou session-close.
7. realtime speaker turn closed résume l’intervention d’entrée capturée. chunks=0 ou hasAudio=false signifie que l’intervention du locuteur a commencé, mais qu’aucun audio exploitable n’a atteint la passerelle temps réel. interruptedPlayback=true signifie que cette intervention d’entrée a chevauché la sortie de l’assistant et déclenché la logique d’interruption.

Champs utiles :

• outputAudioMs : durée de l’audio de l’assistant généré par le fournisseur temps réel avant cette ligne de journal.
• audioMs : durée de l’audio de l’assistant comptabilisée par OpenClaw avant l’arrêt de la lecture.
• elapsedMs : temps réel écoulé entre l’ouverture et la fermeture du flux de lecture ou de l’intervention du locuteur.
• discordBytes : octets PCM stéréo à 48 kHz envoyés à la voix Discord ou reçus depuis celle-ci.
• realtimeBytes : octets PCM au format du fournisseur envoyés au fournisseur temps réel ou reçus depuis celui-ci.
• playbackChunks : fragments audio de l’assistant transmis à Discord pour la réponse active.
• sinceLastAudioMs : intervalle entre la dernière trame audio capturée du locuteur et la fermeture de son intervention.

Schémas courants :

• Une interruption immédiate avec source=active-speaker-audio, une faible valeur outputAudioMs et le même utilisateur à proximité indique généralement que l’écho des haut-parleurs entre dans le microphone. Augmentez voice.realtime.minBargeInAudioEndMs, réduisez le volume des haut-parleurs, utilisez un casque ou définissez voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start suivi de speaker turn closed ... hasAudio=false signifie que Discord a signalé le début de la prise de parole d’un locuteur, mais qu’aucun audio n’a atteint OpenClaw. Il peut s’agir d’un événement vocal Discord transitoire, du comportement de la porte de bruit ou de l’activation très brève du microphone par un client.
• audio playback stopped reason=stream-close sans interruption proche ni provider-clear-audio signifie que le flux de lecture Discord local s’est terminé de manière inattendue. Vérifiez les journaux précédents du fournisseur et du lecteur Discord.
• capture ignored during playback (barge-in disabled) signifie qu’OpenClaw a intentionnellement ignoré l’entrée pendant que l’audio de l’assistant était actif. Activez voice.realtime.bargeIn si vous souhaitez que la parole interrompe la lecture.
• barge-in ignored ... outputActive=false signifie que Discord ou la détection d’activité vocale du fournisseur a signalé de la parole, mais qu’OpenClaw n’avait aucune lecture active à interrompre. Cela ne devrait pas interrompre l’audio.

Les identifiants sont résolus séparément pour chaque composant : authentification de la route LLM pour voice.model, authentification STT pour tools.media.audio, authentification TTS pour messages.tts/voice.tts et authentification du fournisseur temps réel pour voice.realtime.providers ou la configuration d’authentification habituelle du fournisseur.

Messages vocaux

Les messages vocaux Discord affichent un aperçu de la forme d’onde et nécessitent un audio OGG/Opus. OpenClaw génère automatiquement la forme d’onde, mais nécessite ffmpeg et ffprobe sur l’hôte du Gateway pour inspecter et convertir l’audio.

• Fournissez un chemin de fichier local (les URL sont rejetées).
• Omettez le contenu textuel (Discord refuse le texte et le message vocal dans la même charge utile).
• Tous les formats audio sont acceptés ; OpenClaw les convertit en OGG/Opus si nécessaire.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

Résolution des problèmes

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Remplacement facultatif à l’échelle de Discord. Les blocs de compte remplacent les  // champs individuels et héritent d’ici les champs omis.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha écoute les autres bots uniquement lorsqu’ils le mentionnent.      allowBots: "mentions",    },    bravo: {      // Bravo écoute tous les messages Discord rédigés par des bots.      allowBots: true,      mentionAliases: {        // Permet à Bravo d’écrire une mention Discord d’Alpha avec l’identifiant utilisateur configuré.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Autorise jusqu’à cinq messages par minute avant de bloquer la paire.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Référence de configuration

Référence principale : Référence de configuration — Discord.

Sécurité et exploitation

• Traitez les jetons de bot comme des secrets (DISCORD_BOT_TOKEN est recommandé dans les environnements supervisés).
• Accordez à Discord les autorisations minimales nécessaires.
• Si le déploiement ou l’état des commandes est obsolète, redémarrez le Gateway et vérifiez à nouveau avec openclaw channels status --probe.

Pages connexes