Discord (Bot API)

Status: klaar voor DM’s en guildkanalen via de officiële Discord-gateway.

• Koppeling — Discord-DM’s staan standaard op koppelingsmodus.
• Slash-commando’s — Natief commandogedrag en commandocatalogus.
• Kanaalprobleemoplossing — Kanaaloverschrijdende diagnostiek en herstelflow.

Snelle installatie

Je moet een nieuwe applicatie met bot aanmaken, de bot toevoegen aan je server en koppelen met OpenClaw. We raden aan de bot toe te voegen aan je eigen privéserver. Als je er nog geen hebt, maak er dan eerst een aan (kies Create My Own > For me and my friends).

Stap 1: Maak een Discord-applicatie en bot aan

Ga naar het [Discord Developer Portal](https://discord.com/developers/applications) en klik op **New Application**. Geef het een naam zoals "OpenClaw".

Klik op **Bot** in de zijbalk. Stel de **Username** in op wat je je OpenClaw-agent noemt.

Stap 2: Schakel geprivilegieerde intents in

Nog steeds op de **Bot**-pagina, scroll naar beneden naar **Privileged Gateway Intents** en schakel in:

- **Message Content Intent** (vereist)
- **Server Members Intent** (aanbevolen; vereist voor rol-allowlists en naam-naar-ID-matching)
- **Presence Intent** (optioneel; alleen nodig voor presence-updates)

Stap 3: Kopieer je bot-token

Scroll terug naar boven op de **Bot**-pagina en klik op **Reset Token**.

> **Opmerking:** Ondanks de naam genereert dit je eerste token — er wordt niets "gereset".

Kopieer het token en sla het ergens op. Dit is je **Bot Token** en je hebt het zo nodig.

Stap 4: Genereer een uitnodigings-URL en voeg de bot toe aan je server

Klik op **OAuth2** in de zijbalk. Je genereert een uitnodigings-URL met de juiste machtigingen om de bot aan je server toe te voegen.

Scroll naar beneden naar **OAuth2 URL Generator** en schakel in:

- `bot`
- `applications.commands`

Een **Bot Permissions**-sectie verschijnt eronder. Schakel in:

- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions (optioneel)

Kopieer de gegenereerde URL onderaan, plak deze in je browser, selecteer je server en klik op **Continue** om te verbinden. Je zou nu je bot in de Discord-server moeten zien.

Stap 5: Schakel Developer Mode in en verzamel je ID’s

Terug in de Discord-app moet je Developer Mode inschakelen zodat je interne ID's kunt kopiëren.

1. Klik op **User Settings** (tandwielicoon naast je avatar) → **Advanced** → schakel **Developer Mode** in
2. Klik met de rechtermuisknop op je **servericoon** in de zijbalk → **Copy Server ID**
3. Klik met de rechtermuisknop op je **eigen avatar** → **Copy User ID**

Bewaar je **Server ID** en **User ID** samen met je Bot Token — je stuurt alle drie naar OpenClaw in de volgende stap.

Stap 6: Sta DM’s toe van serverleden

Om koppeling te laten werken, moet Discord je bot toestaan om je een DM te sturen. Klik met de rechtermuisknop op je **servericoon** → **Privacy Settings** → schakel **Direct Messages** in.

Dit laat serverleden (inclusief bots) je DM's sturen. Houd dit ingeschakeld als je Discord-DM's met OpenClaw wilt gebruiken. Als je alleen guildkanalen wilt gebruiken, kun je DM's uitschakelen na koppeling.

Stap 7: Stel je bot-token veilig in (verstuur het niet in chat)

Je Discord-bot-token is een geheim (net als een wachtwoord). Stel het in op de machine die OpenClaw draait voordat je je agent een bericht stuurt.

openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway

Als OpenClaw al draait als achtergrondservice, gebruik dan `openclaw gateway restart` in plaats daarvan.

Stap 8: Configureer OpenClaw en koppel

  #### Vraag je agent
    Chat met je OpenClaw-agent op een bestaand kanaal (bijv. Telegram) en vertel het. Als Discord je eerste kanaal is, gebruik dan de CLI-/configtab.

    > "I already set my Discord bot token in config. Please finish Discord setup with User ID `<user_id>` and Server ID `<server_id>`."

  #### CLI / config
    Als je liever bestandgebaseerde configuratie gebruikt, stel in:

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

    Env-terugval voor het standaardaccount:

DISCORD_BOT_TOKEN=...

    SecretRef-waarden worden ook ondersteund voor `channels.discord.token` (env/file/exec-providers). Zie [Geheimenbeheer](/docs/gateway/secrets).

Stap 9: Keur eerste DM-koppeling goed

Wacht tot de gateway draait en DM vervolgens je bot in Discord. Het zal antwoorden met een koppelingscode.


  #### Vraag je agent
    Stuur de koppelingscode naar je agent op je bestaande kanaal:

    > "Approve this Discord pairing code: `<CODE>`"

  #### CLI

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Koppelingscodes verlopen na 1 uur.

Je zou nu met je agent moeten kunnen chatten in Discord via DM.

Opmerking: Tokenresolutie is accountbewust. Configtokenwaarden winnen van env-terugval. DISCORD_BOT_TOKEN wordt alleen gebruikt voor het standaardaccount. Voor geavanceerde uitgaande oproepen (berichttool/kanaalacties) wordt een expliciet per-oproep token gebruikt voor die oproep. Accountbeleid/retry-instellingen komen nog steeds uit het geselecteerde account in de actieve runtimesnapshot.

Aanbevolen: stel een guild-werkruimte in

Zodra DM’s werken, kun je je Discord-server opzetten als een volledige werkruimte waar elk kanaal zijn eigen agentsessie met eigen context krijgt. Dit wordt aanbevolen voor privéservers waar het alleen jij en je bot bent.

Stap 1: Voeg je server toe aan de guild-allowlist

Dit stelt je agent in staat om te reageren in elk kanaal op je server, niet alleen DM's.


  #### Vraag je agent
    > "Add my Discord Server ID `<server_id>` to the guild allowlist"

  #### Config

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

Stap 2: Sta antwoorden toe zonder @vermelding

Standaard reageert je agent alleen in guildkanalen wanneer @vermeld. Voor een privéserver wil je waarschijnlijk dat het op elk bericht reageert.


  #### Vraag je agent
    > "Allow my agent to respond on this server without having to be @mentioned"

  #### Config
    Stel `requireMention: false` in je guildconfiguratie in:

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

Stap 3: Plan voor geheugen in guildkanalen

Standaard wordt langetermijngeheugen (MEMORY.md) alleen geladen in DM-sessies. Guildkanalen laden MEMORY.md niet automatisch.


  #### Vraag je agent
    > "When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md."

  #### Handmatig
    Als je gedeelde context in elk kanaal nodig hebt, zet de stabiele instructies in `AGENTS.md` of `USER.md` (ze worden geïnjecteerd voor elke sessie). Bewaar langetermijnnotities in `MEMORY.md` en open ze op aanvraag met geheugentools.

Nu kun je kanalen aanmaken op je Discord-server en beginnen met chatten. Je agent kan de kanaalnaam zien, en elk kanaal krijgt zijn eigen geïsoleerde sessie — zodat je #coding, #home, #research of wat bij je workflow past kunt opzetten.

Runtimemodel

• De gateway beheert de Discord-verbinding.
• Antwoordroutering is deterministisch: Discord-inkomende berichten antwoorden terug naar Discord.
• Standaard (session.dmScope=main) delen directe chats de agent-hoofdsessie (agent:main:main).
• Guildkanalen zijn geïsoleerde sessiesleutels (agent:<agentId>:discord:channel:<channelId>).
• Groeps-DM’s worden standaard genegeerd (channels.discord.dm.groupEnabled=false).
• Native slash-commando’s draaien in geïsoleerde commandosessies (agent:<agentId>:discord:slash:<userId>), met behoud van CommandTargetSessionKey naar de gerouteerde gesprekssessie.

Forumkanalen

Discord-forum- en mediakanalen accepteren alleen threadposts. OpenClaw ondersteunt twee manieren om ze aan te maken:

• Verstuur een bericht naar het forum-ouderkanaal (channel:<forumId>) om automatisch een thread aan te maken. De threadtitel gebruikt de eerste niet-lege regel van je bericht.
• Gebruik openclaw message thread create om direct een thread aan te maken. Geef geen --message-id door voor forumkanalen.

Voorbeeld: verstuur naar forum-ouderkanaal om een thread aan te maken

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

Voorbeeld: maak een forumthread expliciet aan

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

Forum-ouderkanalen accepteren geen Discord-componenten. Als je componenten nodig hebt, verstuur naar de thread zelf (channel:<threadId>).

Interactieve componenten

OpenClaw ondersteunt Discord components v2-containers voor agentberichten. Gebruik de berichttool met een components-payload. Interactieresultaten worden teruggerouteerd naar de agent als normale inkomende berichten en volgen de bestaande Discord replyToMode-instellingen.

Ondersteunde blokken:

• text, section, separator, actions, media-gallery, file
• Actierijen staan maximaal 5 knoppen of een enkel selectiemenu toe
• Selectietypen: string, user, role, mentionable, channel

Standaard zijn componenten voor eenmalig gebruik. Stel components.reusable=true in om knoppen, selecties en formulieren meerdere keren te laten gebruiken totdat ze verlopen.

Om te beperken wie op een knop kan klikken, stel allowedUsers in op die knop (Discord-gebruikers-ID’s, tags of *). Wanneer geconfigureerd, ontvangen niet-overeenkomende gebruikers een kortstondige weigering.

De /model en /models slash-commando’s openen een interactieve modelpicker met provider- en model-dropdowns plus een verzendstap. Het picker-antwoord is kortstondig en alleen de aanroepende gebruiker kan het gebruiken.

Bestandsbijlagen:

• file-blokken moeten naar een bijlagereferentie wijzen (attachment://<filename>)
• Verstrek de bijlage via media/path/filePath (enkel bestand); gebruik media-gallery voor meerdere bestanden
• Gebruik filename om de uploadnaam te overschrijven wanneer deze moet overeenkomen met de bijlagereferentie

Modale formulieren:

• Voeg components.modal toe met maximaal 5 velden
• Veldtypen: text, checkbox, radio, select, role-select, user-select
• OpenClaw voegt automatisch een triggerknop toe

Voorbeeld:

{
  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" },
          ],
        },
      ],
    },
  },
}

