Discord

Pronto para DMs e canais de guilda pelo Gateway oficial do Discord.

Configuração rápida

Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu servidor e emparelhá-lo com o OpenClaw. Recomendamos adicionar seu bot ao seu próprio servidor privado. Se você ainda não tiver um, crie um primeiro (escolha Create My Own > For me and my friends).

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

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

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

Recomendado: configure um workspace de guilda

Depois que as DMs estiverem funcionando, você pode configurar seu servidor Discord como um workspace completo, onde cada canal recebe sua própria sessão de agente com seu próprio contexto. Isso é recomendado para servidores privados em que há apenas você e seu bot.

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

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

Agora crie alguns canais no seu servidor Discord e comece a conversar. Seu agente consegue ver o nome do canal, e cada canal recebe sua própria sessão isolada — então você pode configurar #coding, #home, #research ou o que se ajustar ao seu fluxo de trabalho.

Modelo de runtime

• Gateway é dono da conexão do Discord.
• O roteamento de respostas é determinístico: respostas de entrada do Discord voltam para o Discord.
• Metadados de guild/canal do Discord são adicionados ao prompt do modelo como contexto não confiável, não como um prefixo de resposta visível ao usuário. Se um modelo copiar esse envelope de volta, o OpenClaw remove os metadados copiados das respostas de saída e do contexto de reprodução futuro.
• Por padrão (session.dmScope=main), conversas diretas compartilham a sessão principal do agente (agent:main:main).
• Canais de guild são chaves de sessão isoladas (agent:<agentId>:discord:channel:<channelId>).
• DMs em grupo são ignoradas por padrão (channels.discord.dm.groupEnabled=false).
• Comandos de barra nativos são executados em sessões de comando isoladas (agent:<agentId>:discord:slash:<userId>), enquanto ainda carregam CommandTargetSessionKey para a sessão de conversa roteada.
• A entrega de anúncio de Cron/Heartbeat somente texto para o Discord usa a resposta final visível ao assistente uma vez. Payloads de mídia e componentes estruturados continuam em várias mensagens quando o agente emite vários payloads entregáveis.

Canais de fórum

Canais de fórum e mídia do Discord aceitam apenas publicações em threads. O OpenClaw oferece suporte a duas formas de criá-las:

• Envie uma mensagem ao pai do fórum (channel:<forumId>) para criar uma thread automaticamente. O título da thread usa a primeira linha não vazia da sua mensagem.
• Use openclaw message thread create para criar uma thread diretamente. Não passe --message-id para canais de fórum.

Exemplo: enviar ao pai do fórum para criar uma thread

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

Exemplo: criar explicitamente uma thread de fórum

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

Pais de fórum não aceitam componentes do Discord. Se você precisar de componentes, envie para a própria thread (channel:<threadId>).

Componentes interativos

O OpenClaw oferece suporte a contêineres de componentes v2 do Discord para mensagens de agente. Use a ferramenta de mensagem com um payload components. Os resultados de interação são roteados de volta ao agente como mensagens de entrada normais e seguem as configurações existentes de replyToMode do Discord.

Blocos compatíveis:

• text, section, separator, actions, media-gallery, file
• Linhas de ação permitem até 5 botões ou um único menu de seleção
• Tipos de seleção: string, user, role, mentionable, channel

Por padrão, componentes são de uso único. Defina components.reusable=true para permitir que botões, seleções e formulários sejam usados várias vezes até expirarem.

Para restringir quem pode clicar em um botão, defina allowedUsers nesse botão (IDs de usuário do Discord, tags ou *). Quando configurado, usuários sem correspondência recebem uma negação efêmera.

