Cómo conectar tu bot de Discord mediante Gateway

Configurar un bot de Discord a veces se siente como una batalla contra la documentación y los permisos que faltan. Es frustrante cuando los mensajes no llegan o cuando las sesiones se mezclan sin control entre canales y mensajes directos.

Para evitar complicaciones, lo mejor es usar el Gateway oficial. Esto te permite tener una conexión estable y un control total sobre cómo tu bot interactúa en servidores o chats privados de forma organizada.

Requisitos previos

Una aplicación creada en el Discord Developer Portal.
Un bot de Discord añadido a tu aplicación.
Permisos para invitar bots a un servidor.
El CLI de openclaw configurado en tu entorno.

Inicio rápido

Sigue estos pasos para tener tu bot funcionando en menos de 5 minutos:

1. Crear un bot de Discord y habilitar intents

Crea una aplicación en el Discord Developer Portal, añade un bot y activa estas opciones:

Message Content Intent
Server Members Intent (recomendado para búsquedas de nombre a ID y coincidencia de allowlist)

2. Configurar el token

Añade tu token directamente en el archivo de configuración:

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

O usa una variable de entorno para la cuenta por defecto:

DISCORD_BOT_TOKEN=...

3. Invitar al bot e iniciar el gateway

Invita al bot a tu servidor con permisos de mensaje y ejecuta el Gateway:

openclaw gateway

4. Aprobar el primer pairing de DM

Para los mensajes directos, necesitas autorizar la conexión:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Runtime model

El sistema gestiona las conexiones y sesiones siguiendo estas reglas:

El Gateway es el dueño de la conexión con Discord.
El enrutamiento de respuestas es determinista: lo que entra por Discord se responde por Discord.
Por defecto (session.dmScope=main), los chats directos comparten la sesión principal del agente (agent:main:main).
Los canales de servidores (Guild channels) usan claves de sesión aisladas (agent:<agentId>:discord:channel:<channelId>).
Los DMs grupales se ignoran por defecto (channels.discord.dm.groupEnabled=false).
Los Slash commands nativos se ejecutan en sesiones de comando aisladas (agent:<agentId>:discord:slash:<userId>), pero mantienen el CommandTargetSessionKey hacia la sesión de conversación enrutada.

Solución de problemas

Los códigos de pairing no funcionan: Recuerda que los códigos de pairing expiran después de 1 hora.
El bot no lee mensajes: Asegúrate de haber activado el Message Content Intent en el portal de desarrolladores.

¿Necesitas ayuda con la configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

Configurar un bot de Discord suele empezar de forma sencilla hasta que te das cuenta de que cualquiera puede invocarlo o enviarle mensajes privados sin control. Gestionar la seguridad y el ruteo de mensajes es vital para evitar que tu bot responda en servidores no autorizados o procese comandos de usuarios desconocidos.

Aquí aprenderás a establecer políticas estrictas para que tu bot solo interactúe donde y con quien tú decidas.

Requisitos previos

Para seguir esta guía, asegúrate de tener acceso a:

Discord Developer Portal: Para crear la aplicación y obtener el token.
Bot Token: Generado en la sección de “Bot”.
IDs de Discord: Necesitarás los IDs numéricos de tu servidor, canales y usuarios (activa el “Developer Mode” en Discord para copiarlos).

Inicio rápido

Configura tu bot en 5 minutos siguiendo estos pasos esenciales en el Discord Developer Portal y en tu archivo de configuración.

Crea la App y el Bot: Ve a Applications -> New Application. En la sección Bot, haz clic en Add Bot y copia el token.
Habilita Privileged Intents: En la pestaña Bot, activa Message Content Intent y Server Members Intent. Esto permite que el bot lea mensajes y reconozca a los miembros.
Configura OAuth2: En el generador de URL, selecciona los scopes bot y applications.commands.
Define Permisos: Marca los permisos básicos: View Channels, Send Messages, Read Message History, Embed Links y Attach Files. Evita usar Administrator.

Gestión de políticas y ruteo

Control de Mensajes Directos (DM)

La propiedad channels.discord.dm.policy define cómo responde el bot a los mensajes privados:

pairing (por defecto): Bloquea desconocidos o solicita vinculación.
allowlist: Solo permite usuarios en lista blanca.
open: Abierto a todos (requiere que channels.discord.dm.allowFrom incluya "*").
disabled: Desactiva los DM por completo.