Toegangscontrole en routering

DM-beleid

`channels.discord.dmPolicy` beheert DM-toegang (verouderd: `channels.discord.dm.policy`):

- `pairing` (standaard)
- `allowlist`
- `open` (vereist dat `channels.discord.allowFrom` `"*"` bevat; verouderd: `channels.discord.dm.allowFrom`)
- `disabled`

Als het DM-beleid niet open is, worden onbekende gebruikers geblokkeerd (of gevraagd om koppeling in `pairing`-modus).

Multi-account-voorrang:

- `channels.discord.accounts.default.allowFrom` geldt alleen voor het `default`-account.
- Benoemde accounts erven `channels.discord.allowFrom` wanneer hun eigen `allowFrom` niet is ingesteld.
- Benoemde accounts erven niet `channels.discord.accounts.default.allowFrom`.

DM-doelformaat voor aflevering:

- `user:<id>`
- `<@id>` vermelding

Kale numerieke ID's zijn ambigu en worden geweigerd tenzij een expliciet user/channel-doeltype wordt opgegeven.

Guildbeleid

Guildafhandeling wordt beheerd door `channels.discord.groupPolicy`:

- `open`
- `allowlist`
- `disabled`

Veilige basislijn wanneer `channels.discord` bestaat is `allowlist`.