Callbacks de componentes expiram após 30 minutos por padrão. Defina channels.discord.agentComponents.ttlMs para alterar esse tempo de vida do registro de callbacks para a conta padrão do Discord, ou channels.discord.accounts.<accountId>.agentComponents.ttlMs para sobrescrever uma conta em uma configuração com várias contas. O valor é em milissegundos, deve ser um inteiro positivo e é limitado a 86400000 (24 horas). TTLs mais longos são úteis para fluxos de trabalho de revisão ou aprovação que precisam que botões permaneçam utilizáveis, mas também ampliam a janela em que uma mensagem antiga do Discord ainda pode acionar uma ação. Prefira o menor TTL que atenda ao fluxo de trabalho e mantenha o padrão quando callbacks obsoletos seriam surpreendentes.

Os comandos de barra /model e /models abrem um seletor de modelo interativo com menus suspensos de provedor, modelo e runtime compatível, além de uma etapa de envio. /models add está obsoleto e agora retorna uma mensagem de obsolescência em vez de registrar modelos pelo chat. A resposta do seletor é efêmera e somente o usuário que invocou pode usá-la. Menus de seleção do Discord são limitados a 25 opções, então adicione entradas provider/* a agents.defaults.models quando quiser que o seletor mostre modelos descobertos dinamicamente apenas para provedores selecionados, como openai ou vllm.

Anexos de arquivo:

• Blocos file devem apontar para uma referência de anexo (attachment://<filename>)
• Forneça o anexo via media/path/filePath (arquivo único); use media-gallery para vários arquivos
• Use filename para sobrescrever o nome de upload quando ele deve corresponder à referência de anexo

Formulários modais:

• Adicione components.modal com até 5 campos
• Tipos de campo: text, checkbox, radio, select, role-select, user-select
• O OpenClaw adiciona um botão de acionamento automaticamente

Exemplo:

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

Controle de acesso e roteamento

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

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

Roteamento de agentes baseado em função

Use bindings[].match.roles para rotear membros de guildas do Discord para agentes diferentes por ID de função. Associações baseadas em função aceitam apenas IDs de função e são avaliadas depois de associações de par ou par pai e antes de associações somente de guilda. Se uma associação também definir outros campos de correspondência (por exemplo peer + guildId + roles), todos os campos configurados devem corresponder.

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

Comandos nativos e autenticação de comandos

• commands.native usa "auto" como padrão e é habilitado para Discord.
• Substituição por canal: channels.discord.commands.native.
• commands.native=false ignora o registro e a limpeza de comandos de barra do Discord durante a inicialização. Comandos registrados anteriormente podem permanecer visíveis no Discord até que você os remova do app do Discord.
• A autenticação de comandos nativos usa as mesmas listas de permissão/políticas do Discord que o tratamento normal de mensagens.
• Os comandos ainda podem ficar visíveis na interface do Discord para usuários que não estão autorizados; a execução ainda aplica a autenticação do OpenClaw e retorna "não autorizado".

Consulte Comandos de barra para o catálogo e o comportamento dos comandos.

Configurações padrão de comandos de barra:

• ephemeral: true

Detalhes do recurso

{channels: {discord: {  suppressEmbeds: false,},},}

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

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

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

{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: {  mentionAliases: {    Vladislava: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

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

Ferramentas e controles de ação

Ações de mensagem do Discord incluem mensagens, administração de canal, moderação, presença e ações de metadados.

Exemplos principais:

• mensagens: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reações: react, reactions, emojiList
• moderação: timeout, kick, ban
• presença: setPresence

A ação event-create aceita um parâmetro opcional image (URL ou caminho de arquivo local) para definir a imagem de capa do evento agendado.

Controles de ação ficam em channels.discord.actions.*.

Comportamento padrão dos controles:

UI de componentes v2

O OpenClaw usa componentes v2 do Discord para aprovações de exec e marcadores entre contextos. Ações de mensagem do Discord também podem aceitar components para UI personalizada (avançado; requer construir um payload de componente via a ferramenta discord), enquanto embeds legados continuam disponíveis, mas não são recomendados.

• channels.discord.ui.components.accentColor define a cor de destaque usada pelos contêineres de componentes do Discord (hex).
• Defina por conta com channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs controla por quanto tempo callbacks de componentes do Discord enviados permanecem registrados (padrão 1800000, máximo 86400000). Defina por conta com channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds são ignorados quando componentes v2 estão presentes.
• Pré-visualizações de URL simples são suprimidas por padrão. Defina suppressEmbeds: false em uma ação de mensagem quando um único link de saída deve ser expandido.

Exemplo:

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

Voz

O Discord tem duas superfícies de voz distintas: canais de voz em tempo real (conversas contínuas) e anexos de mensagem de voz (o formato de pré-visualização de forma de onda). O Gateway oferece suporte a ambos.

Canais de voz

Checklist de configuração:

1. Ative Message Content Intent no Discord Developer Portal.
2. Ative Server Members Intent quando listas de permissão por função/usuário forem usadas.
3. Convide o bot com os escopos bot e applications.commands.
4. Conceda Connect, Speak, Send Messages e Read Message History no canal de voz de destino.
5. Ative comandos nativos (commands.native ou channels.discord.commands.native).
6. Configure channels.discord.voice.

Use /vc join|leave|status para controlar sessões. O comando usa o agente padrão da conta e segue as mesmas regras de lista de permissão e política de grupo de outros comandos do Discord.

/vc join channel:<voice-channel-id>/vc status/vc leave

Para inspecionar as permissões efetivas do bot antes de entrar, execute:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

Exemplo de entrada automática:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

Observações:

• voice.tts substitui messages.tts apenas para reprodução de voz stt-tts. Modos em tempo real usam voice.realtime.speakerVoice.
• voice.mode controla o caminho da conversa. O padrão é agent-proxy: um front-end de voz em tempo real gerencia o tempo dos turnos, interrupção e reprodução, delega o trabalho substantivo ao agente OpenClaw roteado por meio de openclaw_agent_consult e trata o resultado como um prompt digitado do Discord daquele falante. stt-tts mantém o fluxo em lote mais antigo de STT mais TTS. bidi permite que o modelo em tempo real converse diretamente enquanto expõe openclaw_agent_consult para o cérebro do OpenClaw.
• voice.agentSession controla qual conversa do OpenClaw recebe turnos de voz. Deixe sem definir para a sessão própria do canal de voz, ou defina { mode: "target", target: "channel:<text-channel-id>" } para fazer o canal de voz atuar como a extensão de microfone/alto-falante de uma sessão existente de canal de texto do Discord, como #maintainers.
• voice.model substitui o cérebro do agente OpenClaw para respostas de voz do Discord e consultas em tempo real. Deixe sem definir para herdar o modelo do agente roteado. Ele é separado de voice.realtime.model.
• voice.followUsers permite que o bot entre, se mova e saia da voz do Discord com usuários selecionados. Veja Seguir usuários na voz para regras de comportamento e exemplos.
• agent-proxy roteia fala por discord-voice, que preserva a autorização normal de proprietário/ferramenta para o falante e a sessão de destino, mas oculta a ferramenta tts do agente porque a voz do Discord controla a reprodução. Por padrão, agent-proxy dá à consulta acesso total a ferramentas equivalente ao proprietário para falantes proprietários (voice.realtime.toolPolicy: "owner") e prefere fortemente consultar o agente OpenClaw antes de respostas substantivas (voice.realtime.consultPolicy: "always"). Nesse modo padrão always, a camada em tempo real não fala automaticamente preenchimento antes da resposta da consulta; ela captura e transcreve a fala, depois fala a resposta roteada do OpenClaw. Se várias respostas de consulta forçada terminarem enquanto o Discord ainda estiver reproduzindo a primeira resposta, respostas posteriores de fala exata serão enfileiradas até a reprodução ficar ociosa, em vez de substituir a fala no meio da frase.
• No modo stt-tts, o STT usa tools.media.audio; voice.model não afeta a transcrição.
• Em modos em tempo real, voice.realtime.provider, voice.realtime.model e voice.realtime.speakerVoice configuram a sessão de áudio em tempo real. Para OpenAI Realtime 2 mais o cérebro Codex, use voice.realtime.model: "gpt-realtime-2" e voice.model: "openai/gpt-5.5".
• Modos de voz em tempo real incluem pequenos arquivos de perfil IDENTITY.md, USER.md e SOUL.md nas instruções do provedor em tempo real por padrão, para que turnos diretos rápidos mantenham a mesma identidade, base do usuário e persona do agente OpenClaw roteado. Defina voice.realtime.bootstrapContextFiles como um subconjunto para personalizar isso, ou [] para desativar. Os arquivos de inicialização em tempo real compatíveis são limitados a esses arquivos de perfil; AGENTS.md permanece no contexto normal do agente. O contexto de perfil injetado não substitui openclaw_agent_consult para trabalho no workspace, fatos atuais, busca de memória ou ações apoiadas por ferramentas.
• No modo em tempo real agent-proxy da OpenAI, defina voice.realtime.requireWakeName: true para manter a voz em tempo real do Discord silenciosa até que uma transcrição comece ou termine com um nome de ativação. Nomes de ativação configurados devem ter uma ou duas palavras. Se voice.realtime.wakeNames não estiver definido, o OpenClaw usa o name do agente roteado mais OpenClaw, recorrendo ao id do agente mais OpenClaw. O bloqueio por nome de ativação desativa a resposta automática do provedor em tempo real, roteia turnos aceitos pelo caminho de consulta do agente OpenClaw e dá uma breve confirmação falada quando um nome de ativação inicial é reconhecido pela transcrição parcial antes da transcrição final chegar.
• O provedor em tempo real da OpenAI aceita nomes de eventos atuais do Realtime 2 e aliases legados compatíveis com Codex para eventos de áudio de saída e transcrição, para que snapshots compatíveis do provedor possam divergir sem descartar áudio do assistente.
• voice.realtime.bargeIn controla se eventos de início de fala no Discord interrompem a reprodução ativa em tempo real. Se não estiver definido, segue a configuração de interrupção de áudio de entrada do provedor em tempo real.
• voice.realtime.minBargeInAudioEndMs controla a duração mínima de reprodução do assistente antes que uma interrupção em tempo real da OpenAI trunque o áudio. Padrão: 250. Defina 0 para interrupção imediata em salas com pouco eco, ou aumente para configurações de alto-falantes com muito eco.
• Para uma voz da OpenAI na reprodução do Discord, defina voice.tts.provider: "openai" e escolha uma voz de Text-to-speech em voice.tts.providers.openai.speakerVoice. cedar é uma boa escolha com sonoridade masculina no modelo TTS atual da OpenAI.
• Substituições de systemPrompt por canal do Discord se aplicam a turnos de transcrição de voz desse canal de voz.
• Turnos de transcrição de voz derivam o status de proprietário de allowFrom (ou dm.allowFrom) do Discord para comandos protegidos por proprietário e ações de canal. A visibilidade das ferramentas do agente segue a política de ferramentas configurada para a sessão roteada.
• Voz do Discord é opcional para configurações somente texto; defina channels.discord.voice.enabled=true (ou mantenha um bloco channels.discord.voice existente) para habilitar comandos /vc, o runtime de voz e a intent de Gateway GuildVoiceStates.
• channels.discord.intents.voiceStates pode substituir explicitamente a assinatura de intent de estado de voz. Deixe sem definir para que a intent siga a ativação efetiva de voz.
• Se voice.autoJoin tiver várias entradas para o mesmo servidor, o OpenClaw entra no último canal configurado para esse servidor.
• voice.allowedChannels é uma lista opcional de permissão de residência. Deixe sem definir para permitir /vc join em qualquer canal de voz autorizado do Discord. Quando definida, /vc join, entrada automática na inicialização e movimentos de estado de voz do bot ficam restritos às entradas { guildId, channelId } listadas. Defina como um array vazio para negar todas as entradas em voz do Discord. Se o Discord mover o bot para fora da lista de permissão, o OpenClaw sai desse canal e retorna ao destino configurado de entrada automática quando houver um disponível.
• voice.daveEncryption e voice.decryptionFailureTolerance são repassados às opções de entrada de @discordjs/voice.
• Os padrões de @discordjs/voice são daveEncryption=true e decryptionFailureTolerance=24 se não forem definidos.
• O OpenClaw usa o codec libopus-wasm incluído para recebimento de voz do Discord e reprodução PCM bruta em tempo real. Ele inclui uma build WebAssembly fixada da libopus e não exige addons opus nativos.
• voice.connectTimeoutMs controla a espera inicial por Ready de @discordjs/voice para tentativas de /vc join e entrada automática. Padrão: 30000.
• voice.reconnectGraceMs controla por quanto tempo o OpenClaw espera que uma sessão de voz desconectada comece a se reconectar antes de destruí-la. Padrão: 15000.
• No modo stt-tts, a reprodução de voz não para só porque outro usuário começa a falar. Para evitar loops de feedback, o OpenClaw ignora nova captura de voz enquanto o TTS está reproduzindo; fale depois que a reprodução terminar para o próximo turno. Modos em tempo real encaminham inícios de fala como sinais de interrupção ao provedor em tempo real.
• Em modos em tempo real, eco de alto-falantes em um microfone aberto pode parecer interrupção e interromper a reprodução. Para salas do Discord com muito eco, defina voice.realtime.providers.openai.interruptResponseOnInputAudio: false para impedir que a OpenAI interrompa automaticamente com áudio de entrada. Adicione voice.realtime.bargeIn: true se você ainda quiser que eventos de início de fala do Discord interrompam a reprodução ativa. A ponte em tempo real da OpenAI ignora truncamentos de reprodução menores que voice.realtime.minBargeInAudioEndMs como provável eco/ruído e os registra como ignorados em vez de limpar a reprodução do Discord.
• voice.captureSilenceGraceMs controla por quanto tempo o OpenClaw espera depois que o Discord informa que um falante parou antes de finalizar esse segmento de áudio para STT. Padrão: 2000; aumente isso se o Discord dividir pausas normais em transcrições parciais picotadas.
• Quando ElevenLabs é o provedor TTS selecionado, a reprodução de voz do Discord usa TTS por streaming e começa a partir do stream de resposta do provedor. Provedores sem suporte a streaming recorrem ao caminho de arquivo temporário sintetizado.
• O OpenClaw também monitora falhas de descriptografia de recebimento e se recupera automaticamente saindo e entrando novamente no canal de voz após falhas repetidas em uma janela curta.
• Se os logs de recebimento mostrarem repetidamente DecryptionFailed(UnencryptedWhenPassthroughDisabled) após a atualização, colete um relatório de dependências e logs. A linha incluída de @discordjs/voice contém a correção de padding upstream do PR #11449 do discord.js, que fechou a issue #11419 do discord.js.
• Eventos de recebimento The operation was aborted são esperados quando o OpenClaw finaliza um segmento capturado de falante; são diagnósticos detalhados, não avisos.
• Logs detalhados de voz do Discord incluem uma prévia limitada de uma linha da transcrição STT para cada segmento de falante aceito, para que a depuração mostre tanto o lado do usuário quanto o lado da resposta do agente sem despejar texto de transcrição ilimitado.
• No modo agent-proxy, o fallback de consulta forçada ignora fragmentos de transcrição provavelmente incompletos, como texto terminando em ... ou um conector final como and, além de encerramentos obviamente não acionáveis como “já volto” ou “tchau”. Os logs mostram forced agent consult skipped reason=... quando isso impede uma resposta enfileirada obsoleta.

Seguir usuários na voz

Use voice.followUsers quando você quiser que o bot de voz do Discord fique com um ou mais usuários conhecidos do Discord em vez de entrar em um canal fixo na inicialização ou esperar por /vc join.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

Comportamento:

• followUsers aceita IDs brutos de usuário do Discord e valores discord:<id>. O OpenClaw normaliza as duas formas antes de corresponder eventos de estado de voz.
• followUsersEnabled usa true como padrão quando followUsers está configurado. Defina como false para manter a lista salva, mas interromper o acompanhamento automático de voz.
• Quando um usuário seguido entra em um canal de voz permitido, o OpenClaw entra nesse canal. Quando o usuário se move, o OpenClaw se move com ele. Quando o usuário seguido ativo se desconecta, o OpenClaw sai.
• Se vários usuários seguidos estiverem no mesmo servidor e o usuário seguido ativo sair, o OpenClaw se move para o canal de outro usuário seguido rastreado antes de sair do servidor. Se vários usuários seguidos se moverem ao mesmo tempo, o evento de estado de voz observado mais recente vence.
• allowedChannels ainda se aplica. Um usuário seguido em um canal não permitido é ignorado, e uma sessão controlada por acompanhamento se move para outro usuário seguido ou sai.
• O OpenClaw reconcilia eventos de estado de voz perdidos na inicialização e em um intervalo limitado. A reconciliação amostra servidores configurados e limita buscas REST por execução, então listas followUsers muito grandes podem levar mais de um intervalo para convergir.
• Se o Discord ou um administrador mover o bot enquanto ele está seguindo um usuário, o OpenClaw reconstrói a sessão de voz e preserva a propriedade de acompanhamento quando o destino é permitido. Se o bot for movido para fora de allowedChannels, o OpenClaw sai e retorna ao destino configurado quando houver um.
• A recuperação de recebimento DAVE pode sair e entrar novamente no mesmo canal após falhas repetidas de descriptografia. Sessões controladas por acompanhamento mantêm sua propriedade de acompanhamento por esse caminho de recuperação, então uma desconexão posterior do usuário seguido ainda faz o canal ser deixado.

Escolha entre os modos de entrada:

• Use followUsers para configurações pessoais ou de operador em que o bot deve estar automaticamente na voz quando você estiver.
• Use autoJoin para bots de sala fixa que devem estar presentes mesmo quando nenhum usuário rastreado estiver na voz.
• Use /vc join para entradas pontuais ou salas em que presença automática na voz seria inesperada.

Codec de voz do Discord:

• Os logs de recebimento de voz mostram discord voice: opus decoder: libopus-wasm.
• A reprodução em tempo real codifica PCM estéreo bruto de 48 kHz para Opus com o mesmo pacote libopus-wasm incluído antes de entregar os pacotes ao @discordjs/voice.
• A reprodução de arquivos e fluxos de provedor transcodifica para PCM estéreo bruto de 48 kHz com ffmpeg e, em seguida, usa libopus-wasm para o fluxo de pacotes Opus enviado ao Discord.

Pipeline de STT mais TTS:

• A captura PCM do Discord é convertida em um arquivo temporário WAV.
• tools.media.audio lida com STT, por exemplo openai/gpt-4o-mini-transcribe.
• A transcrição é enviada pelo ingresso e roteamento do Discord enquanto o LLM de resposta é executado com uma política de saída por voz que oculta a ferramenta tts do agente e solicita texto retornado, porque a voz do Discord controla a reprodução final de TTS.
• voice.model, quando definido, substitui apenas o LLM de resposta para esta rodada de canal de voz.
• voice.tts é mesclado sobre messages.tts; provedores compatíveis com streaming alimentam o player diretamente, caso contrário o arquivo de áudio resultante é reproduzido no canal conectado.

Exemplo padrão de sessão de canal de voz agent-proxy:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

Sem um bloco voice.agentSession, cada canal de voz recebe sua própria sessão roteada do OpenClaw. Por exemplo, /vc join channel:234567890123456789 conversa com a sessão desse canal de voz do Discord. O modelo em tempo real é apenas a interface de voz; solicitações substantivas são entregues ao agente OpenClaw configurado. Se o modelo em tempo real produzir uma transcrição final sem chamar a ferramenta de consulta, o OpenClaw força a consulta como fallback para que o padrão ainda se comporte como falar com o agente.

Exemplo legado de STT mais TTS:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

Exemplo bidi em tempo real:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Voz como uma extensão de uma sessão de canal existente do Discord:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.5",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

No modo agent-proxy, o bot entra no canal de voz configurado, mas as rodadas do agente OpenClaw usam a sessão roteada normal e o agente do canal de destino. A sessão de voz em tempo real fala o resultado retornado de volta no canal de voz. O agente supervisor ainda pode usar ferramentas normais de mensagem de acordo com sua política de ferramentas, incluindo enviar uma mensagem separada no Discord se essa for a ação correta.

Enquanto uma execução delegada do OpenClaw estiver ativa, novas transcrições de voz do Discord são tratadas como controle de execução ao vivo antes de iniciar outra rodada do agente. Frases como "status", "cancel that", "use the smaller fix" ou "when you're done also check tests" são classificadas como entrada de status, cancelamento, direcionamento ou acompanhamento para a sessão ativa. Resultados de status, cancelamento, direcionamento aceito e acompanhamento são falados de volta no canal de voz para que quem chamou saiba se o OpenClaw lidou com a solicitação.

Formas de destino úteis:

• target: "channel:123456789012345678" é roteado por meio de uma sessão de canal de texto do Discord.
• target: "123456789012345678" é tratado como um alvo de canal.
• target: "dm:123456789012345678" ou target: "user:123456789012345678" é roteado por meio dessa sessão de mensagem direta.

Exemplo OpenAI Realtime com muito eco:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Use isto quando o modelo ouvir sua própria reprodução do Discord por um microfone aberto, mas você ainda quiser interrompê-lo falando. O OpenClaw impede que o OpenAI interrompa automaticamente com áudio de entrada bruto, enquanto bargeIn: true permite que eventos de início de fala do Discord e áudio de falante já ativo cancelem respostas realtime ativas antes que o próximo turno capturado chegue ao OpenAI. Sinais de interrupção muito iniciais com audioEndMs abaixo de minBargeInAudioEndMs são tratados como provável eco/ruído e ignorados para que o modelo não seja cortado no primeiro quadro de reprodução.

Logs de voz esperados:

• Ao entrar: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Ao iniciar realtime: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Em áudio de falante: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... e discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Em fala antiga ignorada: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... ou reason=non-actionable-closing ...
• Na conclusão da resposta realtime: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Ao parar/redefinir a reprodução: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Em consulta realtime: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Em resposta do agente: discord voice: agent turn answer ...
• Em fala exata enfileirada: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., seguido por discord voice: realtime exact speech dequeued reason=player-idle ...
• Na detecção de barge-in: discord voice: realtime barge-in detected source=speaker-start ... ou discord voice: realtime barge-in detected source=active-speaker-audio ..., seguido por discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Na interrupção realtime: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, seguido por discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... ou discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Em eco/ruído ignorado: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Com barge-in desativado: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Em reprodução ociosa: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Para depurar áudio cortado, leia os logs de voz realtime como uma linha do tempo:

1. realtime audio playback started significa que o Discord começou a reproduzir áudio do assistente. A ponte começa a contar blocos de saída do assistente, bytes PCM do Discord, bytes realtime do provedor e duração de áudio sintetizado a partir desse ponto.
2. realtime speaker turn opened marca um falante do Discord se tornando ativo. Se a reprodução já estiver ativa e bargeIn estiver habilitado, isso pode ser seguido por barge-in detected source=speaker-start.
3. realtime input audio started marca o primeiro quadro de áudio real recebido para esse turno de falante. outputActive=true ou um outputAudioMs diferente de zero aqui significa que o microfone está enviando entrada enquanto a reprodução do assistente ainda está ativa.
4. barge-in detected source=active-speaker-audio significa que o OpenClaw viu áudio de falante ao vivo enquanto a reprodução do assistente estava ativa. Isso é útil para distinguir uma interrupção real de um evento de início de fala do Discord sem áudio útil.
5. barge-in requested reason=... significa que o OpenClaw pediu ao provedor realtime para cancelar ou truncar a resposta ativa. Ele inclui outputAudioMs, outputActive e playbackChunks para que você possa ver quanto áudio do assistente realmente havia sido reproduzido antes da interrupção.
6. realtime audio playback stopped reason=... é o ponto local de redefinição da reprodução do Discord. O motivo diz quem parou a reprodução: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close ou session-close.
7. realtime speaker turn closed resume o turno de entrada capturado. chunks=0 ou hasAudio=false significa que o turno de falante abriu, mas nenhum áudio utilizável chegou à ponte realtime. interruptedPlayback=true significa que esse turno de entrada se sobrepôs à saída do assistente e acionou a lógica de barge-in.

Campos úteis:

• outputAudioMs: duração do áudio do assistente gerada pelo provedor realtime antes da linha de log.
• audioMs: duração do áudio do assistente que o OpenClaw contou antes de a reprodução parar.
• elapsedMs: tempo de relógio decorrido entre abrir e fechar o fluxo de reprodução ou o turno de falante.
• discordBytes: bytes PCM estéreo de 48 kHz enviados para ou recebidos da voz do Discord.
• realtimeBytes: bytes PCM no formato do provedor enviados para ou recebidos do provedor realtime.
• playbackChunks: blocos de áudio do assistente encaminhados ao Discord para a resposta ativa.
• sinceLastAudioMs: intervalo entre o último quadro de áudio de falante capturado e o fechamento do turno de falante.

Padrões comuns:

• Corte imediato com source=active-speaker-audio, outputAudioMs pequeno e o mesmo usuário por perto geralmente indica eco do alto-falante entrando no microfone. Aumente voice.realtime.minBargeInAudioEndMs, reduza o volume do alto-falante, use fones de ouvido ou defina voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start seguido por speaker turn closed ... hasAudio=false significa que o Discord informou um início de fala, mas nenhum áudio chegou ao OpenClaw. Isso pode ser um evento transitório de voz do Discord, comportamento de gate de ruído ou um cliente acionando brevemente o microfone.
• audio playback stopped reason=stream-close sem um barge-in próximo ou provider-clear-audio significa que o fluxo local de reprodução do Discord terminou inesperadamente. Verifique os logs anteriores do provedor e do player do Discord.
• capture ignored during playback (barge-in disabled) significa que o OpenClaw descartou intencionalmente a entrada enquanto o áudio do assistente estava ativo. Habilite voice.realtime.bargeIn se quiser que a fala interrompa a reprodução.
• barge-in ignored ... outputActive=false significa que o VAD do Discord ou do provedor informou fala, mas o OpenClaw não tinha reprodução ativa para interromper. Isso não deve cortar o áudio.

As credenciais são resolvidas por componente: autenticação da rota LLM para voice.model, autenticação STT para tools.media.audio, autenticação TTS para messages.tts/voice.tts e autenticação do provedor realtime para voice.realtime.providers ou a configuração normal de autenticação do provedor.

Mensagens de voz

Mensagens de voz do Discord mostram uma prévia de forma de onda e exigem áudio OGG/Opus. O OpenClaw gera a forma de onda automaticamente, mas precisa de ffmpeg e ffprobe no host do gateway para inspecionar e converter.

• Forneça um caminho de arquivo local (URLs são rejeitadas).
• Omita conteúdo de texto (o Discord rejeita texto + mensagem de voz no mesmo payload).
• Qualquer formato de áudio é aceito; o OpenClaw converte para OGG/Opus conforme necessário.

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

Solução de problemas

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

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

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  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 a Mantis Discord mention with the configured user id.        Mantis: "MANTIS_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Referência de configuração

Referência principal: Referência de configuração - Discord.

Segurança e operações

• Trate tokens de bot como segredos (DISCORD_BOT_TOKEN é preferido em ambientes supervisionados).
• Conceda permissões de menor privilégio no Discord.
• Se o deploy/estado de comandos estiver desatualizado, reinicie o gateway e verifique novamente com openclaw channels status --probe.

Relacionado