Para el envío de mensajes, el formato del target debe ser user:<id> o la mención <@id>. No uses IDs numéricos simples, ya que son ambiguos y el sistema los rechazará.

Políticas de Servidor (Guild)

El comportamiento en servidores se gestiona con channels.discord.groupPolicy. Si existe el bloque channels.discord, el valor por defecto es allowlist para garantizar la seguridad.

open: El bot responde en cualquier servidor donde esté presente.
allowlist: El servidor debe coincidir con un ID en channels.discord.guilds.
disabled: Desactiva la interacción en servidores.

Si el servidor está en la allowlist pero no tiene un bloque de channels específico, se permiten todos sus canales. Si defines canales específicos, cualquier canal no listado será denegado.

Ejemplo de configuración:

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

Menciones y DMs grupales

Por defecto, los mensajes en servidores requieren una mención para que el bot responda. La detección de menciones incluye:

Mención explícita al bot.
Patrones configurados en agents.list[].groupChat.mentionPatterns.
Respuestas implícitas al bot (reply).

Los DMs grupales están desactivados por defecto (dm.groupEnabled=false). Puedes habilitarlos mediante una lista blanca en dm.groupChannels usando IDs o slugs.

Comandos nativos y autenticación

OpenClaw soporta comandos de barra (Slash commands) de forma nativa:

commands.native: Está en "auto" por defecto. Si lo cambias a false, se eliminarán los comandos registrados previamente en Discord.
Autenticación: Los comandos nativos usan las mismas políticas de allowlist que los mensajes normales.
Visibilidad: Es posible que usuarios no autorizados vean los comandos en la interfaz de Discord, pero al intentar ejecutarlos, OpenClaw denegará la acción y devolverá un error de “not authorized”.

Solución de problemas

El bot responde a todo el mundo: Revisa si has omitido el bloque channels.discord. Si solo configuras DISCORD_BOT_TOKEN, el sistema usa groupPolicy="open" por defecto y mostrará un aviso en los logs.
IDs rechazados: Asegúrate de usar IDs numéricos en lugar de nombres o slugs siempre que sea posible. Los IDs numéricos son más fiables para auditorías y procesos internos.
El bot no lee mensajes: Verifica que el Message Content Intent esté activado en el Developer Portal. Sin esto, el bot recibirá los eventos pero el contenido estará vacío.
Error de presencia: Si quieres actualizar el estado del bot (setPresence), no necesitas activar el Presence Intent de los miembros a menos que necesites monitorizar el estado de otros usuarios.

Para resolver dudas específicas sobre tu configuración, utiliza el AI Setup Assistant.

Próximos pasos

Slash commands: Explora el catálogo de comandos disponibles.
Configuración de Agentes: Define cómo interactúan tus agentes en estos canales.

Gestionar bots en Discord puede ser un dolor de cabeza cuando no responden correctamente a los hilos o pierden el rastro de la conversación. Es frustrante cuando tu agent ignora un mensaje específico o no reconoce las reacciones como disparadores de eventos, rompiendo la experiencia del usuario.

Si buscas que tu interacción se sienta nativa y fluida, necesitas ajustar cómo el Gateway maneja el contexto y las respuestas. Aquí te explico cómo configurar estas funciones avanzadas para que tu bot se comporte como un usuario más del servidor.

Requisitos previos

Una integración activa de Discord configurada en tu agent.
Acceso a los archivos de configuración (JSON5/YAML).
Permisos de administrador en el servidor de Discord para probar hilos y reacciones.
Un token de PluralKit (opcional, solo para sistemas privados).

Inicio rápido

Configura lo esencial en menos de 5 minutos para mejorar la interacción:

Activa las respuestas nativas: Usa [[reply_to_current]] en el output de tu agent y establece channels.discord.replyToMode en all.
Ajusta el contexto: Define channels.discord.historyLimit en 20 para que el agent recuerde los mensajes recientes.
Habilita reacciones: Cambia el modo de notificaciones a own o all para procesar emojis como eventos.
Controla la configuración: Si no quieres que los usuarios cambien ajustes vía comandos, establece configWrites: false.

Detalles de las Funciones

Reply tags y respuestas nativas

Discord permite que el output del agent incluya etiquetas de respuesta para mantener el orden en canales concurridos. Puedes usar estas etiquetas:

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

El comportamiento se controla mediante channels.discord.replyToMode. Te recomiendo usar all para una experiencia más coherente:

off (por defecto)
first
all

Los IDs de los mensajes aparecen en el contexto y el historial para que los agents puedan responder a mensajes específicos de forma precisa.

Historial, contexto e hilos

El manejo del historial es vital para que el agent no pierda el hilo. Estos son los parámetros que puedes ajustar:

Contexto de la Guild: channels.discord.historyLimit tiene un valor por defecto de 20. Si no se define, usa messages.groupChat.historyLimit. Puedes usar 0 para desactivarlo.
Historial de DM: Controlado por channels.discord.dmHistoryLimit o de forma específica por usuario con channels.discord.dms["<user_id>"].historyLimit.

En cuanto a los hilos, Discord los gestiona como sesiones de canal. Los metadatos del hilo padre se usan para vincular sesiones. Además, la configuración del hilo hereda la del canal padre a menos que definas una específica para el hilo. Ten en cuenta que los Channel topics se inyectan como contexto untrusted (no como system prompt).

Notificaciones de reacciones

Puedes configurar cómo el bot reacciona a los emojis por cada Guild. Los eventos de reacción se transforman en eventos del sistema vinculados a la sesión de Discord.

Modos disponibles:

off
own (por defecto)
all
allowlist (utiliza la lista en guilds.<id>.users)

Config writes

Por defecto, las escrituras de configuración iniciadas desde un canal están activas. Esto permite usar flujos como /config set|unset. Si prefieres bloquear esto por seguridad, usa este snippet:

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

Soporte para PluralKit

Si tu comunidad utiliza PluralKit, puedes mapear los mensajes enviados por proxies a la identidad de los miembros del sistema.

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // opcional; necesario para sistemas privados
      },
    },
  },
}

Puntos clave de PluralKit:

Las allowlists pueden usar el formato pk:<memberId>.
El sistema busca coincidencias por nombre o slug.
Las búsquedas usan el ID del mensaje original y están limitadas por tiempo.
Si la búsqueda falla, los mensajes se tratan como mensajes de bot y se ignoran, a menos que configures allowBots=true.

Exec approvals en Discord

Puedes gestionar aprobaciones de ejecución mediante botones directamente en los DMs de Discord.

Rutas de configuración:

channels.discord.execApprovals.enabled
channels.discord.execApprovals.approvers
Opciones adicionales: agentFilter, sessionFilter, cleanupAfterResolve.

Solución de problemas

IDs de aprobación desconocidos: Si las aprobaciones fallan con errores de ID, verifica que el usuario esté en la lista de approvers y que la feature esté habilitada.
Mensajes de proxy ignorados: Si los mensajes de PluralKit no aparecen, asegúrate de que el token sea correcto (para sistemas privados) o activa allowBots=true para evitar que se descarten.
El historial no carga: Revisa si historyLimit está en 0 o si el bot tiene permisos para leer el historial de mensajes en el canal.
Respuestas sin tag: Verifica que replyToMode no esté en off y que el agent esté enviando el tag [[reply_to_current]] correctamente.

Para resolver dudas específicas sobre tu implementación, consulta al AI Setup Assistant.

Próximos pasos

Gestionar las interacciones de un bot puede volverse un caos rápidamente. A veces solo quieres que tu herramienta envíe mensajes sin preocuparte por si tiene permisos para banear usuarios o cambiar estados por accidente. Configurar estos límites de forma clara es vital para mantener la seguridad de tu servidor y evitar ejecuciones no deseadas.

Recomiendo definir siempre los permisos mínimos necesarios. Es mejor activar funciones según las necesites que dejar todo abierto desde el principio.

What You’ll Need

Acceso a la configuración de channels.discord.actions.*
Conocimiento de los grupos de acciones de la API de Discord

Quick Start

Las acciones de Discord incluyen mensajería, administración de canales, moderación, presencia y acciones de metadatos. Estas funciones se agrupan en “gates” que controlan su ejecución.

Encontrarás estas configuraciones bajo el path channels.discord.actions.*. Aquí tienes los ejemplos principales de lo que puedes ejecutar:

Messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
Reactions: react, reactions, emojiList
Moderation: timeout, kick, ban
Presence: setPresence

Por defecto, el comportamiento de los action gates varía según el grupo. Revisa esta tabla para saber qué está disponible de inmediato:

Grupo de acción	Estado por defecto
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

Troubleshooting