`allowlist`-gedrag:

- guild moet overeenkomen met `channels.discord.guilds` (`id` voorkeur, slug geaccepteerd)
- optionele afzender-allowlists: `users` (stabiele ID's aanbevolen) en `roles` (alleen rol-ID's); als een van beide is geconfigureerd, worden afzenders toegestaan wanneer ze overeenkomen met `users` OF `roles`
- directe naam-/tagmatching is standaard uitgeschakeld; schakel `channels.discord.dangerouslyAllowNameMatching: true` alleen in als noodcompatibiliteitsmodus
- namen/tags worden ondersteund voor `users`, maar ID's zijn veiliger; `openclaw security audit` waarschuwt wanneer naam-/tagvermeldingen worden gebruikt
- als een guild `channels` heeft geconfigureerd, worden niet-vermelde kanalen geweigerd
- als een guild geen `channels`-blok heeft, zijn alle kanalen in die allowlisted guild toegestaan

Voorbeeld:

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

Als je alleen `DISCORD_BOT_TOKEN` instelt en geen `channels.discord`-blok aanmaakt, is de runtime-terugval `groupPolicy="allowlist"` (met een waarschuwing in logs), zelfs als `channels.defaults.groupPolicy` `open` is.

Vermeldingen en groeps-DM’s

