Pular para o conteúdo principal
Pronto para DMs e canais de guilda pelo Gateway oficial do Discord.

Emparelhamento

As DMs do Discord usam o modo de emparelhamento por padrão.

Comandos slash

Comportamento de comandos nativos e catálogo de comandos.

Solução de problemas de canal

Diagnósticos entre canais e fluxo de reparo.

​
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).
1

Crie um aplicativo e um bot do Discord

Acesse o Portal de Desenvolvedores do Discord e clique em New Application. Dê a ele um nome como “OpenClaw”.Clique em Bot na barra lateral. Defina o Username como o nome que você usa para seu agente OpenClaw.
2

Ative intents privilegiados

Ainda na página Bot, role para baixo até Privileged Gateway Intents e ative:
  • Message Content Intent (obrigatório)
  • Server Members Intent (recomendado; obrigatório para listas de permissões de funções e correspondência de nome para ID)
  • Presence Intent (opcional; necessário apenas para atualizações de presença)
3

Copie o token do seu bot

Role de volta para cima na página Bot e clique em Reset Token.
Apesar do nome, isso gera seu primeiro token — nada está sendo “redefinido”.
Copie o token e salve-o em algum lugar. Este é o seu Bot Token e você precisará dele em breve.
4

Gere uma URL de convite e adicione o bot ao seu servidor

Clique em OAuth2 na barra lateral. Você gerará uma URL de convite com as permissões corretas para adicionar o bot ao seu servidor.Role para baixo até OAuth2 URL Generator e ative:
  • bot
  • applications.commands
Uma seção Bot Permissions aparecerá abaixo. Ative pelo menos:Permissões gerais
  • Ver canais
Permissões de texto
  • Enviar mensagens
  • Ler histórico de mensagens
  • Incorporar links
  • Anexar arquivos
  • Adicionar reações (opcional)
Este é o conjunto básico para canais de texto normais. Se você planeja postar em threads do Discord, incluindo fluxos de trabalho de canais de fórum ou mídia que criam ou continuam uma thread, ative também Send Messages in Threads. Copie a URL gerada na parte inferior, cole-a no navegador, selecione seu servidor e clique em Continue para conectar. Agora você deve ver seu bot no servidor Discord.
5

Ative o Modo de Desenvolvedor e colete seus IDs

De volta ao aplicativo Discord, você precisa ativar o Modo de Desenvolvedor para poder copiar IDs internos.
  1. Clique em User Settings (ícone de engrenagem ao lado do seu avatar) → Role até Developer na barra lateral → ative Developer Mode (Observação: no aplicativo móvel do Discord, o Modo de Desenvolvedor fica em App Settings → Advanced)
  2. Clique com o botão direito no ícone do servidor na barra lateral → Copy Server ID
  3. Clique com o botão direito no seu próprio avatar → Copy User ID
Salve seu Server ID e User ID junto com seu Bot Token — você enviará os três ao OpenClaw na próxima etapa.
6

Permita DMs de membros do servidor

Para que o emparelhamento funcione, o Discord precisa permitir que seu bot envie DM para você. Clique com o botão direito no ícone do servidor → Privacy Settings → ative Direct Messages.Isso permite que membros do servidor (incluindo bots) enviem DMs para você. Mantenha isso ativado se quiser usar DMs do Discord com o OpenClaw. Se você planeja usar apenas canais de guilda, pode desativar DMs depois do emparelhamento.
7

Defina o token do seu bot com segurança (não o envie no chat)

O token do seu bot do Discord é um segredo (como uma senha). Defina-o na máquina que executa o OpenClaw antes de enviar mensagens ao seu agente.
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
Se o OpenClaw já estiver em execução como um serviço em segundo plano, reinicie-o pelo aplicativo OpenClaw para Mac ou interrompendo e reiniciando o processo openclaw gateway run. Para instalações de serviço gerenciado, execute openclaw gateway install a partir de um shell em que DISCORD_BOT_TOKEN esteja presente, ou armazene a variável em ~/.openclaw/.env, para que o serviço possa resolver o SecretRef de env após a reinicialização. Se seu host for bloqueado ou tiver limite de taxa pela consulta de aplicativo de inicialização do Discord, defina o ID de aplicativo/cliente do Discord no Portal de Desenvolvedores para que a inicialização possa pular essa chamada REST. Use channels.discord.applicationId para a conta padrão, ou channels.discord.accounts.<accountId>.applicationId quando executar vários bots do Discord.
8

