OpenClaw
Intégrations12 min de lecture

Intégration Discord OpenClaw : Configuration du bot et explication des Gateway Intents

Guide complet pour créer un bot Discord pour OpenClaw, comprendre les Gateway Intents, configurer les politiques de sécurité des DM et mettre en place le contrôle d'accès aux canaux de serveur.

O

OpenClaw Guides

Tutorial Authors

Aperçu

L'intégration Discord vous permet de discuter avec OpenClaw via un bot Discord, prenant en charge la communication par DM (messages directs) et par canaux textuels de serveur. Ce guide couvre la création d'un bot, la compréhension des Gateway Intents, la configuration des politiques de sécurité des DM et la mise en place du contrôle d'accès aux canaux de serveur — le tout basé sur la documentation officielle d'OpenClaw.

Prérequis

  • OpenClaw installé et en cours d'exécution
  • Un compte Discord
  • Un serveur Discord où vous avez les permissions d'administrateur (pour les tests)

Fonctionnement

Avant de commencer, il est utile de comprendre comment OpenClaw achemine les messages Discord :

  • Les conversations en DM sont regroupées dans une session partagée (agent:main:main) avec une sécurité basée sur l'appairage par défaut.
  • Les conversations dans les canaux de serveur sont isolées par canal, selon le schéma agent:<agentId>:discord:channel:<channelId>.
  • Les DM de groupe sont ignorés par défaut, mais peuvent être activés via channels.discord.dm.groupEnabled.

La passerelle démarre automatiquement lorsqu'un token valide existe et que enabled n'est pas défini sur false.

Étape 1 : Créer une application Discord

Accéder au portail développeur Discord

  1. Visitez le Portail développeur Discord
  2. Cliquez sur New Application
  3. Entrez un nom (par ex. « OpenClaw Assistant »)
  4. Cliquez sur Create

Configurer le bot

  1. Dans votre application, allez dans l'onglet Bot
  2. Cliquez sur Add Bot → Yes, do it!
  3. Sous Token, cliquez sur Copy pour copier votre token de bot

Important : Traitez votre token de bot comme un mot de passe. Ne le partagez jamais publiquement. S'il est exposé, régénérez-le immédiatement.

Étape 2 : Activer les Gateway Intents privilégiés

Les Gateway Intents contrôlent les événements que votre bot reçoit de Discord. OpenClaw nécessite des intents privilégiés spécifiques pour fonctionner correctement.

Intents requis

| Intent | Objectif | Requis | |--------|----------|--------| | Message Content Intent | Lire le texte des messages dans les canaux de serveur | Requis — sans cet intent, le bot affiche des erreurs « Used disallowed intents » ou se connecte mais ne répond pas | | Server Members Intent | Recherche de membres et correspondance avec les listes d'autorisation | Recommandé — nécessaire pour le contrôle d'accès basé sur les listes d'autorisation |

Activer les intents dans le portail développeur

  1. Allez dans l'onglet Bot du portail développeur
  2. Descendez jusqu'à Privileged Gateway Intents
  3. Activez MESSAGE CONTENT INTENT (obligatoire)
  4. Activez SERVER MEMBERS INTENT (recommandé)
  5. Cliquez sur Save Changes

Note : Les bots présents dans plus de 100 serveurs nécessitent une vérification Discord pour utiliser les intents privilégiés.

Étape 3 : Générer l'URL d'invitation du bot

Configurer OAuth2

  1. Allez dans OAuth2 → URL Generator

  2. Sélectionnez les scopes :

    • bot
    • applications.commands (requis pour les commandes slash natives)

  3. Sélectionnez les permissions du bot :

    • View Channels
    • Send Messages
    • Read Message History
    • Embed Links
    • Attach Files
    • Add Reactions (optionnel mais recommandé)
    • Use External Emojis (optionnel)

Attention : Évitez d'accorder la permission Administrator sauf si vous êtes en phase de débogage actif. N'accordez que le nécessaire.

  1. Copiez l'URL générée

Inviter le bot

  1. Ouvrez l'URL dans votre navigateur
  2. Sélectionnez votre serveur de test
  3. Cliquez sur Authorize

