Discord

Discord supporta i tag di risposta nell'output dell'agente:

• [[reply_to_current]]
• [[reply_to:<id>]]

Controllati da channels.discord.replyToMode:

• off (predefinito)
• first
• all
• batched

Nota: off disabilita il threading implicito delle risposte. I tag espliciti [[reply_to_*]] vengono comunque rispettati. first collega sempre il riferimento implicito alla risposta nativa al primo messaggio Discord in uscita per il turno. batched collega il riferimento implicito alla risposta nativa di Discord solo quando il turno in ingresso era un batch con debounce di più messaggi. Questo è utile quando vuoi risposte native principalmente per chat ambigue con messaggi a raffica, non per ogni turno con un singolo messaggio.

Gli ID dei messaggi sono esposti nel contesto/nella cronologia, così gli agenti possono indirizzare messaggi specifici.

OpenClaw può trasmettere risposte bozza inviando un messaggio temporaneo e modificandolo man mano che arriva il testo. channels.discord.streaming accetta off | partial | block | progress (predefinito). progress mantiene una bozza di stato modificabile e la aggiorna con l'avanzamento degli strumenti fino alla consegna finale; streamMode è un alias runtime legacy. Esegui openclaw doctor --fix per riscrivere la configurazione persistente usando la chiave canonica.

Imposta channels.discord.streaming.mode su off per disabilitare le modifiche dell'anteprima di Discord. Se lo streaming a blocchi di Discord è abilitato esplicitamente, OpenClaw salta lo stream di anteprima per evitare il doppio streaming.

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

• partial modifica un singolo messaggio di anteprima man mano che arrivano i token.
• block emette blocchi di dimensione bozza (usa draftChunk per regolare dimensioni e punti di interruzione, limitati a textChunkLimit).
• Finali con media, errore e risposta esplicita annullano le modifiche di anteprima in sospeso.
• streaming.preview.toolProgress (predefinito true) controlla se gli aggiornamenti di strumento/avanzamento riutilizzano il messaggio di anteprima.
• streaming.preview.commandText / streaming.progress.commandText controlla il dettaglio di comando/esecuzione nelle righe di avanzamento compatte: raw (predefinito) o status (solo etichetta dello strumento).

Nascondi il testo grezzo di comando/esecuzione mantenendo le righe di avanzamento compatte:

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

Lo streaming di anteprima è solo testo; le risposte con media tornano alla consegna normale. Quando lo streaming block è abilitato esplicitamente, OpenClaw salta lo stream di anteprima per evitare il doppio streaming.

Contesto della cronologia della guild:

• valore predefinito di channels.discord.historyLimit: 20
• fallback: messages.groupChat.historyLimit
• 0 disabilita

Controlli della cronologia DM:

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

Comportamento dei thread:

• I thread Discord vengono instradati come sessioni di canale ed ereditano la configurazione del canale padre, salvo override.
• Le sessioni dei thread ereditano la selezione /model a livello di sessione del canale padre come fallback solo per il modello; le selezioni /model locali al thread hanno comunque la precedenza e la cronologia della trascrizione del padre non viene copiata a meno che l'ereditarietà della trascrizione non sia abilitata.
• channels.discord.thread.inheritParent (predefinito false) fa sì che i nuovi auto-thread vengano inizializzati dalla trascrizione padre. Gli override per account si trovano in channels.discord.accounts.<id>.thread.inheritParent.
• Le reazioni dello strumento messaggi possono risolvere destinazioni DM user:<id>.
• guilds.<guild>.channels.<channel>.requireMention: false viene preservato durante il fallback di attivazione nella fase di risposta.

Gli argomenti dei canali vengono iniettati come contesto non attendibile. Le allowlist regolano chi può attivare l'agente, non costituiscono un confine completo di redazione del contesto supplementare.

Discord può associare un thread a un target di sessione, così i messaggi successivi in quel thread continuano a essere instradati alla stessa sessione (incluse le sessioni dei subagent).

Comandi:

• /focus <target> associa il thread corrente/nuovo a un target di subagent/sessione
• /unfocus rimuove l'associazione del thread corrente
• /agents mostra le esecuzioni attive e lo stato dell'associazione
• /session idle <duration|off> ispeziona/aggiorna l'auto-unfocus per inattività per le associazioni focalizzate
• /session max-age <duration|off> ispeziona/aggiorna l'età massima rigida per le associazioni focalizzate

Configurazione:

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

Note:

• session.threadBindings.* imposta i valori predefiniti globali.
• channels.discord.threadBindings.* sovrascrive il comportamento di Discord.
• spawnSessions controlla la creazione/associazione automatica dei thread per sessions_spawn({ thread: true }) e gli spawn di thread ACP. Predefinito: true.
• defaultSpawnContext controlla il contesto nativo del subagent per gli spawn associati a thread. Predefinito: "fork".
• Le chiavi deprecate spawnSubagentSessions/spawnAcpSessions vengono migrate da openclaw doctor --fix.
• Se le associazioni dei thread sono disabilitate per un account, /focus e le operazioni correlate di associazione dei thread non sono disponibili.