Guildberichten worden standaard vermelding-beveiligd.

Vermeldingsdetectie omvat:

- expliciete botvermelding
- geconfigureerde vermeldingspatronen (`agents.list[].groupChat.mentionPatterns`, terugval `messages.groupChat.mentionPatterns`)
- impliciet antwoord-op-bot-gedrag in ondersteunde gevallen

`requireMention` wordt geconfigureerd per guild/kanaal (`channels.discord.guilds...`).
`ignoreOtherMentions` laat optioneel berichten vallen die een andere gebruiker/rol vermelden maar niet de bot (exclusief @everyone/@here).

Groeps-DM's:

- standaard: genegeerd (`dm.groupEnabled=false`)
- optionele allowlist via `dm.groupChannels` (kanaal-ID's of slugs)

Rolgebaseerde agentroutering

Gebruik bindings[].match.roles om Discord-guildleden naar verschillende agents te routeren op rol-ID. Rolgebaseerde bindings accepteren alleen rol-ID’s en worden geëvalueerd na peer- of parent-peer-bindings en vóór guild-only-bindings. Als een binding ook andere matchvelden instelt (bijvoorbeeld peer + guildId + roles), moeten alle geconfigureerde velden overeenkomen.

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

Developer Portal-setup

1. Discord Developer Portal -> **Applications** -> **New Application**
2. **Bot** -> **Add Bot**
3. Kopieer bot-token

In **Bot -> Privileged Gateway Intents**, schakel in:

- Message Content Intent
- Server Members Intent (aanbevolen)

Presence intent is optioneel en alleen vereist als je presence-updates wilt ontvangen. Het instellen van bot-presence (`setPresence`) vereist niet het inschakelen van presence-updates voor leden.

OAuth URL-generator:

- scopes: `bot`, `applications.commands`

Typische basismachtigingen:

- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions (optioneel)

Vermijd `Administrator` tenzij expliciet nodig.

Schakel Discord Developer Mode in en kopieer:

- server-ID
- kanaal-ID
- gebruikers-ID

Gebruik bij voorkeur numerieke ID's in OpenClaw-configuratie voor betrouwbare audits en probes.

Native commando’s en commando-auth

• commands.native staat standaard op "auto" en is ingeschakeld voor Discord.
• Per-kanaal-overschrijving: channels.discord.commands.native.
• commands.native=false wist expliciet eerder geregistreerde Discord native commando’s.
• Native commando-auth gebruikt dezelfde Discord-allowlists/beleidsregels als normale berichtafhandeling.
• Commando’s kunnen nog steeds zichtbaar zijn in de Discord-UI voor gebruikers die niet zijn geautoriseerd; uitvoering handhaaft nog steeds OpenClaw-auth en retourneert “not authorized”.

Zie Slash-commando’s voor commandocatalogus en gedrag.

Standaard slash-commando-instellingen:

• ephemeral: true

Functiedetails

Discord ondersteunt reply-tags in agentuitvoer:

- `[[reply_to_current]]`
- `[[reply_to:<id>]]`

Beheerd door `channels.discord.replyToMode`:

- `off` (standaard)
- `first`
- `all`

Opmerking: `off` schakelt impliciete reply-threading uit. Expliciete `[[reply_to_*]]`-tags worden nog steeds gehonoreerd.

Bericht-ID's worden getoond in context/geschiedenis zodat agents specifieke berichten kunnen targeten.

OpenClaw kan conceptantwoorden streamen door een tijdelijk bericht te versturen en dit te bewerken naarmate tekst arriveert.

- `channels.discord.streaming` beheert preview-streaming (`off` | `partial` | `block` | `progress`, standaard: `off`).
- `progress` wordt geaccepteerd voor kanaaloverschrijdende consistentie en mapt naar `partial` op Discord.
- `channels.discord.streamMode` is een verouderde alias en wordt automatisch gemigreerd.
- `partial` bewerkt een enkel preview-bericht naarmate tokens arriveren.
- `block` zendt concept-chunks uit (gebruik `draftChunk` om grootte en breekpunten af te stemmen).

Voorbeeld:

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

`block`-modus chunk-standaarden (beperkt tot `channels.discord.textChunkLimit`):

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

Preview-streaming is alleen tekst; media-antwoorden vallen terug op normale aflevering.

Opmerking: preview-streaming is apart van blokstreaming. Wanneer blokstreaming expliciet is ingeschakeld voor Discord, slaat OpenClaw de preview-stream over om dubbel streamen te voorkomen.

Guildgeschiedeniscontext:

- `channels.discord.historyLimit` standaard `20`
- terugval: `messages.groupChat.historyLimit`
- `0` schakelt uit

DM-geschiedeniscontroles:

- `channels.discord.dmHistoryLimit`
- `channels.discord.dms["<user_id>"].historyLimit`

Threadgedrag:

- Discord-threads worden gerouteerd als kanaalsessies
- ouder-threadmetadata kan worden gebruikt voor ouder-sessiekoppeling
- threadconfiguratie erft ouderkanaalconfiguratie tenzij een thread-specifieke vermelding bestaat

Kanaalonderwerpen worden geïnjecteerd als **niet-vertrouwde** context (niet als systeemprompt).

Discord kan een thread binden aan een sessiedoel zodat vervolgberichten in die thread naar dezelfde sessie blijven routeren (inclusief subagentsessies).

Commando's:

- `/focus <target>` bind huidige/nieuwe thread aan een subagent-/sessiedoel
- `/unfocus` verwijder huidige threadbinding
- `/agents` toon actieve runs en bindingsstatus
- `/session idle <duration|off>` inspecteer/update inactiviteits-auto-unfocus voor gefocuste bindings
- `/session max-age <duration|off>` inspecteer/update harde maximale leeftijd voor gefocuste bindings

Configuratie:

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

Opmerkingen:

- `session.threadBindings.*` stelt globale standaarden in.
- `channels.discord.threadBindings.*` overschrijft Discord-gedrag.
- `spawnSubagentSessions` moet true zijn om automatisch threads aan te maken/binden voor `sessions_spawn({ thread: true })`.
- `spawnAcpSessions` moet true zijn om automatisch threads aan te maken/binden voor ACP (`/acp spawn ... --thread ...` of `sessions_spawn({ runtime: "acp", thread: true })`).
- Als threadbindings zijn uitgeschakeld voor een account, zijn `/focus` en gerelateerde threadbinding-operaties niet beschikbaar.

Zie [Sub-agents](/docs/tools/subagents), [ACP Agents](/docs/tools/acp-agents) en [Configuratiereferentie](/docs/gateway/configuration-reference).

Voor stabiele "altijd-aan" ACP-werkruimten, configureer top-level getypte ACP-bindings die Discord-gesprekken targeten.

Configuratiepad:

- `bindings[]` met `type: "acp"` en `match.channel: "discord"`

Voorbeeld:

{
  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,
            },
          },
        },
      },
    },
  },
}