Obtenir les identifiants numériques

Activez le Mode développeur dans Discord (Paramètres utilisateur → Paramètres de l'application → Avancé → Mode développeur) afin de pouvoir faire un clic droit pour copier les identifiants de serveur, de canal et d'utilisateur — vous en aurez besoin pour la configuration.

Étape 4 : Configurer OpenClaw

Option A : Variable d'environnement

Définissez le token comme variable d'environnement :

bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

Option B : Fichier de configuration

Éditez votre fichier de configuration OpenClaw avec le token directement :

json5
{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"
    }
  }
}

Note : Lorsqu'une variable d'environnement et un token dans le fichier de configuration coexistent, le fichier de configuration est prioritaire.

Option C : Support multi-comptes

Pour exécuter plusieurs comptes de bot :

json5
{
  channels: {
    discord: {
      accounts: [
        { token: "BOT_TOKEN_1", name: "assistant-1" },
        { token: "BOT_TOKEN_2", name: "assistant-2" }
      ]
    }
  }
}

Étape 5 : Démarrer et tester

Démarrez ou redémarrez la passerelle OpenClaw :

bash
openclaw gateway restart

Vérifiez le statut des canaux :

bash
openclaw channels status --probe

Lancez un diagnostic si quelque chose semble ne pas fonctionner :

bash
openclaw doctor

Pour le premier contact en DM, le bot utilise un système d'appairage par défaut — l'expéditeur reçoit un code à durée limitée (expire au bout d'une heure) qui doit être approuvé avant que la conversation ne commence.

Politiques de sécurité des DM

OpenClaw propose trois politiques de contrôle d'accès pour les DM :

Appairage (par défaut)

Les expéditeurs inconnus reçoivent un code d'appairage à durée limitée qui expire après 1 heure. Le code doit être approuvé avant que la conversation puisse se poursuivre.

json5
{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "pairing"
      }
    }
  }
}

Liste d'autorisation

Seuls les identifiants ou noms d'utilisateur configurés peuvent envoyer des DM :

json5
{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: ["123456789012345678", "username#1234"]
      }
    }
  }
}

Ouvert

N'importe qui peut envoyer des DM (à utiliser avec prudence) :

json5
{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "open",
        allowFrom: ["*"]
      }
    }
  }
}

Configuration des canaux de serveur

Contrôle d'accès de base au serveur

Restreignez le bot à des serveurs et canaux spécifiques avec des exigences de mention :

json5
{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          requireMention: true,
          channels: {
            "CHANNEL_ID": {
              enabled: true
            }
          }
        }
      }
    }
  }
}

Important : requireMention doit être configuré au niveau du serveur ou du canal, pas au niveau supérieur de la configuration Discord.

Paramètres par canal

Vous pouvez configurer des listes d'autorisation et des restrictions de compétences par canal :

json5
{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_ID_1": {
              enabled: true,
              requireMention: true
            },
            "CHANNEL_ID_2": {
              enabled: true,
              requireMention: false
            }
          }
        }
      }
    }
  }
}

Paramètres de configuration

Paramètres des messages

| Paramètre | Par défaut | Description | |------------|------------|-------------| | textChunkLimit | 2000 | Nombre maximum de caractères par segment de message sortant | | chunkMode | — | Défini pour découper sur les lignes vides (limites de paragraphe) avant d'appliquer les limites de longueur | | maxLinesPerMessage | 17 | Nombre maximum de lignes par message | | mediaMaxMb | 8 | Taille maximale des fichiers média en Mo |

Historique du contexte

json5
{
  channels: {
    discord: {
      historyLimit: 20  // Number of recent messages included as context (default: 20, set to 0 to disable)
    }
  }
}

Fil de réponse

Le fil de réponse natif est désactivé par défaut. Activez-le avec :

json5
{
  channels: {
    discord: {
      replyToMode: "on"  // Enable native reply threading
    }
  }
}

Utilisez des balises de réponse dans les réponses de l'agent pour contrôler le comportement du fil :

  • [[reply_to_current]] — répondre au message en cours de traitement
  • [[reply_to:<message_id>]] — répondre à un message spécifique

Notifications de réactions