Configure o OpenClaw e emparelhe

Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e diga a ele. Se o Discord for seu primeiro canal, use a aba CLI / configuração em vez disso.
“Já defini meu token de bot do Discord na configuração. Conclua a configuração do Discord com User ID <user_id> e Server ID <server_id>.”
9

Aprove o primeiro emparelhamento por DM

Aguarde até que o Gateway esteja em execução e envie uma DM para seu bot no Discord. Ele responderá com um código de emparelhamento.
Envie o código de emparelhamento ao seu agente no canal existente:
“Aprove este código de emparelhamento do Discord: <CODE>”
Códigos de emparelhamento expiram após 1 hora.Agora você deve conseguir conversar com seu agente no Discord via DM.
A resolução de token reconhece contas. Valores de token na configuração têm prioridade sobre fallback de env. DISCORD_BOT_TOKEN é usado apenas para a conta padrão. Se duas contas do Discord ativadas resolverem para o mesmo token de bot, o OpenClaw inicia apenas um monitor de Gateway para esse token. Um token vindo da configuração tem prioridade sobre o fallback de env padrão; caso contrário, a primeira conta ativada vence e a conta duplicada é reportada como desativada. Para chamadas de saída avançadas (ferramenta de mensagem/ações de canal), um token explícito por chamada é usado para essa chamada. Isso se aplica a ações de envio e leitura/sondagem (por exemplo, ler/pesquisar/buscar/thread/pins/permissões). As configurações de política/tentativa da conta ainda vêm da conta selecionada no snapshot de runtime ativo.

​
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.
1

Adicione seu servidor à lista de permissões de guilda

Isso permite que seu agente responda em qualquer canal do seu servidor, não apenas em DMs.
“Adicione meu Server ID do Discord <server_id> à lista de permissões de guilda”
2

Permita respostas sem @mention

Por padrão, seu agente só responde em canais de guilda quando recebe @mention. Para um servidor privado, você provavelmente quer que ele responda a todas as mensagens.Em canais de guilda, respostas normais são publicadas automaticamente por padrão. Para salas compartilhadas sempre ativas, opte por messages.groupChat.visibleReplies: "message_tool" para que o agente possa ficar à espreita e postar apenas quando decidir que uma resposta no canal é útil. Isso funciona melhor com modelos de última geração e confiáveis em ferramentas, como GPT 5.5. Eventos de sala ambiente ficam silenciosos a menos que a ferramenta envie. Consulte Eventos de sala ambiente para a configuração completa do modo de observação.Se o Discord mostrar digitação e os logs mostrarem uso de token, mas nenhuma mensagem publicada, verifique se o turno foi configurado como um evento de sala ambiente ou optou por respostas visíveis via ferramenta de mensagem.
“Permita que meu agente responda neste servidor sem precisar receber @mention”
3

Planeje a memória em canais de guilda

Por padrão, a memória de longo prazo (MEMORY.md) só é carregada em sessões de DM. Canais de guilda não carregam MEMORY.md automaticamente.
“Quando eu fizer perguntas em canais do Discord, use memory_search ou memory_get se precisar de contexto de longo prazo de MEMORY.md.”
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

channels.discord.dmPolicy controla o acesso por DM. channels.discord.allowFrom é a lista de permissões canônica para DM.
  • pairing (padrão)
  • allowlist
  • open (exige que channels.discord.allowFrom inclua "*")
  • disabled