Opmerkingen:

- Threadberichten kunnen de ouderkanaal-ACP-binding erven.
- In een gebonden kanaal of thread resetten `/new` en `/reset` dezelfde ACP-sessie ter plaatse.
- Tijdelijke threadbindings werken nog steeds en kunnen doelresolutie overschrijven terwijl ze actief zijn.

Zie [ACP Agents](/docs/tools/acp-agents) voor bindinggedragdetails.

Per-guild-reactienotificatiemodus:

- `off`
- `own` (standaard)
- `all`
- `allowlist` (gebruikt `guilds.<id>.users`)

Reactie-events worden omgezet naar systeemevents en gekoppeld aan de gerouteerde Discord-sessie.

`ackReaction` stuurt een bevestigingsemoji terwijl OpenClaw een inkomend bericht verwerkt.

Resolutievolgorde:

- `channels.discord.accounts.<accountId>.ackReaction`
- `channels.discord.ackReaction`
- `messages.ackReaction`
- agent-identiteitsemoji-terugval (`agents.list[].identity.emoji`, anders "👀")

Opmerkingen:

- Discord accepteert unicode-emoji of aangepaste emoji-namen.
- Gebruik `""` om de reactie voor een kanaal of account uit te schakelen.

Kanaalgeïnitieerde configschrijfacties zijn standaard ingeschakeld.