Configurez les notifications d'événements de réaction par serveur :

json5
{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          reactionNotifications: "own"  // Options: "off", "own", "all", "allowlist"
        }
      }
    }
  }
}

Actions d'outils

L'agent peut invoquer un outil discord pour effectuer des actions dans Discord. La plupart des actions sont activées par défaut, à l'exception des rôles et de la modération qui sont désactivés par défaut.

Actions disponibles

| Catégorie | Actions | |-----------|---------| | Réactions | react, sticker, poll | | Messages | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | Fils | threadCreate, threadList, threadReply | | Épingles | pinMessage, unpinMessage, listPins | | Canaux | channelInfo, channelList | | Membres | memberInfo, roleInfo, permissions | | Rôles | roleAdd, roleRemove (désactivés par défaut) | | Modération | timeout, kick, ban (désactivés par défaut) | | Autres | emojiList, voiceStatus, eventList, eventCreate, setPresence |

Fonctionnalités avancées

Support PluralKit

Lorsqu'il est activé, OpenClaw résout les messages proxifiés vers les membres du système sous-jacents, affichant les expéditeurs sous la forme « Member (PK:System) » pour éviter les pings Discord accidentels.

Interface de boutons d'approbation d'exécution

Dans les conversations en DM, OpenClaw peut présenter des boutons d'approbation d'exécution pour la confirmation interactive des actions d'outils.

Configuration des tentatives de réessai

Les appels API sortants réessaient automatiquement en cas de limitation de débit en utilisant l'en-tête retry_after de Discord avec un backoff exponentiel. Configurez le comportement de réessai via les paramètres channels.discord.retry.

Dépannage

Le bot est en ligne mais ne répond pas

  1. Vérifiez le Message Content Intent : Sans cet intent, le bot se connecte mais ne peut pas lire le texte des messages. Allez dans le portail développeur → Bot → Privileged Gateway Intents et assurez-vous que MESSAGE CONTENT INTENT est activé.

  2. Vérifiez les permissions du canal : Assurez-vous que le bot dispose des permissions View Channels et Send Messages dans le canal cible.

  3. Vérifiez les exigences de mention : Si requireMention est activé pour le serveur ou le canal, vous devez @mentionner le bot.

  4. Vérifiez les listes d'autorisation serveur/canal : Vérifiez que le canal n'est pas bloqué par la configuration de la liste d'autorisation.

Erreur « Used Disallowed Intents »

Cela signifie que les intents requis ne sont pas activés dans le portail développeur :

  1. Allez dans le portail développeur → Bot → Privileged Gateway Intents
  2. Activez MESSAGE CONTENT INTENT
  3. Sauvegardez et redémarrez la passerelle OpenClaw

Les DM ne fonctionnent pas

  1. Vérifiez que dm.enabled n'est pas défini sur false
  2. Vérifiez la politique de DM — si elle est définie sur « allowlist », assurez-vous que l'identifiant de l'utilisateur est inclus
  3. Si vous utilisez la politique « pairing », vérifiez si le code d'appairage a expiré (limite d'une heure)

Commandes de diagnostic

Utilisez les outils de diagnostic intégrés pour identifier les problèmes :

bash
# Run full diagnostics
openclaw doctor

# Check channel status with connection probe
openclaw channels status --probe

Bonnes pratiques

  1. Traitez les tokens de bot comme des mots de passe — utilisez des variables d'environnement sur les hôtes supervisés, ne commitez jamais de tokens dans le contrôle de version.
  2. N'accordez que les permissions nécessaires — évitez la permission Administrator sauf en phase de débogage actif.
  3. Utilisez les politiques de DM par appairage ou liste d'autorisation — la politique « open » ne devrait être utilisée que pour les bots publics avec une limitation de débit appropriée.
  4. Activez le Server Members Intent si vous utilisez le contrôle d'accès basé sur les listes d'autorisation pour une correspondance des membres plus fiable.
  5. Utilisez requireMention dans les serveurs actifs pour empêcher le bot de répondre à chaque message.
  6. Redémarrez la passerelle avec --force si elle se bloque : openclaw gateway restart --force.

Prochaines étapes