Discord

​

Configuração rápida

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" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw 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 discord
openclaw pairing approve discord <CODE>

​

Recomendação: configurar um espaço de trabalho no servidor

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

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

​

Modelo de runtime

• O Gateway gerencia a conexão com o Discord.
• O roteamento das respostas é determinístico: as respostas de entradas do Discord retornam ao Discord.
• Os metadados do servidor/canal do Discord são adicionados ao prompt do modelo como contexto não confiável, e não como um prefixo de resposta visível ao usuário. Se um modelo copiar esse envelope na resposta, o OpenClaw removerá os metadados copiados das respostas de saída e do contexto de reprodução futuro.
• Por padrão (session.dmScope=main), os chats diretos compartilham a sessão principal do agente (agent:main:main).
• Os canais do servidor usam chaves de sessão isoladas (agent:<agentId>:discord:channel:<channelId>).
• As DMs em grupo são ignoradas por padrão (channels.discord.dm.groupEnabled=false).
• Os comandos de barra nativos são executados em sessões de comando isoladas (agent:<agentId>:discord:slash:<userId>), mas ainda carregam CommandTargetSessionKey para a sessão de conversa roteada.
• A entrega de anúncios de Cron/Heartbeat somente em texto ao Discord é condensada na resposta final visível do assistente, enviada uma única vez. As cargas de mídia e de componentes estruturados continuam usando várias mensagens quando o agente emite várias cargas entregáveis.

​

Canais de fórum

• Envie uma mensagem para o canal pai do fórum (channel:<forumId>) para criar automaticamente uma thread. O título da thread é a primeira linha não vazia da mensagem (truncada para o limite de 100 caracteres do Discord para nomes de threads).
• Use openclaw message thread create para criar uma thread diretamente. Não passe --message-id para canais de fórum.

openclaw message send --channel discord --target channel:<forumId> \
  --message "Título do tópico\nCorpo da publicação"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Título do tópico" --message "Corpo da publicação"

​

