OpenClaw
Integraciones12 min de lectura

Integración de OpenClaw con Discord: Configuración del Bot y Gateway Intents Explicados

Guía completa para crear un bot de Discord para OpenClaw, entender los Gateway Intents, configurar las políticas de seguridad de mensajes directos y establecer el control de acceso en canales de servidor.

O

OpenClaw Guides

Tutorial Authors

Descripción General

La integración con Discord te permite chatear con OpenClaw a través de un bot de Discord, con soporte tanto para comunicación por DM (mensaje directo) como por canales de texto en servidores. Esta guía cubre la creación de un bot, la comprensión de los Gateway Intents, la configuración de las políticas de seguridad de DM y el establecimiento del control de acceso en canales de servidor, todo basado en la documentación oficial de OpenClaw.

Requisitos Previos

  • OpenClaw instalado y en ejecución
  • Una cuenta de Discord
  • Un servidor de Discord donde tengas permisos de administrador (para pruebas)

Cómo Funciona

Antes de comenzar, es útil entender cómo OpenClaw enruta los mensajes de Discord:

  • Las conversaciones por DM se agrupan en una sesión compartida (agent:main:main) con seguridad basada en emparejamiento por defecto.
  • Las conversaciones en canales de servidor están aisladas por canal, utilizando el patrón agent:<agentId>:discord:channel:<channelId>.
  • Los DM grupales se ignoran por defecto, pero se pueden habilitar mediante channels.discord.dm.groupEnabled.

El gateway se inicia automáticamente cuando existe un token válido y enabled no es false.

Paso 1: Crear una Aplicación de Discord

Ve al Portal de Desarrolladores de Discord

  1. Visita el Portal de Desarrolladores de Discord
  2. Haz clic en New Application
  3. Ingresa un nombre (ej., "OpenClaw Assistant")
  4. Haz clic en Create

Configura el Bot

  1. En tu aplicación, ve a la pestaña Bot
  2. Haz clic en Add Bot → Yes, do it!
  3. En Token, haz clic en Copy para copiar el token de tu bot

Importante: Trata el token de tu bot como una contraseña. Nunca lo compartas públicamente. Si queda expuesto, regeneralo inmediatamente.

Paso 2: Habilitar los Gateway Intents Privilegiados

Los Gateway Intents controlan qué eventos recibe tu bot de Discord. OpenClaw requiere intents privilegiados específicos para funcionar correctamente.

Intents Requeridos

| Intent | Propósito | Requerido | |--------|-----------|-----------| | Message Content Intent | Leer el texto de mensajes en canales de servidor | Requerido — sin él, el bot muestra errores de "Used disallowed intents" o se conecta pero no responde | | Server Members Intent | Búsqueda de miembros y coincidencia con listas de permitidos | Recomendado — necesario para el control de acceso basado en listas de permitidos |

Habilitar los Intents en el Portal de Desarrolladores

  1. Ve a la pestaña Bot en el Portal de Desarrolladores
  2. Desplázate hasta Privileged Gateway Intents
  3. Habilita MESSAGE CONTENT INTENT (obligatorio)
  4. Habilita SERVER MEMBERS INTENT (recomendado)
  5. Haz clic en Save Changes

Nota: Los bots en más de 100 servidores necesitan verificación de Discord para usar intents privilegiados.

Paso 3: Generar la URL de Invitación del Bot

Configurar OAuth2

  1. Ve a OAuth2 → URL Generator

  2. Selecciona los scopes:

    • bot
    • applications.commands (requerido para comandos slash nativos)

  3. Selecciona los permisos del bot:

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

Advertencia: Evita otorgar permisos de Administrator a menos que estés depurando activamente. Concede solo lo necesario.

  1. Copia la URL generada

Invitar al Bot

  1. Abre la URL en tu navegador
  2. Selecciona tu servidor de prueba
  3. Haz clic en Authorize

Obtener los IDs Numéricos

Habilita el Developer Mode en Discord (Ajustes de Usuario → Configuración de la App → Avanzado → Developer Mode) para poder hacer clic derecho y copiar los IDs de servidor, canal y usuario, ya que los necesitarás para la configuración.

Paso 4: Configurar OpenClaw

Opción A: Variable de Entorno

Establece el token como variable de entorno:

bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

Opción B: Archivo de Configuración

Edita tu archivo de configuración de OpenClaw con el token directamente:

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

Nota: Cuando existen tanto una variable de entorno como un token en el archivo de configuración, el archivo de configuración tiene prioridad.

Opción C: Soporte Multi-Cuenta

Para ejecutar múltiples cuentas de bot:

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

Paso 5: Iniciar y Probar

Inicia o reinicia el gateway de OpenClaw:

bash
openclaw gateway restart

Verifica el estado del canal:

bash
openclaw channels status --probe

Ejecuta diagnósticos si algo parece estar mal:

bash
openclaw doctor

Para el primer contacto por DM, el bot utiliza un sistema de emparejamiento por defecto: el remitente recibe un código con tiempo limitado (expira en 1 hora) que debe ser aprobado antes de que comience la conversación.

Políticas de Seguridad de DM

OpenClaw ofrece tres políticas de control de acceso para DM:

Emparejamiento (Por Defecto)

Los remitentes desconocidos reciben un código de emparejamiento con tiempo limitado que expira después de 1 hora. El código debe ser aprobado antes de que la conversación pueda continuar.

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