Se a política de DM não estiver aberta, usuários desconhecidos serão bloqueados (ou solicitados a fazer pareamento no modo pairing).Precedência de várias contas:
  • channels.discord.accounts.default.allowFrom se aplica apenas à conta default.
  • Para uma conta, allowFrom tem precedência sobre o dm.allowFrom legado.
  • Contas nomeadas herdam channels.discord.allowFrom quando seus próprios allowFrom e dm.allowFrom legado não estão definidos.
  • Contas nomeadas não herdam channels.discord.accounts.default.allowFrom.
channels.discord.dm.policy e channels.discord.dm.allowFrom legados ainda são lidos para compatibilidade. openclaw doctor --fix os migra para dmPolicy e allowFrom quando pode fazer isso sem alterar o acesso.Formato de destino de DM para entrega:
  • user:<id>
  • menção <@id>
IDs numéricos simples normalmente são resolvidos como IDs de canal quando um padrão de canal está ativo, mas IDs listados no allowFrom efetivo de DM da conta são tratados como destinos de DM de usuário para compatibilidade.

​
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

O Discord oferece suporte a tags de resposta na saída do agente:
  • [[reply_to_current]]
  • [[reply_to:<id>]]
Controlado por channels.discord.replyToMode:
  • off (padrão)
  • first
  • all
  • batched
Observação: off desabilita o encadeamento implícito de respostas. Tags explícitas [[reply_to_*]] ainda são respeitadas. first sempre anexa a referência implícita de resposta nativa à primeira mensagem de saída do Discord no turno. batched só anexa a referência implícita de resposta nativa do Discord quando o evento de entrada foi um lote com debounce de várias mensagens. Isso é útil quando você quer respostas nativas principalmente para conversas ambíguas em rajadas, não para cada turno de mensagem única.IDs de mensagem são expostos no contexto/histórico para que agentes possam mirar mensagens específicas.
O OpenClaw pode transmitir rascunhos de respostas enviando uma mensagem temporária e editando-a conforme o texto chega. channels.discord.streaming aceita off | partial | block | progress (padrão). progress mantém um rascunho de status editável e o atualiza com o progresso de ferramentas até a entrega final; o rótulo inicial compartilhado é uma linha contínua, então ele rola para fora como o restante quando trabalho suficiente aparece. streamMode é um alias de runtime legado. Execute openclaw doctor --fix para regravar a configuração persistida para a chave canônica.Defina channels.discord.streaming.mode como off para desabilitar edições de prévia do Discord. Se a transmissão em bloco do Discord estiver explicitamente habilitada, o OpenClaw ignora a transmissão de prévia para evitar transmissão duplicada.
{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
          commentary: false,
        },
      },
    },
  },
}
  • partial edita uma única mensagem de prévia conforme tokens chegam.
  • block emite blocos do tamanho de rascunho (use draftChunk para ajustar tamanho e pontos de quebra, limitado a textChunkLimit).
  • Finais com mídia, erro e resposta explícita cancelam edições de prévia pendentes.
  • streaming.preview.toolProgress (padrão true) controla se atualizações de ferramenta/progresso reutilizam a mensagem de prévia.
  • Linhas de ferramenta/progresso são renderizadas como emoji compacto + título + detalhe quando disponível, por exemplo 🛠️ Bash: run tests ou 🔎 Web Search: for "query".
  • streaming.progress.commentary (padrão false) opta por incluir texto de comentário/preâmbulo do assistente no rascunho temporário de progresso. O comentário é limpo antes da exibição, permanece transitório e não altera a entrega da resposta final.
  • streaming.progress.maxLineChars controla o orçamento de prévia de progresso por linha. A prosa é encurtada nos limites de palavras; detalhes de comando e caminho mantêm sufixos úteis.
  • streaming.preview.commandText / streaming.progress.commandText controla detalhes de comando/execução em linhas compactas de progresso: raw (padrão) ou status (somente rótulo da ferramenta).
Oculte o texto bruto de comando/execução enquanto mantém linhas compactas de progresso:
{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}
A transmissão de prévia é somente texto; respostas com mídia voltam para a entrega normal. Quando a transmissão block é explicitamente habilitada, o OpenClaw ignora a transmissão de prévia para evitar transmissão duplicada.
Contexto de histórico da guilda:
  • channels.discord.historyLimit padrão 20
  • fallback: messages.groupChat.historyLimit
  • 0 desabilita