Consulta Sub-agent, Agenti ACP e Riferimento di configurazione.

Per workspace ACP stabili e "sempre attivi", configura associazioni ACP tipizzate di primo livello che puntano a conversazioni Discord.

Percorso di configurazione:

• bindings[] con type: "acp" e match.channel: "discord"

Esempio:

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

Note:

• /acp spawn codex --bind here associa il canale o thread corrente sul posto e mantiene i messaggi futuri sulla stessa sessione ACP. I messaggi del thread ereditano l'associazione del canale padre.
• In un canale o thread associato, /new e /reset reimpostano sul posto la stessa sessione ACP. Le associazioni temporanee dei thread possono sovrascrivere la risoluzione del target mentre sono attive.
• spawnSessions regola la creazione/associazione dei thread figli tramite --thread auto|here.

Consulta Agenti ACP per i dettagli sul comportamento delle associazioni.

Modalità di notifica delle reazioni per guild:

• off
• own (predefinito)
• all
• allowlist (usa guilds.<id>.users)

Gli eventi di reazione vengono trasformati in eventi di sistema e allegati alla sessione Discord instradata.

ackReaction invia un'emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.

Ordine di risoluzione:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• fallback emoji dell'identità dell'agente (agents.list[].identity.emoji, altrimenti "👀")

Note:

• Discord accetta emoji unicode o nomi di emoji personalizzate.
• Usa "" per disabilitare la reazione per un canale o account.

Le scritture di configurazione avviate dal canale sono abilitate per impostazione predefinita.

Questo influisce sui flussi /config set|unset (quando le funzionalità dei comandi sono abilitate).

Disabilita:

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

Instrada il traffico WebSocket del Gateway Discord e le ricerche REST di avvio (ID applicazione + risoluzione allowlist) tramite un proxy HTTP(S) con channels.discord.proxy.

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

Override per account:

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

Abilita la risoluzione PluralKit per mappare i messaggi proxati all'identità del membro di sistema:

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

Note:

• le allowlist possono usare pk:<memberId>
• i nomi visualizzati dei membri vengono confrontati per nome/slug solo quando channels.discord.dangerouslyAllowNameMatching: true
• le ricerche usano l'ID del messaggio originale e sono limitate da una finestra temporale
• se la ricerca non riesce, i messaggi proxati vengono trattati come messaggi bot e scartati a meno che allowBots=true

Usa mentionAliases quando gli agenti hanno bisogno di menzioni in uscita deterministiche per utenti Discord noti. Le chiavi sono handle senza la @ iniziale; i valori sono ID utente Discord. Gli handle sconosciuti, @everyone, @here e le menzioni all'interno di code span Markdown restano invariati.

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

Gli aggiornamenti della presenza vengono applicati quando imposti un campo di stato o attività, oppure quando abiliti la presenza automatica.

Esempio solo stato:

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

Esempio di attività (lo stato personalizzato è il tipo di attività predefinito):

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

Esempio di streaming:

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

Mappa dei tipi di attività:

• 0: Playing
• 1: Streaming (richiede activityUrl)
• 2: Listening
• 3: Watching
• 4: Custom (usa il testo dell'attività come stato; l'emoji è facoltativa)
• 5: Competing

Esempio di presenza automatica (segnale di salute del runtime):

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

La presenza automatica mappa la disponibilità runtime allo stato Discord: healthy => online, degraded o unknown => idle, exhausted o unavailable => dnd. Override di testo facoltativi:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText (supporta il segnaposto {reason})

Discord supporta la gestione delle approvazioni basata su pulsanti nei DM e può facoltativamente pubblicare prompt di approvazione nel canale di origine.

Percorso di configurazione:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (facoltativo; ricorre a commands.ownerAllowFrom quando possibile)
• channels.discord.execApprovals.target (dm | channel | both, predefinito: dm)
• agentFilter, sessionFilter, cleanupAfterResolve

Discord abilita automaticamente le approvazioni exec native quando enabled non è impostato o è "auto" e almeno un approvatore può essere risolto, da execApprovals.approvers o da commands.ownerAllowFrom. Discord non deduce gli approvatori exec da allowFrom del canale, dal legacy dm.allowFrom o dal defaultTo dei messaggi diretti. Imposta enabled: false per disabilitare esplicitamente Discord come client di approvazione nativo.

Per comandi di gruppo sensibili riservati agli owner, come /diagnostics e /export-trajectory, OpenClaw invia privatamente i prompt di approvazione e i risultati finali. Prova prima il DM Discord quando l'owner che invoca il comando dispone di una route owner Discord; se non è disponibile, ricorre alla prima route owner disponibile da commands.ownerAllowFrom, come Telegram.

Quando target è channel o both, il prompt di approvazione è visibile nel canale. Solo gli approvatori risolti possono usare i pulsanti; gli altri utenti ricevono un diniego effimero. I prompt di approvazione includono il testo del comando, quindi abilita la consegna nel canale solo in canali attendibili. Se l'ID del canale non può essere derivato dalla chiave di sessione, OpenClaw ricorre alla consegna tramite DM.