Lista de Permitidos

Solo los IDs de usuario o nombres de usuario configurados pueden enviar DMs:

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

Abierto

Cualquiera puede enviar DMs (usar con precaución):

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

Configuración de Canales de Servidor

Control de Acceso Básico por Servidor

Restringe el bot a servidores y canales específicos con requisitos de mención:

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

Importante: requireMention debe configurarse a nivel de servidor o de canal, no en la configuración de nivel superior de Discord.

Configuración por Canal

Puedes configurar listas de permitidos y restricciones de habilidades por canal:

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

Parámetros de Configuración

Configuración de Mensajes

| Parámetro | Por Defecto | Descripción | |-----------|-------------|-------------| | textChunkLimit | 2000 | Máximo de caracteres por fragmento de mensaje saliente | | chunkMode | — | Configurar para dividir en líneas en blanco (límites de párrafo) antes de aplicar límites de longitud | | maxLinesPerMessage | 17 | Máximo de líneas por mensaje | | mediaMaxMb | 8 | Tamaño máximo de archivo multimedia en MB |

Historial de Contexto

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

Hilos de Respuesta

Los hilos de respuesta nativos están desactivados por defecto. Habilítalos con:

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

Usa etiquetas de respuesta en las respuestas del agente para controlar el comportamiento de los hilos:

  • [[reply_to_current]] — responder al mensaje que se está procesando
  • [[reply_to:<message_id>]] — responder a un mensaje específico

Notificaciones de Reacciones

Configura las notificaciones de eventos de reacción por servidor:

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

Acciones de Herramientas

El agente puede invocar una herramienta discord para realizar acciones dentro de Discord. La mayoría de las acciones están habilitadas por defecto, excepto roles y moderación, que están deshabilitados por defecto.

Acciones Disponibles

| Categoría | Acciones | |-----------|----------| | Reacciones | react, sticker, poll | | Mensajes | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | Hilos | threadCreate, threadList, threadReply | | Fijados | pinMessage, unpinMessage, listPins | | Canales | channelInfo, channelList | | Miembros | memberInfo, roleInfo, permissions | | Roles | roleAdd, roleRemove (deshabilitado por defecto) | | Moderación | timeout, kick, ban (deshabilitado por defecto) | | Otros | emojiList, voiceStatus, eventList, eventCreate, setPresence |

Funciones Avanzadas

Soporte de PluralKit

Cuando está habilitado, OpenClaw resuelve los mensajes proxy a los miembros subyacentes del sistema, mostrando los remitentes como "Member (PK:System)" para evitar menciones accidentales en Discord.

Interfaz de Botones de Aprobación de Ejecución

En conversaciones por DM, OpenClaw puede presentar botones de aprobación de ejecución para la confirmación interactiva de acciones de herramientas.

Configuración de Reintentos

Las llamadas API salientes reintentan automáticamente en caso de límites de tasa usando el encabezado retry_after de Discord con retroceso exponencial. Configura el comportamiento de reintentos mediante los parámetros de channels.discord.retry.

Solución de Problemas

El Bot Está En Línea Pero No Responde

  1. Verifica el Message Content Intent: Sin este intent, el bot se conecta pero no puede leer el texto de los mensajes. Ve al Portal de Desarrolladores → Bot → Privileged Gateway Intents y asegúrate de que MESSAGE CONTENT INTENT esté habilitado.

  2. Verifica los permisos del canal: Asegúrate de que el bot tenga los permisos View Channels y Send Messages en el canal objetivo.

  3. Verifica los requisitos de mención: Si requireMention está habilitado para el servidor o canal, debes @mencionar al bot.

  4. Verifica las listas de permitidos del servidor/canal: Comprueba que el canal no esté bloqueado por la configuración de listas de permitidos.

Error "Used Disallowed Intents"

Esto significa que los intents requeridos no están habilitados en el Portal de Desarrolladores:

  1. Ve al Portal de Desarrolladores → Bot → Privileged Gateway Intents
  2. Habilita MESSAGE CONTENT INTENT
  3. Guarda y reinicia el gateway de OpenClaw

Los DMs No Funcionan

  1. Verifica que dm.enabled no esté configurado como false
  2. Revisa la política de DM — si está configurada como "allowlist", asegúrate de que el ID del usuario esté incluido
  3. Si usas la política "pairing", verifica si el código de emparejamiento ha expirado (límite de 1 hora)

Comandos de Diagnóstico

Usa las herramientas de diagnóstico integradas para identificar problemas:

bash
# Run full diagnostics
openclaw doctor

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

Mejores Prácticas

  1. Trata los tokens del bot como contraseñas — usa variables de entorno en hosts supervisados, nunca incluyas tokens en el control de versiones.
  2. Concede solo los permisos necesarios — evita Administrator a menos que estés depurando activamente.
  3. Usa las políticas de DM de emparejamiento o lista de permitidos — la política "open" solo debe usarse para bots públicos con limitación de tasa adecuada.
  4. Habilita el Server Members Intent si usas control de acceso basado en listas de permitidos para una coincidencia de miembros más confiable.
  5. Usa requireMention en servidores concurridos para evitar que el bot responda a todos los mensajes.
  6. Reinicia el gateway con --force si se queda atascado: openclaw gateway restart --force.

Siguientes Pasos