Controles de histórico de DM:
  • channels.discord.dmHistoryLimit
  • channels.discord.dms["<user_id>"].historyLimit
Comportamento de threads:
  • Threads do Discord são roteadas como sessões de canal e herdam a configuração do canal pai, a menos que substituídas.
  • Sessões de thread herdam a seleção de /model em nível de sessão do canal pai como fallback somente de modelo; seleções de /model locais à thread ainda têm precedência, e o histórico de transcrição do pai não é copiado, a menos que a herança de transcrição esteja habilitada.
  • channels.discord.thread.inheritParent (padrão false) faz com que novas auto-threads sejam semeadas a partir da transcrição pai. Substituições por conta ficam em channels.discord.accounts.<id>.thread.inheritParent.
  • Reações da ferramenta de mensagens podem resolver alvos de DM user:<id>.
  • guilds.<guild>.channels.<channel>.requireMention: false é preservado durante o fallback de ativação na etapa de resposta.
Tópicos de canal são injetados como contexto não confiável. Listas de permissão controlam quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar.
O Discord pode associar uma thread a um alvo de sessão para que mensagens de acompanhamento nessa thread continuem roteando para a mesma sessão (incluindo sessões de subagente).Comandos:
  • /focus <target> associa a thread atual/nova a um alvo de subagente/sessão
  • /unfocus remove a associação da thread atual
  • /agents mostra execuções ativas e o estado de associação
  • /session idle <duration|off> inspeciona/atualiza o desfoco automático por inatividade para associações focadas
  • /session max-age <duration|off> inspeciona/atualiza a idade máxima rígida para associações focadas
Configuração:
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
    },
  },
}
Observações:
  • session.threadBindings.* define padrões globais.
  • channels.discord.threadBindings.* substitui o comportamento do Discord.
  • spawnSessions controla a criação/associação automática de threads para sessions_spawn({ thread: true }) e spawns de thread ACP. Padrão: true.
  • defaultSpawnContext controla o contexto nativo de subagente para spawns associados a thread. Padrão: "fork".
  • Chaves obsoletas spawnSubagentSessions/spawnAcpSessions são migradas por openclaw doctor --fix.
  • Se associações de thread estiverem desabilitadas para uma conta, /focus e operações relacionadas de associação de thread ficam indisponíveis.
Consulte Subagentes, Agentes ACP e Referência de configuração.
Para workspaces ACP estáveis e “sempre ativos”, configure associações ACP tipadas de nível superior mirando conversas do Discord.Caminho de configuração:
  • bindings[] com type: "acp" e match.channel: "discord"
Exemplo:
{
  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,
            },
          },
        },
      },
    },
  },
}
Observações:
  • /acp spawn codex --bind here associa o canal ou a thread atual no local e mantém mensagens futuras na mesma sessão ACP. Mensagens de thread herdam a associação do canal pai.
  • Em um canal ou thread associado, /new e /reset redefinem a mesma sessão ACP no local. Associações temporárias de thread podem substituir a resolução de alvo enquanto ativas.
  • spawnSessions controla a criação/associação de threads filhas via --thread auto|here.
Consulte Agentes ACP para detalhes do comportamento de associação.
Modo de notificação de reação por guilda:
  • off
  • own (padrão)
  • all
  • allowlist (usa guilds.<id>.users)
Eventos de reação são transformados em eventos de sistema e anexados à sessão roteada do Discord.
ackReaction envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem de entrada.Ordem de resolução:
  • channels.discord.accounts.<accountId>.ackReaction
  • channels.discord.ackReaction
  • messages.ackReaction
  • fallback de emoji da identidade do agente (agents.list[].identity.emoji, senão ”👀”)
Observações:
  • O Discord aceita emoji unicode ou nomes de emoji personalizados.
  • Use "" para desabilitar a reação para um canal ou conta.