Discord renderizza anche i pulsanti di approvazione condivisi usati da altri canali di chat. L'adapter Discord nativo aggiunge principalmente il routing DM degli approvatori e il fanout sul canale. Quando questi pulsanti sono presenti, sono la UX di approvazione principale; OpenClaw dovrebbe includere un comando manuale /approve solo quando il risultato dello strumento indica che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. Se il runtime di approvazione nativo Discord non è attivo, OpenClaw mantiene visibile il prompt locale deterministico /approve <id> <decision>. Se il runtime è attivo ma una scheda nativa non può essere consegnata a nessun target, OpenClaw invia un avviso di fallback nella stessa chat con il comando /approve esatto dall'approvazione in sospeso.

L'autenticazione Gateway e la risoluzione delle approvazioni seguono il contratto client Gateway condiviso (gli ID plugin: si risolvono tramite plugin.approval.resolve; gli altri ID tramite exec.approval.resolve). Le approvazioni scadono dopo 30 minuti per impostazione predefinita.

Vedi Approvazioni exec.

• abilita Message Content Intent
• abilita Server Members Intent quando dipendi dalla risoluzione di utenti/membri
• riavvia il Gateway dopo aver modificato gli intent

• verifica groupPolicy
• verifica l'allowlist della guild in channels.discord.guilds
• se esiste la mappa channels della guild, sono consentiti solo i canali elencati
• verifica il comportamento di requireMention e i pattern di menzione

Controlli utili:

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

Cause comuni:

• groupPolicy="allowlist" senza allowlist di guild/canale corrispondente
• requireMention configurato nel posto sbagliato (deve trovarsi in channels.discord.guilds o nella voce del canale)
• mittente bloccato dall'allowlist users di guild/canale

Log tipici:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Parametri della coda del gateway Discord:

• account singolo: channels.discord.eventQueue.listenerTimeout
• multi-account: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• questo controlla solo il lavoro del listener del gateway Discord, non la durata del turno dell'agente

Discord non applica un timeout di proprietà del canale ai turni dell'agente in coda. I listener dei messaggi passano il lavoro immediatamente, e le esecuzioni Discord in coda preservano l'ordine per sessione finché il ciclo di vita di sessione/strumento/runtime completa o interrompe il lavoro.

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

OpenClaw recupera i metadati Discord /gateway/bot prima di connettersi. Gli errori transitori ripiegano sull'URL gateway predefinito di Discord e vengono limitati nei log.

Opzioni di timeout dei metadati:

• account singolo: channels.discord.gatewayInfoTimeoutMs
• più account: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• fallback env quando la configurazione non è impostata: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• predefinito: 30000 (30 secondi), massimo: 120000

OpenClaw attende l'evento READY del gateway Discord durante l'avvio e dopo le riconnessioni di runtime. Le configurazioni con più account e avvio scaglionato possono richiedere una finestra READY di avvio più lunga rispetto a quella predefinita.

Opzioni di timeout READY:

• avvio account singolo: channels.discord.gatewayReadyTimeoutMs
• avvio più account: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• fallback env di avvio quando la configurazione non è impostata: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• predefinito di avvio: 15000 (15 secondi), massimo: 120000
• runtime account singolo: channels.discord.gatewayRuntimeReadyTimeoutMs
• runtime più account: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• fallback env di runtime quando la configurazione non è impostata: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• predefinito di runtime: 30000 (30 secondi), massimo: 120000

I controlli dei permessi di channels status --probe funzionano solo per gli ID numerici dei canali.

Se usi chiavi slug, la corrispondenza di runtime può comunque funzionare, ma il probe non può verificare completamente i permessi.

• DM disabilitati: channels.discord.dm.enabled=false
• criterio DM disabilitato: channels.discord.dmPolicy="disabled" (legacy: channels.discord.dm.policy)
• in attesa dell'approvazione dell'abbinamento in modalità pairing

Per impostazione predefinita, i messaggi scritti dai bot vengono ignorati.

Se imposti channels.discord.allowBots=true, usa regole rigorose di menzione e allowlist per evitare comportamenti di loop. Preferisci channels.discord.allowBots="mentions" per accettare solo i messaggi dei bot che menzionano il bot.

{
channels: {
discord: {
  accounts: {
    mantis: {
      // Mantis listens to other bots only when they mention her.
      allowBots: "mentions",
    },
    molty: {
      // Molty listens to all bot-authored Discord messages.
      allowBots: true,
      mentionAliases: {
        // Lets Molty write "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• mantieni OpenClaw aggiornato (openclaw update) in modo che sia presente la logica di recupero della ricezione vocale Discord
• conferma channels.discord.voice.daveEncryption=true (predefinito)
• parti da channels.discord.voice.decryptionFailureTolerance=24 (predefinito upstream) e regola solo se necessario
• controlla nei log:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• se gli errori continuano dopo il rientro automatico, raccogli i log e confrontali con la cronologia upstream della ricezione DAVE in discord.js #11419 e discord.js #11449