Problema: Las acciones de moderación o gestión de roles no se ejecutan.
Solución: Verifica el estado del gate. Por defecto, los grupos roles, moderation y presence están configurados como disabled. Debes cambiarlos a enabled en tu configuración para que funcionen.
Problema: Error al intentar usar setPresence.
Solución: Este comando pertenece al grupo presence, el cual viene desactivado por defecto. Asegúrate de habilitar el gate correspondiente en el path de la API.

Si necesitas ayuda con la configuración técnica, consulta al AI Setup Assistant.

What’s Next

Seguro te ha pasado: configuras tu bot, lanzas el Gateway y, de repente, el silencio es total. No responde a los mensajes, los permisos parecen no aplicarse o simplemente los eventos no llegan a tu terminal. Es frustrante cuando el código está bien pero la comunicación con la API de Discord falla por un detalle técnico invisible.

Aquí tienes los pasos directos para identificar por qué tu bot no se está comportando como debería y cómo arreglarlo sin perder tiempo.

Requisitos previos

Para seguir esta guía, asegúrate de tener:

El token de tu bot de Discord.
CLI de openclaw instalado.
Acceso al archivo de configuración de tu Gateway.

Inicio rápido

Si tienes problemas, usa estas herramientas de diagnóstico rápido para encontrar el fallo en menos de 5 minutos:

Diagnóstico general y logs: Ejecuta openclaw doctor para revisar el estado del sistema. Si necesitas ver qué pasa en tiempo real, usa openclaw logs --follow.
Prueba de canales: Usa el comando openclaw channels status --probe para verificar si el Gateway puede ver y acceder a los canales configurados.

Si realizas cambios en los intents en el portal de desarrolladores de Discord, recuerda que es obligatorio reiniciar el Gateway para que los cambios surtan efecto.

Solución de problemas

Intents no permitidos o el bot no ve mensajes

Activa el Message Content Intent en el portal de Discord.
Activa el Server Members Intent si tu lógica depende de la resolución de usuarios o miembros.
Reinicia el Gateway después de modificar cualquier intent.

Mensajes de Guild bloqueados inesperadamente

Verifica el valor de groupPolicy.
Revisa la allowlist de guilds en channels.discord.guilds.
Si existe un mapa de channels definido, el Gateway solo permitirá los canales que estén listados ahí.
Comprueba el comportamiento de requireMention y los patrones de mención configurados.

Puedes usar estos comandos para verificar la configuración:

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

requireMention es false pero sigue bloqueado

Causas comunes:

Tienes groupPolicy="allowlist" pero no hay una coincidencia en la allowlist de guild o canal.
El parámetro requireMention está en el lugar equivocado (debe estar bajo channels.discord.guilds o en la entrada específica del canal).
El remitente está bloqueado por la allowlist de users del guild o canal.

Errores en la auditoría de permisos

Los chequeos de permisos de channels status --probe solo funcionan con IDs de canal numéricos. Si usas slug keys, el emparejamiento en runtime funcionará, pero el comando probe no podrá verificar los permisos totalmente.

Problemas con DM y pairing

Revisa si los DM están desactivados: channels.discord.dm.enabled=false.
Verifica si la política de DM es channels.discord.dm.policy="disabled".
Si usas el modo pairing, asegúrate de que no estás esperando una aprobación de emparejamiento.

Bucles de bot a bot

Por defecto, los mensajes escritos por bots son ignorados. Si decides activar channels.discord.allowBots=true, asegúrate de usar reglas de mención y allowlists estrictas para evitar comportamientos de bucle infinito.

Configuration reference pointers

Referencia principal:

Configuration reference - Discord

Campos de alta prioridad en Discord:

Startup/Auth: enabled, token, accounts.*, allowBots
Policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
Command: commands.native, commands.useAccessGroups, configWrites
Reply/History: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
Delivery: textChunkLimit, chunkMode, maxLinesPerMessage
Media/Retry: mediaMaxMb, retry
Actions: actions.*
Features: pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Safety and operations

Maneja los tokens de tu bot como secretos. Es preferible usar DISCORD_BOT_TOKEN en entornos supervisados.
Otorga siempre el principio de menor privilegio en los permisos de Discord.
Si el estado de despliegue de los comandos parece desactualizado, reinicia el Gateway y verifica de nuevo con openclaw channels status --probe.

¿Necesitas ayuda personalizada con tu configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.