Escritas de configuração iniciadas pelo canal são habilitadas por padrão.Isso afeta fluxos /config set|unset (quando recursos de comando estão habilitados).Desabilitar:
{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}
Roteie o tráfego WebSocket do Gateway do Discord e consultas REST de inicialização (ID da aplicação + resolução de lista de permissões) por meio de um proxy HTTP(S) com channels.discord.proxy. O proxy WebSocket do Gateway do Discord é explícito; conexões WebSocket não herdam variáveis de ambiente de proxy do ambiente do processo do Gateway. Consultas REST de inicialização usam esse proxy quando channels.discord.proxy está configurado.
{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}
Substituição por conta:
{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}
Ative a resolução do PluralKit para mapear mensagens intermediadas para a identidade do membro do sistema:
{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}
Observações:
  • listas de permissão podem usar pk:<memberId>
  • nomes de exibição de membros são correspondidos por nome/slug somente quando channels.discord.dangerouslyAllowNameMatching: true
  • consultas usam o ID da mensagem original e são limitadas por janela de tempo
  • se a consulta falhar, mensagens intermediadas são tratadas como mensagens de bot e descartadas, a menos que allowBots=true
Use mentionAliases quando agentes precisarem de menções de saída determinísticas para usuários conhecidos do Discord. As chaves são identificadores sem o @ inicial; os valores são IDs de usuários do Discord. Identificadores desconhecidos, @everyone, @here e menções dentro de spans de código Markdown permanecem inalterados.
{
  channels: {
    discord: {
      mentionAliases: {
        Vladislava: "123456789012345678",
      },
      accounts: {
        ops: {
          mentionAliases: {
            OpsLead: "234567890123456789",
          },
        },
      },
    },
  },
}
Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando ativa a presença automática.Exemplo somente de status:
{
  channels: {
    discord: {
      status: "idle",
    },
  },
}
Exemplo de atividade (status personalizado é o tipo de atividade padrão):
{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}
Exemplo de streaming:
{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}
Mapa de tipos de atividade:
  • 0: Jogando
  • 1: Streaming (requer activityUrl)
  • 2: Ouvindo
  • 3: Assistindo
  • 4: Personalizado (usa o texto da atividade como estado do status; emoji é opcional)
  • 5: Competindo
Exemplo de presença automática (sinal de integridade em runtime):
{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}
A presença automática mapeia a disponibilidade em runtime para o status do Discord: íntegro => online, degradado ou desconhecido => idle, esgotado ou indisponível => dnd. Substituições opcionais de texto:
  • autoPresence.healthyText
  • autoPresence.degradedText
  • autoPresence.exhaustedText (aceita o placeholder {reason})
O Discord oferece suporte ao tratamento de aprovações por botões em DMs e pode, opcionalmente, publicar solicitações de aprovação no canal de origem.Caminho de configuração:
  • channels.discord.execApprovals.enabled
  • channels.discord.execApprovals.approvers (opcional; recorre a commands.ownerAllowFrom quando possível)
  • channels.discord.execApprovals.target (dm | channel | both, padrão: dm)
  • agentFilter, sessionFilter, cleanupAfterResolve