Dit beïnvloedt `/config set|unset`-flows (wanneer commandofuncties zijn ingeschakeld).

Uitschakelen:

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

Routeer Discord-gateway-WebSocket-verkeer en opstart-REST-lookups (applicatie-ID + allowlist-resolutie) via een HTTP(S)-proxy met `channels.discord.proxy`.

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

Per-account-overschrijving:

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

Schakel PluralKit-resolutie in om geproxyde berichten te mappen naar systeemlididentiteit:

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optioneel; nodig voor privésystemen
      },
    },
  },
}

Opmerkingen:

- allowlists kunnen `pk:<memberId>` gebruiken
- lid-weergavenamen worden alleen gematcht op naam/slug wanneer `channels.discord.dangerouslyAllowNameMatching: true`
- lookups gebruiken het oorspronkelijke bericht-ID en zijn tijdvenster-beperkt
- als lookup faalt, worden geproxyde berichten behandeld als botberichten en verworpen tenzij `allowBots=true`

Presence-updates worden toegepast wanneer je een status- of activiteitsveld instelt, of wanneer je auto-presence inschakelt.

Alleen-status-voorbeeld:

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

Activiteitsvoorbeeld (aangepaste status is het standaard activiteitstype):

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

Streaming-voorbeeld:

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

Activiteitstypemap:

- 0: Playing
- 1: Streaming (vereist `activityUrl`)
- 2: Listening
- 3: Watching
- 4: Custom (gebruikt de activiteitstekst als statusstatus; emoji is optioneel)
- 5: Competing

Auto-presence-voorbeeld (runtime-gezondheidssignaal):

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

Auto-presence mapt runtime-beschikbaarheid naar Discord-status: healthy => online, degraded of unknown => idle, exhausted of unavailable => dnd. Optionele tekstoverschrijvingen:

- `autoPresence.healthyText`
- `autoPresence.degradedText`
- `autoPresence.exhaustedText` (ondersteunt `{reason}` placeholder)

Discord ondersteunt knopgebaseerde exec-goedkeuringen in DM's en kan optioneel goedkeuringsprompts posten in het oorspronkelijke kanaal.

Configuratiepad:

- `channels.discord.execApprovals.enabled`
- `channels.discord.execApprovals.approvers`
- `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, standaard: `dm`)
- `agentFilter`, `sessionFilter`, `cleanupAfterResolve`

Wanneer `target` `channel` of `both` is, is de goedkeuringsprompt zichtbaar in het kanaal. Alleen geconfigureerde goedkeurders kunnen de knoppen gebruiken; andere gebruikers ontvangen een kortstondige weigering. Goedkeuringsprompts bevatten de commandotekst, dus schakel kanaalaflevering alleen in in vertrouwde kanalen. Als het kanaal-ID niet kan worden afgeleid uit de sessiesleutel, valt OpenClaw terug op DM-aflevering.

Gateway-auth voor deze handler gebruikt hetzelfde gedeelde credentialresolutiecontract als andere Gateway-clients:

- env-first lokale auth (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` dan `gateway.auth.*`)
- in lokale modus kan `gateway.remote.*` worden gebruikt als terugval alleen wanneer `gateway.auth.*` niet is ingesteld; geconfigureerde-maar-niet-opgeloste lokale SecretRefs falen gesloten
- remote-modusondersteuning via `gateway.remote.*` wanneer van toepassing
- URL-overschrijvingen zijn overschrijvingsveilig: CLI-overschrijvingen hergebruiken geen impliciete credentials, en env-overschrijvingen gebruiken alleen env-credentials

