Integração do OpenClaw com Discord: Configuração do Bot e Gateway Intents Explicados

Visão Geral

A integração com o Discord permite que você converse com o OpenClaw por meio de um bot do Discord, com suporte tanto para DM (mensagem direta) quanto para comunicação em canais de texto de servidores. Este guia aborda a criação de um bot, a compreensão dos Gateway Intents, a configuração de políticas de segurança de DM e o controle de acesso a canais de servidores — tudo baseado na documentação oficial do OpenClaw.

Pré-requisitos

• OpenClaw instalado e em execução
• Uma conta do Discord
• Um servidor do Discord onde você tenha permissões de administrador (para testes)

Como Funciona

Antes de começar, é útil entender como o OpenClaw roteia as mensagens do Discord:

• Conversas por DM são agrupadas em uma sessão compartilhada (agent:main:main) com segurança baseada em pareamento por padrão.
• Conversas em canais de servidor são isoladas por canal, usando o padrão agent:<agentId>:discord:channel:<channelId>.
• DMs em grupo são ignoradas por padrão, mas podem ser habilitadas via channels.discord.dm.groupEnabled.

O gateway inicia automaticamente quando um token válido existe e enabled não está definido como false.

Passo 1: Criar uma Aplicação do Discord

Acesse o Portal de Desenvolvedores do Discord

1. Visite o Portal de Desenvolvedores do Discord
2. Clique em New Application
3. Digite um nome (ex.: "OpenClaw Assistant")
4. Clique em Create

Configure o Bot

1. Na sua aplicação, vá para a aba Bot
2. Clique em Add Bot → Yes, do it!
3. Em Token, clique em Copy para copiar o token do seu bot

Importante: Trate o token do seu bot como uma senha. Nunca o compartilhe publicamente. Se for exposto, regenere-o imediatamente.

Passo 2: Habilitar Privileged Gateway Intents

Os Gateway Intents controlam quais eventos seu bot recebe do Discord. O OpenClaw requer intents privilegiados específicos para funcionar corretamente.

Intents Necessários

| Intent | Finalidade | Obrigatório | |--------|-----------|-------------| | Message Content Intent | Ler o texto das mensagens em canais de servidor | Obrigatório — sem ele, o bot exibe erros "Used disallowed intents" ou conecta mas não responde | | Server Members Intent | Consulta de membros e verificação de allowlist | Recomendado — necessário para controle de acesso baseado em allowlist |

Habilitando os Intents no Portal de Desenvolvedores

1. Vá para a aba Bot no Portal de Desenvolvedores
2. Role até Privileged Gateway Intents
3. Ative MESSAGE CONTENT INTENT (obrigatório)
4. Ative SERVER MEMBERS INTENT (recomendado)
5. Clique em Save Changes

Nota: Bots em mais de 100 servidores precisam de verificação do Discord para usar intents privilegiados.

Passo 3: Gerar URL de Convite do Bot

Configurar OAuth2

1. Vá para OAuth2 → URL Generator

2. Selecione os escopos:

   • bot
   • applications.commands (necessário para comandos de barra nativos)

3. Selecione as permissões do bot:

   • View Channels
   • Send Messages
   • Read Message History
   • Embed Links
   • Attach Files
   • Add Reactions (opcional, mas recomendado)
   • Use External Emojis (opcional)

Atenção: Evite conceder a permissão Administrator a menos que esteja depurando ativamente. Conceda apenas o necessário.

4. Copie a URL gerada

Convide o Bot

1. Abra a URL no seu navegador
2. Selecione seu servidor de teste
3. Clique em Authorize

Obtenha os IDs Numéricos

Ative o Developer Mode no Discord (Configurações do Usuário → Configurações do App → Avançado → Developer Mode) para poder clicar com o botão direito e copiar IDs de servidor, canal e usuário — você precisará deles para a configuração.

Passo 4: Configurar o OpenClaw

Opção A: Variável de Ambiente

Defina o token como uma variável de ambiente:

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

Opção B: Arquivo de Configuração

Edite seu arquivo de configuração do OpenClaw com o token diretamente:

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"
    }
  }
}

Nota: Quando existem tanto uma variável de ambiente quanto um token no arquivo de configuração, o arquivo de configuração tem precedência.

Opção C: Suporte a Múltiplas Contas

Para executar múltiplas contas de bot:

{
  channels: {
    discord: {
      accounts: [
        { token: "BOT_TOKEN_1", name: "assistant-1" },
        { token: "BOT_TOKEN_2", name: "assistant-2" }
      ]
    }
  }
}

Passo 5: Iniciar e Testar

Inicie ou reinicie o gateway do OpenClaw:

openclaw gateway restart

Verifique o status do canal:

openclaw channels status --probe

Execute o diagnóstico se algo parecer errado:

openclaw doctor

Para o contato inicial por DM, o bot usa um sistema de pareamento por padrão — o remetente recebe um código com tempo limitado (expira em 1 hora) que deve ser aprovado antes que a conversa comece.

Políticas de Segurança de DM

O OpenClaw oferece três políticas de controle de acesso para DMs:

Pareamento (Padrão)

Remetentes desconhecidos recebem um código de pareamento com tempo limitado que expira após 1 hora. O código deve ser aprovado antes que a conversa possa prosseguir.

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "pairing"
      }
    }
  }
}

Allowlist

Apenas IDs de usuário ou nomes de usuário configurados podem enviar DMs:

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: ["123456789012345678", "username#1234"]
      }
    }
  }
}

Open

Qualquer pessoa pode enviar DMs (use com cautela):

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "open",
        allowFrom: ["*"]
      }
    }
  }
}

Configuração de Canais de Servidor