O Discord ativa automaticamente aprovações nativas de exec quando enabled não está definido ou é "auto" e pelo menos um aprovador pode ser resolvido, seja de execApprovals.approvers ou de commands.ownerAllowFrom. O Discord não infere aprovadores de exec a partir de allowFrom do canal, dm.allowFrom legado ou defaultTo de mensagens diretas. Defina enabled: false para desativar explicitamente o Discord como cliente de aprovação nativo.Para comandos de grupo confidenciais exclusivos do proprietário, como /diagnostics e /export-trajectory, o OpenClaw envia solicitações de aprovação e resultados finais de forma privada. Ele tenta primeiro uma DM do Discord quando o proprietário que invocou o comando tem uma rota de proprietário do Discord; se isso não estiver disponível, recorre à primeira rota de proprietário disponível em commands.ownerAllowFrom, como Telegram.Quando target é channel ou both, a solicitação de aprovação fica visível no canal. Somente aprovadores resolvidos podem usar os botões; outros usuários recebem uma negativa efêmera. Solicitações de aprovação incluem o texto do comando, portanto ative a entrega no canal somente em canais confiáveis. Se o ID do canal não puder ser derivado da chave da sessão, o OpenClaw recorre à entrega por DM.O Discord também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Discord adiciona principalmente roteamento de DM para aprovadores e fanout de canal. Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw só deve incluir um comando manual /approve quando o resultado da ferramenta disser que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho. Se o runtime de aprovação nativa do Discord não estiver ativo, o OpenClaw mantém o prompt determinístico local /approve <id> <decision> visível. Se o runtime estiver ativo, mas um cartão nativo não puder ser entregue a nenhum destino, o OpenClaw envia um aviso de fallback no mesmo chat com o comando /approve exato da aprovação pendente.A autenticação do Gateway e a resolução de aprovações seguem o contrato compartilhado do cliente Gateway (IDs plugin: são resolvidos por plugin.approval.resolve; outros IDs por exec.approval.resolve). Aprovações expiram após 30 minutos por padrão.Consulte Aprovações de exec.

​
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:
Grupo de açõesPadrão
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissionsativado
rolesdesativado
moderationdesativado
presencedesativado

​
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

  • habilite Message Content Intent
  • habilite Server Members Intent quando você depender da resolução de usuário/membro
  • reinicie o gateway depois de alterar intents
  • verifique groupPolicy
  • verifique a allowlist de guildas em channels.discord.guilds
  • se o mapa channels da guilda existir, somente os canais listados serão permitidos
  • verifique o comportamento de requireMention e os padrões de menção
Verificações úteis:
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
Causas comuns:
  • groupPolicy="allowlist" sem allowlist de guilda/canal correspondente
  • requireMention configurado no lugar errado (deve ficar em channels.discord.guilds ou na entrada do canal)
  • remetente bloqueado pela allowlist users da guilda/canal
Logs típicos:
  • Slow listener detected ...
  • stuck session: sessionKey=agent:...:discord:... state=processing ...
Controles da fila do gateway do Discord:
  • conta única: channels.discord.eventQueue.listenerTimeout
  • várias contas: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
  • isso controla apenas o trabalho do listener do gateway do Discord, não a duração do turno do agente
O Discord não aplica um tempo limite pertencente ao canal a turnos de agente enfileirados. Listeners de mensagem transferem imediatamente, e execuções enfileiradas do Discord preservam a ordenação por sessão até que o ciclo de vida da sessão/ferramenta/runtime conclua ou aborte o trabalho.
{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
        },
      },
    },
  },
}
O OpenClaw busca metadados /gateway/bot do Discord antes de conectar. Falhas transitórias recorrem à URL padrão do gateway do Discord e são limitadas por taxa nos logs.Controles de tempo limite de metadados:
  • conta única: channels.discord.gatewayInfoTimeoutMs
  • várias contas: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
  • fallback de env quando a configuração não está definida: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
  • padrão: 30000 (30 segundos), máximo: 120000
O OpenClaw aguarda o evento READY do gateway do Discord durante a inicialização e após reconexões de runtime. Configurações com várias contas e escalonamento de inicialização podem precisar de uma janela READY de inicialização maior que o padrão.Controles de tempo limite de READY:
  • inicialização com conta única: channels.discord.gatewayReadyTimeoutMs
  • inicialização com várias contas: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
  • fallback de env de inicialização quando a configuração não está definida: OPENCLAW_DISCORD_READY_TIMEOUT_MS
  • padrão de inicialização: 15000 (15 segundos), máximo: 120000
  • runtime com conta única: channels.discord.gatewayRuntimeReadyTimeoutMs
  • runtime com várias contas: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
  • fallback de env de runtime quando a configuração não está definida: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
  • padrão de runtime: 30000 (30 segundos), máximo: 120000
As verificações de permissão de channels status --probe funcionam apenas para IDs numéricos de canal.Se você usar chaves slug, a correspondência em runtime ainda pode funcionar, mas o probe não consegue verificar permissões por completo.
  • DM desabilitada: channels.discord.dm.enabled=false
  • política de DM desabilitada: channels.discord.dmPolicy="disabled" (legado: channels.discord.dm.policy)
  • aguardando aprovação de pareamento no modo pairing
