​

Discord (API Bot)

​

Configurazione rapida

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>

​

Consigliato: configura un workspace guild

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

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

​

Modello di runtime

• Il gateway gestisce la connessione Discord.
• L’instradamento delle risposte è deterministico: le risposte in ingresso da Discord tornano su Discord.
• Per impostazione predefinita (session.dmScope=main), le chat dirette condividono la sessione principale dell’agente (agent:main:main).
• I canali guild hanno chiavi di sessione isolate (agent:<agentId>:discord:channel:<channelId>).
• I DM di gruppo vengono ignorati per impostazione predefinita (channels.discord.dm.groupEnabled=false).
• I comandi slash nativi vengono eseguiti in sessioni comando isolate (agent:<agentId>:discord:slash:<userId>), continuando però a trasportare CommandTargetSessionKey verso la sessione di conversazione instradata.

​

Canali forum

• Invia un messaggio al forum padre (channel:<forumId>) per creare automaticamente un thread. Il titolo del thread usa la prima riga non vuota del tuo messaggio.
• Usa openclaw message thread create per creare direttamente un thread. Non passare --message-id per i canali 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"

​

Componenti interattivi

• text, section, separator, actions, media-gallery, file
• Le righe di azione consentono fino a 5 pulsanti o un singolo menu di selezione
• Tipi di selezione: string, user, role, mentionable, channel

• i blocchi file devono puntare a un riferimento allegato (attachment://<filename>)
• fornisci l’allegato tramite media/path/filePath (file singolo); usa media-gallery per più file
• usa filename per sovrascrivere il nome di upload quando deve corrispondere al riferimento allegato

• aggiungi components.modal con fino a 5 campi
• Tipi di campo: text, checkbox, radio, select, role-select, user-select
• OpenClaw aggiunge automaticamente un pulsante di attivazione

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Testo di fallback facoltativo",
  components: {
    reusable: true,
    text: "Scegli un percorso",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approva",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Rifiuta", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Scegli un'opzione",
          options: [
            { label: "Opzione A", value: "a" },
            { label: "Opzione B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Dettagli",
      triggerLabel: "Apri modulo",
      fields: [
        { type: "text", label: "Richiedente" },
        {
          type: "select",
          label: "Priorità",
          options: [
            { label: "Bassa", value: "low" },
            { label: "Alta", value: "high" },
          ],
        },
      ],
    },
  },
}

​

Controllo degli accessi e instradamento

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

​

Instradamento agente basato sui ruoli

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

​

Configurazione del Developer Portal

​

Comandi nativi e autorizzazione dei comandi

• commands.native ha come valore predefinito "auto" ed è abilitato per Discord.
• Override per canale: channels.discord.commands.native.
• commands.native=false rimuove esplicitamente i comandi nativi Discord registrati in precedenza.
• L’autorizzazione dei comandi nativi usa le stesse allowlist/criteri Discord della normale gestione dei messaggi.
• I comandi possono comunque essere visibili nell’interfaccia Discord agli utenti non autorizzati; l’esecuzione continua comunque ad applicare l’autorizzazione OpenClaw e restituisce “non autorizzato”.

• ephemeral: true

​

Dettagli delle funzionalità

{
  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_...", // facoltativo; necessario per sistemi privati
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "Tempo di concentrazione",
      activityType: 4,
    },
  },
}

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

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

​

Strumenti e gate delle azioni

• messaggistica: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reazioni: react, reactions, emojiList
• moderazione: timeout, kick, ban
• presenza: setPresence

​

UI components v2

• channels.discord.ui.components.accentColor imposta il colore di accento usato dai contenitori dei componenti Discord (hex).
• Imposta per account con channels.discord.accounts.<id>.ui.components.accentColor.
• embeds vengono ignorati quando sono presenti components v2.

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

​

Canali vocali

• Abilita i comandi nativi (commands.native o channels.discord.commands.native).
• Configura channels.discord.voice.
• Il bot necessita dei permessi Connect + Speak nel canale vocale di destinazione.

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

• voice.tts sovrascrive messages.tts solo per la riproduzione vocale.
• I turni di trascrizione vocale derivano lo stato owner da Discord allowFrom (o dm.allowFrom); i parlanti non owner non possono accedere agli strumenti riservati agli owner (ad esempio gateway e cron).
• Voice è abilitato per impostazione predefinita; imposta channels.discord.voice.enabled=false per disabilitarlo.
• voice.daveEncryption e voice.decryptionFailureTolerance vengono passati alle opzioni di join di @discordjs/voice.
• I valori predefiniti di @discordjs/voice sono daveEncryption=true e decryptionFailureTolerance=24 se non impostati.
• OpenClaw monitora anche i fallimenti di decrittazione in ricezione e si ripristina automaticamente uscendo e rientrando nel canale vocale dopo fallimenti ripetuti in una finestra temporale breve.
• Se i log in ricezione mostrano ripetutamente DecryptionFailed(UnencryptedWhenPassthroughDisabled), potrebbe trattarsi del bug di ricezione upstream @discordjs/voice tracciato in discord.js #11419.

​

Messaggi vocali

• Fornisci un percorso file locale (gli URL vengono rifiutati).
• Ometti il contenuto testuale (Discord non consente testo + messaggio vocale nello stesso payload).
• Qualsiasi formato audio è accettato; OpenClaw lo converte in OGG/Opus quando necessario.

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

​

Risoluzione dei problemi

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

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

​

Riferimenti alla configurazione

• Riferimento di configurazione - Discord

• avvio/autenticazione: enabled, token, accounts.*, allowBots
• criterio: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• comandi: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• coda eventi: eventQueue.listenerTimeout (budget del listener), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• worker in ingresso: inboundWorker.runTimeoutMs
• risposta/cronologia: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• consegna: textChunkLimit, chunkMode, maxLinesPerMessage
• streaming: streaming (alias legacy: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• media/retry: mediaMaxMb, retry
  • mediaMaxMb limita gli upload Discord in uscita (predefinito: 100MB)
• azioni: actions.*
• presenza: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• funzionalità: threadBindings, bindings[] di livello superiore (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

Sicurezza e operazioni

• Tratta i token dei bot come segreti (DISCORD_BOT_TOKEN preferito negli ambienti supervisionati).
• Concedi i permessi Discord minimi necessari.
• Se il deploy/stato dei comandi è obsoleto, riavvia il gateway e ricontrolla con openclaw channels status --probe.

​

Correlati

• Abbinamento
• Gruppi
• Instradamento del canale
• Sicurezza
• Instradamento multi-agent
• Risoluzione dei problemi
• Comandi slash