Controle de Acesso Básico de Servidor

Restrinja o bot a servidores e canais específicos com requisitos de menção:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          requireMention: true,
          channels: {
            "CHANNEL_ID": {
              enabled: true
            }
          }
        }
      }
    }
  }
}

Importante: requireMention deve ser configurado no nível do servidor ou canal, não no nível superior da configuração do Discord.

Configurações por Canal

Você pode configurar allowlists e restrições de habilidades por canal:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_ID_1": {
              enabled: true,
              requireMention: true
            },
            "CHANNEL_ID_2": {
              enabled: true,
              requireMention: false
            }
          }
        }
      }
    }
  }
}

Parâmetros de Configuração

Configurações de Mensagem

| Parâmetro | Padrão | Descrição | |-----------|--------|-----------| | textChunkLimit | 2000 | Máximo de caracteres por bloco de mensagem enviada | | chunkMode | — | Definir para dividir em linhas em branco (limites de parágrafo) antes de aplicar limites de tamanho | | maxLinesPerMessage | 17 | Máximo de linhas por mensagem | | mediaMaxMb | 8 | Tamanho máximo de arquivo de mídia em MB |

Histórico de Contexto

{
  channels: {
    discord: {
      historyLimit: 20  // Number of recent messages included as context (default: 20, set to 0 to disable)
    }
  }
}

Reply Threading

O reply threading nativo está desativado por padrão. Ative-o com:

{
  channels: {
    discord: {
      replyToMode: "on"  // Enable native reply threading
    }
  }
}

Use tags de resposta nas respostas do agente para controlar o comportamento de threading:

• [[reply_to_current]] — responder à mensagem sendo tratada
• [[reply_to:<message_id>]] — responder a uma mensagem específica

Notificações de Reações

Configure notificações de eventos de reação por servidor:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          reactionNotifications: "own"  // Options: "off", "own", "all", "allowlist"
        }
      }
    }
  }
}

Ações de Ferramentas

O agente pode invocar uma ferramenta discord para executar ações dentro do Discord. A maioria das ações está habilitada por padrão, exceto roles e moderation, que são desabilitadas por padrão.

Ações Disponíveis

| Categoria | Ações | |-----------|-------| | Reactions | react, sticker, poll | | Messages | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | Threads | threadCreate, threadList, threadReply | | Pins | pinMessage, unpinMessage, listPins | | Channels | channelInfo, channelList | | Members | memberInfo, roleInfo, permissions | | Roles | roleAdd, roleRemove (desabilitado por padrão) | | Moderation | timeout, kick, ban (desabilitado por padrão) | | Other | emojiList, voiceStatus, eventList, eventCreate, setPresence |

Recursos Avançados

Suporte ao PluralKit

Quando habilitado, o OpenClaw resolve mensagens proxy para seus membros de sistema subjacentes, exibindo remetentes como "Member (PK:System)" para evitar pings acidentais no Discord.

Interface de Botão de Aprovação Exec

Em conversas por DM, o OpenClaw pode apresentar botões de aprovação exec para confirmação interativa de ações de ferramentas.

Configuração de Retentativas

Chamadas de API de saída automaticamente fazem retentativas em caso de limitação de taxa usando o cabeçalho retry_after do Discord com backoff exponencial. Configure o comportamento de retentativa via parâmetros channels.discord.retry.

Solução de Problemas

Bot Está Online Mas Não Responde

1. Verifique o Message Content Intent: Sem esse intent, o bot conecta mas não consegue ler o texto das mensagens. Vá para o Portal de Desenvolvedores → Bot → Privileged Gateway Intents e certifique-se de que o MESSAGE CONTENT INTENT está ativado.

2. Verifique as permissões do canal: Certifique-se de que o bot tem as permissões View Channels e Send Messages no canal de destino.

3. Verifique os requisitos de menção: Se requireMention estiver ativado para o servidor ou canal, você deve @mencionar o bot.

4. Verifique as allowlists de servidor/canal: Verifique se o canal não está bloqueado pela configuração de allowlist.

Erro "Used Disallowed Intents"

Isso significa que os intents necessários não estão habilitados no Portal de Desenvolvedores:

1. Vá para o Portal de Desenvolvedores → Bot → Privileged Gateway Intents
2. Ative o MESSAGE CONTENT INTENT
3. Salve e reinicie o gateway do OpenClaw

DMs Não Funcionam

1. Verifique se dm.enabled não está definido como false
2. Verifique a política de DM — se estiver definida como "allowlist", certifique-se de que o ID do usuário está incluído
3. Se estiver usando a política "pairing", verifique se o código de pareamento expirou (limite de 1 hora)

Comandos de Diagnóstico

Use as ferramentas de diagnóstico integradas para identificar problemas:

# Run full diagnostics
openclaw doctor

# Check channel status with connection probe
openclaw channels status --probe

Melhores Práticas

1. Trate tokens de bot como senhas — use variáveis de ambiente em hosts supervisionados, nunca faça commit de tokens no controle de versão.
2. Conceda apenas as permissões necessárias — evite Administrator a menos que esteja depurando ativamente.
3. Use políticas de DM de pareamento ou allowlist — a política "open" só deve ser usada para bots públicos com limitação de taxa apropriada.
4. Ative o Server Members Intent se estiver usando controle de acesso baseado em allowlist para uma correspondência de membros mais confiável.
5. Use requireMention em servidores movimentados para evitar que o bot responda a todas as mensagens.
6. Reinicie o gateway com --force se ele travar: openclaw gateway restart --force.

Próximos Passos

• Guia de integração com WhatsApp
• Guia de integração com Telegram
• Solução de erros comuns