Por padrão, mensagens criadas por bots são ignoradas.Se você definir channels.discord.allowBots=true, use regras estritas de menção e allowlist para evitar comportamento de loop. Prefira channels.discord.allowBots="mentions" para aceitar apenas mensagens de bot que mencionem o bot.O OpenClaw também inclui proteção contra loop de bots compartilhada. Sempre que allowBots permite que mensagens criadas por bots cheguem ao dispatch, o Discord mapeia o evento de entrada para fatos de (conta, canal, par de bots) e a proteção genérica de par suprime o par depois que ele ultrapassa o orçamento de eventos configurado. A proteção evita loops descontrolados entre dois bots que antes precisavam ser interrompidos pelos limites de taxa do Discord; ela não afeta implantações com um único bot nem respostas pontuais de bots que permanecem abaixo do orçamento.Configurações padrão (ativas quando allowBots está definido):
  • maxEventsPerWindow: 20 — o par de bots pode trocar 20 mensagens dentro da janela deslizante
  • windowSeconds: 60 — duração da janela deslizante
  • cooldownSeconds: 60 — quando o orçamento é atingido, toda mensagem adicional de bot para bot em qualquer direção é descartada por um minuto
Configure o padrão compartilhado uma vez em channels.defaults.botLoopProtection e então sobrescreva o Discord quando um fluxo de trabalho legítimo precisar de mais margem. A precedência é:
  • channels.discord.accounts.<account>.botLoopProtection
  • channels.discord.botLoopProtection
  • channels.defaults.botLoopProtection
  • padrões integrados
O Discord usa as chaves genéricas maxEventsPerWindow, windowSeconds e cooldownSeconds.
{
  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,
          },
        },
      },
    },
  },
}
  • mantenha o OpenClaw atualizado (openclaw update) para que a lógica de recuperação de recebimento de voz do Discord esteja presente
  • confirme channels.discord.voice.daveEncryption=true (padrão)
  • comece com channels.discord.voice.decryptionFailureTolerance=24 (padrão upstream) e ajuste somente se necessário
  • observe os logs para:
    • discord voice: DAVE decrypt failures detected
    • discord voice: repeated decrypt failures; attempting rejoin
  • se as falhas continuarem após a reentrada automática, colete logs e compare com o histórico upstream de recebimento DAVE em discord.js #11419 e discord.js #11449

​
Referência de configuração

Referência principal: Referência de configuração - Discord.
  • inicialização/auth: enabled, token, accounts.*, allowBots
  • política: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
  • comando: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
  • fila de eventos: eventQueue.listenerTimeout (orçamento do listener), eventQueue.maxQueueSize, eventQueue.maxConcurrency
  • gateway: gatewayInfoTimeoutMs, gatewayReadyTimeoutMs, gatewayRuntimeReadyTimeoutMs
  • resposta/histórico: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
  • entrega: textChunkLimit, chunkMode, maxLinesPerMessage
  • streaming: streaming (alias legado: streamMode), streaming.preview.toolProgress, draftChunk, blockStreaming, blockStreamingCoalesce
  • mídia/tentativa: mediaMaxMb (limita uploads de saída do Discord, padrão 100MB), retry
  • ações: actions.*
  • presença: activity, status, activityType, activityUrl
  • UI: ui.components.accentColor
  • recursos: threadBindings, bindings[] de nível superior (type: "acp"), pluralkit, execApprovals, intents, agentComponents.enabled, agentComponents.ttlMs, heartbeat, responsePrefix

​
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

Pareamento

Pareie um usuário do Discord ao gateway.

Grupos

Comportamento de chat em grupo e allowlist.

Roteamento de canais

Roteie mensagens de entrada para agentes.

Segurança

Modelo de ameaças e hardening.

Roteamento multiagente

Mapeie guildas e canais para agentes.

Comandos slash

Comportamento de comando nativo.