Als goedkeuringen falen met onbekende goedkeurings-ID's, verifieer dan de goedkeurderslijst en functie-inschakeling.

Gerelateerde documentatie: [Exec-goedkeuringen](/docs/tools/exec-approvals)

Tools en actie-gates

Discord-berichtacties omvatten berichten, kanaalbeheer, moderatie, presence en metadata-acties.

Kernvoorbeelden:

• berichten: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reacties: react, reactions, emojiList
• moderatie: timeout, kick, ban
• presence: setPresence

Actie-gates staan onder channels.discord.actions.*.

Standaard gate-gedrag:

Components v2-UI

OpenClaw gebruikt Discord components v2 voor exec-goedkeuringen en cross-contextmarkeringen. Discord-berichtacties kunnen ook components accepteren voor aangepaste UI (geavanceerd; vereist Carbon-componentinstanties), terwijl verouderde embeds beschikbaar blijven maar niet worden aanbevolen.

• channels.discord.ui.components.accentColor stelt de accentkleur in die wordt gebruikt door Discord-componentcontainers (hex).
• Stel per account in met channels.discord.accounts.<id>.ui.components.accentColor.
• embeds worden genegeerd wanneer components v2 aanwezig zijn.

Voorbeeld:

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

Spraakkanalen

OpenClaw kan deelnemen aan Discord-spraakkanalen voor realtime, doorlopende gesprekken. Dit staat los van spraakberichtbijlagen.

Vereisten:

• Schakel native commando’s in (commands.native of channels.discord.commands.native).
• Configureer channels.discord.voice.
• De bot heeft Connect + Speak-machtigingen nodig in het doelspraakkanaal.

Gebruik het Discord-only native commando /vc join|leave|status om sessies te beheren. Het commando gebruikt de standaard account-agent en volgt dezelfde allowlist- en groepsbeleidsregels als andere Discord-commando’s.

Auto-join-voorbeeld:

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

Opmerkingen:

• voice.tts overschrijft messages.tts alleen voor spraakweergave.
• Spraaktranscript-beurten leiden eigenaarsstatus af van Discord allowFrom (of dm.allowFrom); niet-eigenaarsprekers hebben geen toegang tot eigenaarstools (bijvoorbeeld gateway en cron).
• Spraak is standaard ingeschakeld; stel channels.discord.voice.enabled=false in om het uit te schakelen.
• voice.daveEncryption en voice.decryptionFailureTolerance worden doorgegeven aan @discordjs/voice join-opties.
• @discordjs/voice-standaarden zijn daveEncryption=true en decryptionFailureTolerance=24 indien niet ingesteld.
• OpenClaw bewaakt ook ontvangst-decryptfouten en herstelt automatisch door het spraakkanaal te verlaten/opnieuw te betreden na herhaalde fouten in een kort tijdsvenster.
• Als ontvangstlogs herhaaldelijk DecryptionFailed(UnencryptedWhenPassthroughDisabled) tonen, kan dit de upstream @discordjs/voice ontvangstbug zijn die wordt bijgehouden in discord.js #11419.

Spraakberichten

Discord-spraakberichten tonen een golfvormpreview en vereisen OGG/Opus-audio plus metadata. OpenClaw genereert de golfvorm automatisch, maar het heeft ffmpeg en ffprobe nodig die beschikbaar zijn op de gatewayhost om audiobestanden te inspecteren en converteren.

Vereisten en beperkingen:

• Verstrek een lokaal bestandspad (URL’s worden geweigerd).
• Laat tekstinhoud weg (Discord staat geen tekst + spraakbericht in dezelfde payload toe).
• Elk audioformaat wordt geaccepteerd; OpenClaw converteert naar OGG/Opus wanneer nodig.

Voorbeeld:

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

Probleemoplossing

