​

Discord (API Bot)

​

Configuration rapide

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

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

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

Recommandé : configurer un espace de travail de serveur

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

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

​

Modèle d’exécution

• La passerelle gère la connexion Discord.
• Le routage des réponses est déterministe : les réponses entrantes Discord repartent vers Discord.
• 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 MP 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 transportant CommandTargetSessionKey vers la session de conversation routée.

​

Canaux forum

• Envoyer un message au parent du forum (channel:<forumId>) pour créer automatiquement un fil. Le titre du fil utilise la première ligne non vide de votre message.
• Utiliser openclaw message thread create pour créer un fil directement. Ne passez pas --message-id pour les canaux forum.

openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

​

Composants interactifs

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

• 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 (fichier unique) ; utilisez media-gallery pour plusieurs fichiers
• utilisez filename pour remplacer le nom de téléversement lorsqu’il doit correspondre à la référence de pièce jointe

• ajoutez components.modal avec jusqu’à 5 champs
• types de champ : text, checkbox, radio, select, role-select, user-select
• OpenClaw ajoute automatiquement un bouton de déclenchement

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}

​

Contrôle d’accès et routage

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

​

Routage d’agent basé sur les rôles

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

​

Configuration du Portail développeur

​

Commandes natives et authentification des commandes

• commands.native vaut par défaut "auto" et est activé pour Discord.
• Remplacement par canal : channels.discord.commands.native.
• commands.native=false efface explicitement les commandes natives Discord précédemment enregistrées.
• L’authentification des commandes natives utilise les mêmes listes d’autorisation/politiques Discord que la gestion normale des messages.
• Les commandes peuvent quand même être visibles dans l’interface Discord pour les utilisateurs non autorisés ; l’exécution applique toujours l’authentification OpenClaw et renvoie « non autorisé ».

• ephemeral: true

​

Détails des fonctionnalités

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in
      },
    },
  },
}

{
  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_...", // optional; needed for private systems
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}

​

Outils et contrôles d’actions

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

​

UI Components v2

• channels.discord.ui.components.accentColor définit la couleur d’accent utilisée par les conteneurs de composants Discord (hex).
• Définissez-la par compte avec channels.discord.accounts.<id>.ui.components.accentColor.
• embeds sont ignorés lorsque des components v2 sont présents.

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

​

Canaux vocaux

• Activez les commandes natives (commands.native ou channels.discord.commands.native).
• Configurez channels.discord.voice.
• Le bot a besoin des autorisations Connect + Speak dans le canal vocal cible.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• voice.tts remplace messages.tts uniquement pour la lecture vocale.
• Les tours de transcription vocale dérivent le statut de propriétaire à partir de Discord allowFrom (ou dm.allowFrom) ; les intervenants non propriétaires ne peuvent pas accéder aux outils réservés au propriétaire (par exemple gateway et cron).
• La voix est activée par défaut ; définissez channels.discord.voice.enabled=false pour la désactiver.
• voice.daveEncryption et voice.decryptionFailureTolerance sont transmis aux options de jonction @discordjs/voice.
• Les valeurs par défaut de @discordjs/voice sont daveEncryption=true et decryptionFailureTolerance=24 si elles ne sont pas définies.
• OpenClaw surveille également les échecs de déchiffrement à la réception et récupère automatiquement en quittant puis en rejoignant à nouveau le canal vocal après des échecs répétés dans une courte fenêtre.
• Si les journaux de réception affichent de façon répétée DecryptionFailed(UnencryptedWhenPassthroughDisabled), il peut s’agir du bug de réception amont @discordjs/voice suivi dans discord.js #11419.

​

Messages vocaux

• Fournissez un chemin de fichier local (les URL sont refusées).
• Omettez le contenu texte (Discord n’autorise pas le texte + message vocal dans la même charge utile).
• Tout format audio est accepté ; OpenClaw convertit en OGG/Opus si nécessaire.

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

​

Dépannage

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

Indications de référence de configuration

• Référence de configuration - Discord

• démarrage/auth : enabled, token, accounts.*, allowBots
• politique : groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• commande : commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• file d’événements : eventQueue.listenerTimeout (budget du listener), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• worker entrant : inboundWorker.runTimeoutMs
• réponse/historique : replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• remise : textChunkLimit, chunkMode, maxLinesPerMessage
• streaming : streaming (alias hérité : streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• média/nouvelle tentative : mediaMaxMb, retry
  • mediaMaxMb plafonne les téléversements Discord sortants (par défaut : 100MB)
• actions : actions.*
• présence : activity, status, activityType, activityUrl
• UI : ui.components.accentColor
• fonctionnalités : threadBindings, bindings[] de niveau supérieur (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

Sécurité et opérations

• Traitez les jetons de bot comme des secrets (DISCORD_BOT_TOKEN de préférence dans les environnements supervisés).
• Accordez le minimum d’autorisations Discord nécessaire.
• Si le déploiement/l’état des commandes est obsolète, redémarrez la passerelle et revérifiez avec openclaw channels status --probe.

​

Liens associés

• Appairage
• Groupes
• Routage des canaux
• Sécurité
• Routage multi-agent
• Dépannage
• Commandes slash