Componentes interativos

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

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

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

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Texto alternativo opcional",
  components: {
    reusable: true,
    text: "Escolha um caminho",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Aprovar",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Recusar", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Escolha uma opção",
          options: [
            { label: "Opção A", value: "a" },
            { label: "Opção B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Detalhes",
      triggerLabel: "Abrir formulário",
      fields: [
        { type: "text", label: "Solicitante" },
        {
          type: "select",
          label: "Prioridade",
          options: [
            { label: "Baixa", value: "low" },
            { label: "Alta", 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: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

Roteamento de agentes baseado em funções

{
  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" por padrão e está habilitado para o Discord.
• Substituição por canal: channels.discord.commands.native.
• commands.native=false ignora o registro e a limpeza dos comandos de barra do Discord durante a inicialização. Comandos registrados anteriormente podem permanecer visíveis no Discord até que você os remova do aplicativo do Discord.
• A autenticação de comandos nativos usa as mesmas listas de permissões/políticas do Discord que o processamento normal de mensagens.
• Os comandos ainda podem ficar visíveis na interface do Discord para usuários não autorizados; a execução aplica a autenticação do OpenClaw e responde “não autorizado”.
• Configurações padrão dos comandos de barra: ephemeral: true (channels.discord.slashCommand.ephemeral).

​

Detalhes dos recursos

{
  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_...", // opcional; necessário para sistemas privados
      },
    },
  },
}

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

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

{
  channels: {
    discord: {
      activity: "Tempo de concentração",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Programação ao vivo",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

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

​

Ferramentas e controles de ações

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

​

Interface de usuário dos componentes v2

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

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

​

Voz

​

Canais de voz

1. Ative Message Content Intent no Discord Developer Portal.
2. Ative Server Members Intent quando forem usadas listas de permissões de funções/usuários.
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 os comandos nativos (commands.native ou channels.discord.commands.native).
6. Configure channels.discord.voice.

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

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

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.6-sol",
        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.1",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

• A voz do Discord é opcional para configurações somente de texto; defina channels.discord.voice.enabled=true (ou mantenha um bloco channels.discord.voice existente) para habilitar os comandos /vc, o runtime de voz e a intenção de Gateway GuildVoiceStates. channels.discord.intents.voiceStates pode substituir explicitamente a assinatura da intenção; deixe essa opção não definida para seguir a habilitação efetiva da voz.
• voice.mode controla o fluxo da conversa. O padrão é agent-proxy: um front-end de voz em tempo real gerencia o momento dos turnos, as interrupções e a reprodução, delega o trabalho substancial ao agente OpenClaw encaminhado por meio de openclaw_agent_consult e trata o resultado como um prompt digitado no Discord por esse participante. stt-tts mantém o fluxo em lote mais antigo de STT seguido de TTS. bidi permite que o modelo em tempo real converse diretamente, disponibilizando openclaw_agent_consult para o cérebro do OpenClaw.
• voice.agentSession controla qual conversa do OpenClaw recebe os turnos de voz. Deixe essa opção não definida para usar a própria sessão do canal de voz ou defina { mode: "target", target: "channel:<text-channel-id>" } para fazer com que o canal de voz atue como uma 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 no Discord e consultas em tempo real. Deixe essa opção não definida para herdar o modelo do agente encaminhado. Ela é separada de voice.realtime.model.
• voice.followUsers permite que o bot entre, mude de canal e saia da voz do Discord junto com usuários selecionados. Consulte Seguir usuários na voz.
• agent-proxy encaminha a fala por discord-voice, que preserva a autorização normal de proprietário e de ferramentas para o participante 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 concede à consulta acesso a ferramentas equivalente ao do proprietário para participantes proprietários (voice.realtime.toolPolicy: "owner") e dá forte preferência à consulta do agente OpenClaw antes de respostas substanciais (voice.realtime.consultPolicy: "always"). Nesse modo padrão always, a camada em tempo real não fala automaticamente conteúdo de preenchimento antes da resposta da consulta; ela captura e transcreve a fala e, em seguida, reproduz a resposta encaminhada do OpenClaw. Se várias respostas de consultas obrigatórias forem concluídas enquanto o Discord ainda estiver reproduzindo a primeira resposta, as respostas posteriores com fala exata serão enfileiradas até que a reprodução fique ociosa, em vez de substituir a fala no meio de uma frase.
• No modo stt-tts, o STT usa tools.media.audio; voice.model não afeta a transcrição.
• Nos modos em tempo real, voice.realtime.provider, voice.realtime.model e voice.realtime.speakerVoice configuram a sessão de áudio em tempo real. Para o OpenAI Realtime 2.1 com o cérebro Codex, use voice.realtime.model: "gpt-realtime-2.1" e voice.model: "openai/gpt-5.6-sol".
• Por padrão, os modos de voz em tempo real incluem os pequenos arquivos de perfil IDENTITY.md, USER.md e SOUL.md nas instruções do provedor em tempo real, para que turnos diretos e rápidos mantenham a mesma identidade, contextualização do usuário e persona do agente OpenClaw encaminhado. Defina voice.realtime.bootstrapContextFiles como um subconjunto para personalizar isso ou como [] para desabilitá-lo. Somente esses arquivos de perfil são compatíveis; AGENTS.md permanece no contexto normal do agente. O contexto de perfil injetado não substitui openclaw_agent_consult para trabalho no espaço de trabalho, fatos atuais, consulta à memória ou ações respaldadas 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 em silêncio até que uma transcrição comece ou termine com um nome de ativação. Os nomes de ativação configurados devem ter uma ou duas palavras. Se voice.realtime.wakeNames não estiver definido, o OpenClaw usará o name do agente encaminhado mais OpenClaw, recorrendo ao ID do agente mais OpenClaw. A restrição por nome de ativação desabilita a resposta automática do provedor em tempo real, encaminha os turnos aceitos pelo fluxo de consulta do agente OpenClaw e fornece uma breve confirmação falada quando um nome de ativação inicial é reconhecido na transcrição parcial antes da chegada da transcrição final.
• O provedor em tempo real da OpenAI aceita os nomes atuais de eventos do Realtime 2 e aliases legados compatíveis com o Codex para eventos de áudio de saída e transcrição, portanto snapshots compatíveis do provedor podem divergir sem descartar o áudio do assistente.
• voice.realtime.bargeIn controla se os eventos de início de fala no Discord interrompem a reprodução ativa em tempo real. Se não estiver definido, seguirá a configuração de interrupção por á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 ambientes com pouco eco ou aumente o valor para configurações de alto-falantes com muito eco.
• voice.tts substitui messages.tts somente para a reprodução de voz de stt-tts; os modos em tempo real usam voice.realtime.speakerVoice. Para usar uma voz da OpenAI na reprodução do Discord, defina voice.tts.provider: "openai" e escolha uma voz de conversão de texto em fala em voice.tts.providers.openai.speakerVoice. cedar é uma boa opção com sonoridade masculina no modelo TTS atual da OpenAI.
• As substituições de systemPrompt do Discord por canal são aplicadas aos turnos de transcrição de voz desse canal de voz.
• Os turnos de transcrição de voz derivam o status de proprietário de allowFrom (ou dm.allowFrom) do Discord para comandos e ações de canal restritos ao proprietário. A visibilidade das ferramentas do agente segue a política de ferramentas configurada para a sessão encaminhada.
• Se voice.autoJoin tiver várias entradas para o mesmo servidor, o OpenClaw entrará no último canal configurado para esse servidor.
• voice.allowedChannels é uma lista de permissões de permanência opcional. Deixe essa opção não definida para permitir que /vc join entre em qualquer canal de voz autorizado do Discord. Quando definida, /vc join, a entrada automática na inicialização e as mudanças de estado de voz do bot ficam restritas às entradas { guildId, channelId } listadas. Defina-a como um array vazio para negar todas as entradas na voz do Discord. Se o Discord mover o bot para fora da lista de permissões, o OpenClaw sairá desse canal e entrará novamente no destino configurado para 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 do upstream são daveEncryption=true e decryptionFailureTolerance=24.
• O OpenClaw usa o codec libopus-wasm incluído para receber voz do Discord e reproduzir PCM bruto em tempo real. Ele inclui uma compilação WebAssembly fixada do libopus e não requer complementos nativos do opus.
• voice.connectTimeoutMs controla a espera inicial pelo estado Ready de @discordjs/voice nas tentativas de /vc join e entrada automática. Padrão: 30000.
• voice.reconnectGraceMs controla por quanto tempo o OpenClaw aguarda 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 apenas porque outro usuário começa a falar. Para evitar ciclos de realimentação, o OpenClaw ignora novas capturas de voz enquanto o TTS está sendo reproduzido; fale após o término da reprodução para iniciar o próximo turno. Os modos em tempo real encaminham os inícios de fala como sinais de interrupção ao provedor em tempo real.
• Nos modos em tempo real, o eco dos alto-falantes captado por um microfone aberto pode parecer uma 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 em resposta ao áudio de entrada. Adicione voice.realtime.bargeIn: true se ainda quiser que os 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 inferiores a voice.realtime.minBargeInAudioEndMs por considerá-los prováveis ecos/ruídos e os registra como ignorados, em vez de limpar a reprodução do Discord.
• voice.captureSilenceGraceMs controla por quanto tempo o OpenClaw aguarda após o Discord informar que um participante parou de falar antes de finalizar esse segmento de áudio para STT. Padrão: 2000; aumente o valor se o Discord estiver dividindo pausas normais em transcrições parciais fragmentadas.
• Quando o ElevenLabs é o provedor de TTS selecionado, a reprodução de voz do Discord usa TTS por streaming e começa a partir do fluxo de resposta do provedor. Provedores sem suporte a streaming recorrem ao fluxo de arquivo temporário sintetizado.
• O OpenClaw monitora falhas de descriptografia na recepção e se recupera automaticamente saindo e entrando novamente no canal de voz após falhas repetidas em um intervalo curto.
• Se os logs de recepção mostrarem repetidamente DecryptionFailed(UnencryptedWhenPassthroughDisabled) após uma atualização, colete um relatório de dependências e os logs. A versão incluída de @discordjs/voice contém a correção upstream de preenchimento do PR #11449 do discord.js, que encerrou a issue #11419 do discord.js.
• Os eventos de recepção The operation was aborted são esperados quando o OpenClaw finaliza um segmento capturado de um participante; são diagnósticos detalhados, não avisos.
• Os logs detalhados da voz do Discord incluem uma prévia limitada de uma linha da transcrição STT para cada segmento de participante aceito, permitindo que a depuração mostre tanto o lado do usuário quanto o lado da resposta do agente sem despejar texto de transcrição sem limite.
• No modo agent-proxy, o fallback de consulta obrigatória ignora fragmentos de transcrição provavelmente incompletos, como textos que terminam em ... ou em um conector final como “e”, além de encerramentos claramente não acionáveis, como “já volto” ou “tchau”. Os logs mostram forced agent consult skipped reason=... quando isso impede uma resposta obsoleta na fila.

​

Seguir usuários na voz

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

• followUsers aceita IDs brutos de usuários do Discord e valores discord:<id>. O OpenClaw normaliza ambas as formas antes de compará-las aos eventos de estado de voz.
• followUsersEnabled usa true como padrão quando followUsers está configurado. Defina-o como false para manter a lista salva, mas interromper o acompanhamento automático por voz.
• Quando um usuário seguido entra em um canal de voz permitido, o OpenClaw entra nesse canal. Quando o usuário muda de canal, o OpenClaw o acompanha. 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 mudará para o canal de outro usuário seguido monitorado antes de sair do servidor. Se vários usuários seguidos mudarem de canal ao mesmo tempo, prevalecerá o evento de estado de voz observado mais recentemente.
• allowedChannels continua sendo aplicado. Um usuário seguido em um canal não permitido é ignorado, e uma sessão controlada por acompanhamento muda para outro usuário seguido ou sai.
• O OpenClaw reconcilia eventos de estado de voz perdidos na inicialização e em intervalos limitados. A reconciliação consulta servidores configurados por amostragem e limita as consultas REST por execução, portanto listas followUsers muito grandes podem levar mais de um intervalo para convergir.
• Se o Discord ou um administrador mover o bot enquanto ele estiver seguindo um usuário, o OpenClaw reconstruirá a sessão de voz e preservará o controle por acompanhamento quando o destino for permitido. Se o bot for movido para fora de allowedChannels, o OpenClaw sairá e entrará novamente no destino configurado quando houver um.
• A recuperação de recepção do DAVE pode sair e entrar novamente no mesmo canal após falhas repetidas de descriptografia. As sessões controladas por acompanhamento mantêm esse controle durante o fluxo de recuperação, portanto uma desconexão posterior do usuário seguido ainda fará com que o bot saia do canal.

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

• Os logs de recepção de voz mostram discord voice: opus decoder: libopus-wasm.
• A reprodução em tempo real codifica PCM estéreo bruto de 48 kHz em Opus com o mesmo pacote libopus-wasm incluído antes de entregar os pacotes a @discordjs/voice.
• A reprodução de arquivos e fluxos de provedores 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.

• A captura PCM do Discord é convertida em um arquivo WAV temporário.
• tools.media.audio processa STT, por exemplo, openai/gpt-4o-mini-transcribe.
• A transcrição é enviada pela entrada e pelo roteamento do Discord enquanto o LLM de resposta é executado com uma política de saída de voz que oculta a ferramenta tts do agente e solicita o retorno de texto, pois a voz do Discord é responsável pela reprodução final de TTS.
• voice.model, quando definido, substitui apenas o LLM de resposta para este turno do canal de voz.
• voice.tts é mesclado sobre messages.tts; provedores com capacidade de streaming alimentam o player diretamente; caso contrário, o arquivo de áudio resultante é reproduzido no canal em que o bot entrou.

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

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

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

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

• target: "channel:123456789012345678" roteia por uma sessão de canal de texto do Discord.
• target: "123456789012345678" é tratado como um destino de canal.
• target: "dm:123456789012345678" ou target: "user:123456789012345678" roteia por essa sessão de mensagem direta.

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

• Ao entrar: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Ao iniciar o modo em tempo real: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• No áudio do 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=...
• Ao ignorar fala obsoleta: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... ou reason=non-actionable-closing ...
• Ao concluir a resposta em tempo real: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Ao interromper/redefinir a reprodução: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Na consulta em tempo real: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Na resposta do agente: discord voice: agent turn answer ...
• Ao enfileirar fala exata: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., seguido por discord voice: realtime exact speech dequeued reason=player-idle ...
• Ao detectar interrupção por fala: 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 em tempo real: 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 ...
• Ao ignorar eco/ruído: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Com interrupção por fala desativada: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Com reprodução ociosa: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

1. realtime audio playback started significa que o Discord começou a reproduzir o áudio do assistente. A partir desse ponto, a ponte começa a contar os blocos de saída do assistente, os bytes PCM do Discord, os bytes do provedor em tempo real e a duração do áudio sintetizado.
2. realtime speaker turn opened indica que um falante do Discord ficou ativo. Se a reprodução já estiver ativa e bargeIn estiver habilitado, isso poderá ser seguido por barge-in detected source=speaker-start.
3. realtime input audio started indica o primeiro quadro de áudio real recebido para esse turno do falante. outputActive=true ou um outputAudioMs diferente de zero nesse ponto 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 detectou áudio ao vivo do falante 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 solicitou ao provedor em tempo real que cancelasse ou truncasse a resposta ativa. Ele inclui outputAudioMs, outputActive e playbackChunks, para que você possa ver quanto áudio do assistente havia realmente sido reproduzido antes da interrupção.
6. realtime audio playback stopped reason=... é o ponto de redefinição da reprodução local do Discord. O motivo indica quem interrompeu 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 do falante foi aberto, mas nenhum áudio utilizável chegou à ponte em tempo real. interruptedPlayback=true significa que esse turno de entrada se sobrepôs à saída do assistente e acionou a lógica de interrupção por fala.

• outputAudioMs: duração do áudio do assistente gerado pelo provedor em tempo real antes da linha de log.
• audioMs: duração do áudio do assistente contabilizada pelo OpenClaw antes da interrupção da reprodução.
• elapsedMs: tempo decorrido entre a abertura e o fechamento do fluxo de reprodução ou do turno do 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 em tempo real.
• playbackChunks: blocos de áudio do assistente encaminhados ao Discord para a resposta ativa.
• sinceLastAudioMs: intervalo entre o último quadro de áudio capturado do falante e o fechamento do turno do falante.

• Uma interrupção imediata com source=active-speaker-audio, outputAudioMs pequeno e o mesmo usuário por perto geralmente indica que o eco do alto-falante está 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 o início de fala de um usuário, mas nenhum áudio chegou ao OpenClaw. Isso pode ser um evento transitório de voz do Discord, comportamento do controle de ruído ou um cliente ativando brevemente o microfone.
• audio playback stopped reason=stream-close sem uma interrupção por fala ou provider-clear-audio próximo significa que o fluxo de reprodução local 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 detectou fala, mas o OpenClaw não tinha uma reprodução ativa para interromper. Isso não deve interromper o áudio.

​

Mensagens de voz

• Forneça um caminho de arquivo local (URLs são rejeitadas).
• Omita o 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 doctor
openclaw channels status --probe
openclaw logs --follow

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

{
  channels: {
    defaults: {
      botLoopProtection: {
        maxEventsPerWindow: 20,
        windowSeconds: 60,
        cooldownSeconds: 60,
      },
    },
    discord: {
      // Substituição opcional para todo o Discord. Os blocos de conta substituem campos
      // individuais e herdam daqui os campos omitidos.
      botLoopProtection: {
        maxEventsPerWindow: 4,
      },
      accounts: {
        alpha: {
          // Alpha escuta outros bots somente quando eles o mencionam.
          allowBots: "mentions",
        },
        bravo: {
          // Bravo escuta todas as mensagens do Discord criadas por bots.
          allowBots: true,
          mentionAliases: {
            // Permite que Bravo escreva uma menção a Alpha no Discord com o ID de usuário configurado.
            Alpha: "ALPHA_DISCORD_USER_ID",
          },
          botLoopProtection: {
            // Permite até cinco mensagens por minuto antes de suprimir o par.
            maxEventsPerWindow: 5,
            windowSeconds: 60,
            cooldownSeconds: 90,
          },
        },
      },
    },
  },
}

​

Referência de configuração

​

Segurança e operações

• Trate os tokens de bot como segredos (DISCORD_BOT_TOKEN é preferível em ambientes supervisionados).
• Conceda permissões do Discord com o menor privilégio possível.
• Se a implantação ou o estado dos comandos estiver desatualizado, reinicie o Gateway e verifique novamente com openclaw channels status --probe.

​

Relacionados