- schakel Message Content Intent in
- schakel Server Members Intent in wanneer je afhankelijk bent van gebruiker-/lidresolutie
- herstart de gateway na het wijzigen van intents

- verifieer `groupPolicy`
- verifieer guild-allowlist onder `channels.discord.guilds`
- als guild `channels`-map bestaat, zijn alleen vermelde kanalen toegestaan
- verifieer `requireMention`-gedrag en vermeldingspatronen

Nuttige controles:

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

Veelvoorkomende oorzaken:

- `groupPolicy="allowlist"` zonder overeenkomende guild-/kanaal-allowlist
- `requireMention` geconfigureerd op de verkeerde plek (moet onder `channels.discord.guilds` of kanaalvermelding staan)
- afzender geblokkeerd door guild-/kanaal-`users`-allowlist

Typische logs:

- `Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE`
- `Slow listener detected ...`
- `discord inbound worker timed out after ...`

Luisteraar-budgetknop:

- enkel-account: `channels.discord.eventQueue.listenerTimeout`
- multi-account: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`

Worker-run-timeout-knop:

- enkel-account: `channels.discord.inboundWorker.runTimeoutMs`
- multi-account: `channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- standaard: `1800000` (30 minuten); stel `0` in om uit te schakelen

Aanbevolen basislijn:

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

Gebruik `eventQueue.listenerTimeout` voor trage luisteraar-setup en `inboundWorker.runTimeoutMs`
alleen als je een apart veiligheidsventiel wilt voor in de wachtrij geplaatste agentbeurten.

`channels status --probe` machtigingscontroles werken alleen voor numerieke kanaal-ID's.

Als je slug-sleutels gebruikt, kan runtime-matching nog steeds werken, maar probe kan machtigingen niet volledig verifiëren.

- DM uitgeschakeld: `channels.discord.dm.enabled=false`
- DM-beleid uitgeschakeld: `channels.discord.dmPolicy="disabled"` (verouderd: `channels.discord.dm.policy`)
- wacht op koppelingsgoedkeuring in `pairing`-modus

Standaard worden door bots geschreven berichten genegeerd.

Als je `channels.discord.allowBots=true` instelt, gebruik strikte vermeldings- en allowlistregels om lusgedrag te voorkomen.
Gebruik bij voorkeur `channels.discord.allowBots="mentions"` om alleen botberichten te accepteren die de bot vermelden.

- houd OpenClaw actueel (`openclaw update`) zodat de Discord-spraak-ontvangst-herstellogica aanwezig is
- bevestig `channels.discord.voice.daveEncryption=true` (standaard)
- begin met `channels.discord.voice.decryptionFailureTolerance=24` (upstream standaard) en stem alleen af indien nodig
- let op logs voor:
  - `discord voice: DAVE decrypt failures detected`
  - `discord voice: repeated decrypt failures; attempting rejoin`
- als fouten aanhouden na automatisch herintredin, verzamel logs en vergelijk met [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)

Configuratiereferentie-verwijzingen

Primaire referentie:

• Configuratiereferentie - Discord

Belangrijkste Discord-velden:

• opstart/auth: enabled, token, accounts.*, allowBots
• beleid: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• commando: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• event-wachtrij: eventQueue.listenerTimeout (luisteraarbudget), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• inkomende worker: inboundWorker.runTimeoutMs
• antwoord/geschiedenis: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• aflevering: textChunkLimit, chunkMode, maxLinesPerMessage
• streaming: streaming (verouderde alias: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• media/retry: mediaMaxMb, retry
  • mediaMaxMb beperkt uitgaande Discord-uploads (standaard: 8MB)
• acties: actions.*
• presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• functies: threadBindings, top-level bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Veiligheid en operaties

• Behandel bot-tokens als geheimen (DISCORD_BOT_TOKEN voorkeur in begeleide omgevingen).
• Verleen minimale Discord-machtigingen.
• Als commando-deploy/status verouderd is, herstart de gateway en controleer opnieuw met openclaw channels status --probe.

Gerelateerd

• Koppeling
• Kanaalroutering
• Multi-agent-routering
• Probleemoplossing
• Slash-commando’s