Ir al contenido
OpenClaw Docs

Discord

Discord (Bot API)

Sección titulada «Discord (Bot API)»

Estado: listo para mensajes directos y canales de servidor a través de la puerta de enlace oficial de Discord.

Emparejamiento

Los MD de Discord están en modo de emparejamiento por defecto.

Comandos de barra

Comportamiento de comandos nativos y catálogo de comandos.

Solución de problemas del canal

Flujo de diagnóstico y reparación entre canales.

Configuración rápida

Sección titulada «Configuración rápida»

Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servidor y emparejarlo con OpenClaw. Recomendamos añadir tu bot a tu propio servidor privado. Si aún no tienes uno, crea uno primero (elige Crear el mío > Para mí y mis amigos).

  1. Crear una aplicación y un bot de Discord

    Ve al Portal para Desarrolladores de Discord y haz clic en Nueva Aplicación. Ponle un nombre como “OpenClaw”.

    Haz clic en Bot en la barra lateral. Establece el Nombre de usuario a como llames a tu agente de OpenClaw.

  2. Habilitar intents privilegiados

    Aún en la página Bot, desplázate hacia abajo hasta Intents de Gateway Privilegiados y habilita:

    • Intent de Contenido de Mensajes (requerido)
    • Intent de Miembros del Servidor (recomendado; requerido para listas de permitidos de roles y coincidencia de nombre con ID)
    • Intent de Presencia (opcional; solo necesario para actualizaciones de presencia)

  3. Copiar el token de tu bot

    Vuelve a desplazarte hacia arriba en la página Bot y haz clic en Restablecer Token.

    Copia el token y guárdalo en algún lugar. Este es tu Token de Bot y lo necesitarás en breve.

  4. Generate an invite URL and add the bot to your server

    Haz clic en OAuth2 en la barra lateral. Generarás una URL de invitación con los permisos adecuados para añadir el bot a tu servidor.

    Desplázate hacia abajo hasta OAuth2 URL Generator (Generador de URL de OAuth2) y habilita:

    • bot
    • applications.commands

    Aparecerá abajo una sección de Bot Permissions (Permisos de bot). Habilita:

    • Ver canales
    • Enviar mensajes
    • Leer el historial de mensajes
    • Incrustar enlaces
    • Adjuntar archivos
    • Añadir reacciones (opcional)

    Copia la URL generada en la parte inferior, pégala en tu navegador, selecciona tu servidor y haz clic en Continue (Continuar) para conectar. Ahora deberías ver tu bot en el servidor de Discord.

  5. Enable Developer Mode and collect your IDs

    De vuelta en la aplicación de Discord, debes habilitar el Modo de desarrollador para poder copiar los IDs internos.

    1. Haz clic en User Settings (Configuración de usuario, icono de engranaje junto a tu avatar) → Advanced (Avanzado) → activa Developer Mode (Modo de desarrollador)
    2. Haz clic derecho en el icono de tu servidor en la barra lateral → Copy Server ID (Copiar ID del servidor)
    3. Haz clic derecho en tu propio avatar → Copy User ID (Copiar ID de usuario)

    Guarda tu ID de servidor y tu ID de usuario junto a tu Token de bot — enviarás los tres a OpenClaw en el siguiente paso.

  6. Allow DMs from server members

    Para que el emparejamiento funcione, Discord necesita permitir que tu bot te envíe mensajes directos. Haz clic derecho en el icono de tu servidor → Privacy Settings (Configuración de privacidad) → activa Direct Messages (Mensajes directos).

    Esto permite que los miembros del servidor (incluidos los bots) te envíen mensajes directos. Mantén esto habilitado si deseas usar los mensajes directos de Discord con OpenClaw. Si solo planeas usar canales del servidor, puedes deshabilitar los mensajes directos después del emparejamiento.

  7. Set your bot token securely (do not send it in chat)

    El token de tu bot de Discord es un secreto (como una contraseña). Establécelo en la máquina que ejecuta OpenClaw antes de enviar mensajes a tu agente.
    Ventana de terminal
    export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
    openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
    openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
    openclaw config set channels.discord.enabled true --strict-json
    openclaw gateway
    Si OpenClaw ya se está ejecutando como un servicio en segundo plano, reinícialo a través de la aplicación Mac de OpenClaw o deteniendo y reiniciando el proceso `openclaw gateway run`.

  8. Configurar OpenClaw y emparejar

    Chatea con tu agente de OpenClaw en cualquier canal existente (por ejemplo, Telegram) e indícale lo siguiente. Si Discord es tu primer canal, usa la pestaña CLI / config en su lugar.

    “Ya configuré mi token de bot de Discord en la configuración. Por favor, termina la configuración de Discord con el ID de Usuario `

    y el ID de Servidor

    `.”

  9. Aprobar primer emparejamiento DM

    Espere hasta que la puerta de enlace se esté ejecutando y luego envíe un mensaje privado (DM) a su bot en Discord. Responderá con un código de emparejamiento.

    Envíe el código de emparejamiento a su agente en su canal existente:

    “Apruebe este código de emparejamiento de Discord: `

    `”

    Los códigos de emparejamiento caducan después de 1 hora.

    Ahora debería poder chatear con su agente en Discord mediante DM.

Recomendado: Configurar un espacio de trabajo de servidor (guild)

Sección titulada «Recomendado: Configurar un espacio de trabajo de servidor (guild)»

Una vez que los DM funcionen, puede configurar su servidor de Discord como un espacio de trabajo completo donde cada canal obtenga su propia sesión de agente con su propio contexto. Esto se recomienda para servidores privados donde solo está usted y su bot.

  1. Añade tu servidor a la lista de permitidos del gremio

    Esto permite que tu agente responda en cualquier canal de tu servidor, no solo en mensajes directos.

    “Añade mi ID de Servidor de Discord `

    ` a la lista de permitidos del gremio”

  2. Permitir respuestas sin @mención

    De forma predeterminada, tu agente solo responde en los canales del gremio cuando se le @menciona. Para un servidor privado, probablemente quieras que responda a cada mensaje.

    “Permite que mi agente responda en este servidor sin tener que ser @mencionado”

  3. Planificar la memoria en los canales del gremio

    De forma predeterminada, la memoria a largo plazo (MEMORY.md) solo se carga en sesiones de mensajes directos. Los canales del gremio no cargan automáticamente MEMORY.md.

    “Cuando haga preguntas en los canales de Discord, usa memory_search o memory_get si necesitas contexto a largo plazo de MEMORY.md.”

Ahora crea algunos canales en tu servidor de Discord y comienza a chatear. Tu agente puede ver el nombre del canal y cada canal tiene su propia sesión aislada, por lo que puedes configurar #coding, #home, #research o lo que se adapte a tu flujo de trabajo.

Modelo de tiempo de ejecución

Sección titulada «Modelo de tiempo de ejecución»
  • Gateway es el propietario de la conexión de Discord.
  • El enrutamiento de respuestas es determinista: las respuestas entrantes de Discord se devuelven a Discord.
  • Por defecto (session.dmScope=main), los chats directos comparten la sesión principal del agente (agent:main:main).
  • Los canales de servidor son claves de sesión aisladas (agent:<agentId>:discord:channel:<channelId>).
  • Los mensajes directos grupales se ignoran por defecto (channels.discord.dm.groupEnabled=false).
  • Los comandos nativos de barra diagonal se ejecutan en sesiones de comando aisladas (agent:<agentId>:discord:slash:<userId>), mientras que aún transportan CommandTargetSessionKey a la sesión de conversación enrutada.

Canales del foro

Sección titulada «Canales del foro»

Los canales de foro y medios de Discord solo aceptan publicaciones de hilos. OpenClaw admite dos formas de crearlos:

  • Envía un mensaje al foro principal (channel:<forumId>) para crear un hilo automáticamente. El título del hilo usa la primera línea no vacía de tu mensaje.
  • Usa openclaw message thread create para crear un hilo directamente. No pases --message-id para canales de foro.

Ejemplo: enviar al padre del foro para crear un hilo

Ventana de terminal
openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

Ejemplo: crear explícitamente un hilo de foro

Ventana de terminal
openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

Los foros principales no aceptan componentes de Discord. Si necesitas componentes, envía al hilo en sí (channel:<threadId>).

Componentes interactivos

Sección titulada «Componentes interactivos»

OpenClaw soporta contenedores de componentes de Discord v2 para mensajes de agente. Usa la herramienta de mensaje con un payload components. Los resultados de las interacciones se enrutan de vuelta al agente como mensajes entrantes normales y siguen la configuración existente de replyToMode de Discord.

Bloques admitidos:

  • text, section, separator, actions, media-gallery, file
  • Las filas de acciones permiten hasta 5 botones o un menú de selección único
  • Tipos de selección: string, user, role, mentionable, channel

Por defecto, los componentes son de un solo uso. Establece components.reusable=true para permitir que los botones, selecciones y formularios se usen varias veces hasta que expiren.

Para restringir quién puede hacer clic en un botón, establece allowedUsers en ese botón (IDs de usuario de Discord, etiquetas o *). Cuando se configura, los usuarios que no coinciden reciben una denegación efímera.

Los comandos de barra diagonal /model y /models abren un selector de modelo interactivo con menús desplegables de proveedor y modelo además de un paso Enviar. La respuesta del selector es efímera y solo el usuario que lo invoca puede usarla.

Archivos adjuntos:

  • los bloques file deben apuntar a una referencia de adjunto (attachment://<filename>)
  • Proporcione el adjunto a través de media/path/filePath (archivo único); use media-gallery para varios archivos
  • Use filename para anular el nombre de carga cuando deba coincidir con la referencia del adjunto

Formularios modales:

  • Añada components.modal con hasta 5 campos
  • Tipos de campo: text, checkbox, radio, select, role-select, user-select
  • OpenClaw añade automáticamente un botón de activación

Ejemplo:

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

Control de acceso y enrutamiento

Sección titulada «Control de acceso y enrutamiento»

channels.discord.dmPolicy controla el acceso a MD (legado: channels.discord.dm.policy):

  • pairing (predeterminado)
  • allowlist
  • open (requiere que channels.discord.allowFrom incluya "*"; legado: channels.discord.dm.allowFrom)
  • disabled

Si la política de MD no está abierta, los usuarios desconocidos están bloqueados (o se les solicita emparejamiento en el modo pairing).

Precedencia de cuentas múltiples:

  • channels.discord.accounts.default.allowFrom se aplica solo a la cuenta default.
  • Las cuentas con nombre heredan channels.discord.allowFrom cuando su propia allowFrom no está establecida.
  • Las cuentas con nombre no heredan channels.discord.accounts.default.allowFrom.

Formato de destino de MD para entrega:

  • `user:

- mención<@id>`

Los IDs numéricos simples son ambiguos y se rechazan a menos que se proporcione un tipo de destino de usuario/canal explícito.

Enrutamiento de agentes basado en roles

Sección titulada «Enrutamiento de agentes basado en roles»

Use bindings[].match.roles para enrutar a los miembros del gremio de Discord a diferentes agentes por ID de rol. Los enlaces basados en roles aceptan solo IDs de roles y se evalúan después de los enlaces peer o parent-peer y antes de los enlaces solo de gremio. Si un enlace también establece otros campos de coincidencia (por ejemplo peer + guildId + roles), todos los campos configurados deben coincidir.

{
  bindings: [
    {
      agentId: "opus",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
        roles: ["111111111111111111"],
      },
    },
    {
      agentId: "sonnet",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
      },
    },
  ],
}

Configuración del Portal para Desarrolladores

Sección titulada «Configuración del Portal para Desarrolladores»
Crear aplicación y bot
  1. Discord Developer Portal -> Applications -> New Application
  2. Bot -> Add Bot
  3. Copiar token del bot
Intents privilegiados

En Bot -> Privileged Gateway Intents, habilite:

  • Message Content Intent
  • Server Members Intent (recomendado)

El intent de presencia es opcional y solo se requiere si desea recibir actualizaciones de presencia. Configurar la presencia del bot (setPresence) no requiere habilitar las actualizaciones de presencia para los miembros.

Ámbitos OAuth y permisos base

Generador de URL OAuth:

  • ámbitos: bot, applications.commands

Permisos base típicos:

  • Ver canales
  • Enviar mensajes
  • Ver historial de mensajes
  • Incrustar enlaces
  • Adjuntar archivos
  • Añadir reacciones (opcional)

Evite Administrator a menos que sea explícitamente necesario.

Copiar IDs

Activa el modo de desarrollador de Discord y luego copia:

  • ID del servidor
  • ID del canal
  • ID del usuario

Se prefieren los IDs numéricos en la configuración de OpenClaw para auditorías y sondas confiables.

Comandos nativos y autenticación de comandos

Sección titulada «Comandos nativos y autenticación de comandos»
  • commands.native por defecto es "auto" y está habilitado para Discord.
  • Anulación por canal: channels.discord.commands.native.
  • commands.native=false borra explícitamente los comandos nativos de Discord registrados anteriormente.
  • La autenticación de comandos nativos utiliza las mismas listas de permitidos/políticas de Discord que el manejo normal de mensajes.
  • Es posible que los comandos sigan siendo visibles en la interfaz de usuario de Discord para usuarios que no están autorizados; la ejecución aún hace cumplir la autenticación de OpenClaw y devuelve “no autorizado”.

Consulte Slash commands para ver el catálogo de comandos y el comportamiento.

Configuración predeterminada de comandos de barra:

  • ephemeral: true

Detalles de la función

Sección titulada «Detalles de la función»
Etiquetas de respuesta y respuestas nativas

Discord admite etiquetas de respuesta en la salida del agente:

  • [[reply_to_current]]
  • `[[reply_to:

]]`

Controlado por `channels.discord.replyToMode`:


- `off` (predeterminado)
- `first`
- `all`


Nota: `off` desactiva el hilado implícito de respuestas. Las etiquetas explícitas `[[reply_to_*]]` aún se respetan.


Los IDs de mensaje se muestran en el contexto/historial para que los agentes puedan apuntar a mensajes específicos.
Vista previa de transmisión en vivo
OpenClaw puede transmitir respuestas de borrador enviando un mensaje temporal y editándolo a medida que llega el texto.


- `channels.discord.streaming` controla la transmisión de vista previa (`off` | `partial` | `block` | `progress`, por defecto: `off`).
- El valor predeterminado sigue siendo `off` porque las ediciones de vista previa de Discord pueden alcanzar rápidamente los límites de velocidad, especialmente cuando varios bots o puertas de enlace comparten la misma cuenta o el tráfico del gremio.
- `progress` se acepta para la coherencia entre canales y se asigna a `partial` en Discord.
- `channels.discord.streamMode` es un alias heredado y se migra automáticamente.
- `partial` edita un único mensaje de vista previa a medida que llegan los tokens.
- `block` emite fragmentos del tamaño de un borrador (use `draftChunk` para ajustar el tamaño y los puntos de interrupción).


Ejemplo:
{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}
Valores predeterminados de fragmentación del modo `block` (limitados a `channels.discord.textChunkLimit`):
{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}
La transmisión de vista previa es solo de texto; las respuestas multimedia vuelven a la entrega normal.


Nota: la transmisión de vista previa es independiente de la transmisión de bloques. Cuando la transmisión de bloques está explícitamente habilitada para Discord, OpenClaw omite la transmisión de vista previa para evitar la doble transmisión.
Historial, contexto y comportamiento de los hilos

Contexto del historial del gremio:

  • channels.discord.historyLimit por defecto 20
  • alternativa: messages.groupChat.historyLimit
  • 0 deshabilita

Controles del historial de MD:

  • channels.discord.dmHistoryLimit
  • `channels.discord.dms[”

“].historyLimit`

Comportamiento de los hilos:


- Los hilos de Discord se enrutan como sesiones de canal
- los metadatos del hilo principal se pueden usar para la vinculación de la sesión principal
- la configuración del hilo hereda la configuración del canal principal a menos que exista una entrada específica del hilo


Los temas del canal se inyectan como contexto **no confiable** (no como mensaje del sistema).
Thread-bound sessions for subagents

Discord puede vincular un hilo a un destino de sesión de modo que los mensajes de seguimiento en ese hilo sigan enrutándose a la misma sesión (incluidas las sesiones de subagente).

Comandos:

  • `/focus

vincular el hilo actual/nuevo a un destino de subagente/sesión -/unfocuseliminar la vinculación del hilo actual -/agentsmostrar las ejecuciones activas y el estado de vinculación -/session idle

inspeccionar/actualizar la auto-desactivación por inactividad para vinculaciones enfocadas -/session max-age

` inspeccionar/actualizar la antigüedad máxima estricta para vinculaciones enfocadas

Configuración:
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in
      },
    },
  },
}
Notas:


- `session.threadBindings.*` establece los valores predeterminados globales.
- `channels.discord.threadBindings.*` anula el comportamiento de Discord.
- `spawnSubagentSessions` debe ser verdadero para crear/vincular automáticamente hilos para `sessions_spawn({ thread: true })`.
- `spawnAcpSessions` debe ser verdadero para crear/vincular automáticamente hilos para ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`).
- Si las vinculaciones de hilos están deshabilitadas para una cuenta, `/focus` y las operaciones de vinculación de hilos relacionadas no están disponibles.


Consulte [Sub-agentes](/en/tools/subagents), [Agentes ACP](/en/tools/acp-agents) y [Referencia de configuración](/en/gateway/configuration-reference).
Vínculos de canal ACP persistentes
Para espacios de trabajo ACP "siempre activos" estables, configure vínculos ACP escritos de nivel superior que apunten a conversaciones de Discord.


Ruta de configuración:


- `bindings[]` con `type: "acp"` y `match.channel: "discord"`


Ejemplo:
{
  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,
            },
          },
        },
      },
    },
  },
}
Notas:


- `/acp spawn codex --bind here` vincula el canal o hilo de Discord actual en su lugar y mantiene los mensajes futuros enrutados a la misma sesión ACP.
- Eso aún puede significar "iniciar una sesión nueva de Codex ACP", pero no crea un nuevo hilo de Discord por sí mismo. El canal existente sigue siendo la superficie de chat.
- Codex aún puede ejecutarse en su propio `cwd` o espacio de trabajo de backend en disco. Ese espacio de trabajo es el estado de ejecución, no un hilo de Discord.
- Los mensajes de los hilos pueden heredar el vínculo ACP del canal principal.
- En un canal o hilo vinculado, `/new` y `/reset` restablecen la misma sesión ACP en su lugar.
- Los vínculos temporales de hilos aún funcionan y pueden anular la resolución del objetivo mientras estén activos.
- `spawnAcpSessions` solo se requiere cuando OpenClaw necesita crear/vincular un hilo secundario a través de `--thread auto|here`. No se requiere para `/acp spawn ... --bind here` en el canal actual.


Consulte [Agentes ACP](/en/tools/acp-agents) para obtener detalles sobre el comportamiento de vinculación.
Notificaciones de reacción

Modo de notificación de reacción por servidor:

  • off
  • own (predeterminado)
  • all
  • allowlist (usa `guilds.

.users`)

Los eventos de reacción se convierten en eventos del sistema y se adjuntan a la sesión de Discord enrutada.
Ack reactions

ackReaction envía un emoji de reconocimiento mientras OpenClaw procesa un mensaje entrante.

Orden de resolución:

  • `channels.discord.accounts.

.ackReaction -channels.discord.ackReaction -messages.ackReaction - respaldo de emoji de identidad del agente (agents.list[].identity.emoji`, si no, ”👀”)

Notas:


- Discord acepta emoji unicode o nombres de emoji personalizados.
- Use `""` para desactivar la reacción para un canal o cuenta.
Config writes
Las escrituras de configuración iniciadas por el canal están habilitadas por defecto.


Esto afecta a los flujos de `/config set|unset` (cuando las funciones de comandos están habilitadas).


Desactivar:
{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}
Gateway proxy
Enrute el tráfico del WebSocket de la puerta de enlace de Discord y las búsquedas REST de inicio (ID de aplicación + resolución de lista blanca) a través de un proxy HTTP(S) con `channels.discord.proxy`.
{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}
Anulación por cuenta:
{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}
PluralKit support
Habilite la resolución de PluralKit para asignar mensajes con proxy a la identidad del miembro del sistema:
{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}
Notas:


- las listas blancas pueden usar `pk:

- los nombres para mostrar de los miembros coinciden por nombre/solo slug cuandochannels.discord.dangerouslyAllowNameMatching: true - las búsquedas usan el ID del mensaje original y están restringidas por una ventana de tiempo - si la búsqueda falla, los mensajes con proxy se tratan como mensajes del bot y se descartan a menos queallowBots=true`

Configuración de presencia
Las actualizaciones de presencia se aplican cuando estableces un campo de estado o actividad, o cuando habilitas la presencia automática.


Ejemplo de solo estado:
{
  channels: {
    discord: {
      status: "idle",
    },
  },
}
Ejemplo de actividad (el estado personalizado es el tipo de actividad predeterminado):
{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}
Ejemplo de transmisión:
{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}
Mapa de tipos de actividad:


- 0: Jugando
- 1: Transmitiendo (requiere `activityUrl`)
- 2: Escuchando
- 3: Viendo
- 4: Personalizado (usa el texto de actividad como estado; el emoji es opcional)
- 5: Compitiendo


Ejemplo de presencia automática (señal de salud de tiempo de ejecución):
{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}
La presencia automática asigna la disponibilidad de tiempo de ejecución al estado de Discord: healthy => en línea, degraded o unknown => ausente, exhausted o unavailable => no molestar. Opcionalmente se puede sobrescribir el texto:


- `autoPresence.healthyText`
- `autoPresence.degradedText`
- `autoPresence.exhaustedText` (soporta el marcador de posición `{reason}`)
Aprobaciones de ejecución en Discord

Discord admite aprobaciones de ejecución basadas en botones en MDs y, opcionalmente, puede publicar solicitudes de aprobación en el canal de origen.

Ruta de configuración:

  • channels.discord.execApprovals.enabled
  • channels.discord.execApprovals.approvers (opcional; recurre a los IDs de propietario inferidos de allowFrom y MD explícito defaultTo cuando sea posible)
  • channels.discord.execApprovals.target (dm | channel | both, predeterminado: dm)
  • agentFilter, sessionFilter, cleanupAfterResolve

Discord se convierte en un cliente de aprobación cuando enabled: true y al menos un aprobador se puede resolver, ya sea desde execApprovals.approvers o desde la configuración de propietario existente de la cuenta (allowFrom, dm.allowFrom heredado, o MD explícito defaultTo).

Cuando target es channel o both, la solicitud de aprobación es visible en el canal. Solo los aprobadores resueltos pueden usar los botones; otros usuarios reciben una denegación efímera. Las solicitudes de aprobación incluyen el texto del comando, por lo que solo habilite la entrega en el canal en canales de confianza. Si no se puede derivar el ID del canal de la clave de sesión, OpenClaw recurre a la entrega por MD.

Discord también representa los botones de aprobación compartidos que utilizan otros canales de chat. El adaptador nativo de Discord principalmente agrega el enrutamiento de MD del aprobador y la distribución en el canal.

La autenticación de Gateway para este controlador utiliza el mismo contrato de resolución de credenciales compartidas que otros clientes de Gateway:

  • autenticación local con prioridad de entorno (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD luego gateway.auth.*)
  • en modo local, gateway.remote.* se puede usar como alternativa solo cuando gateway.auth.* no está configurado; las referencias Secret locales configuradas pero no resueltas fallan de forma cerrada
  • soporte de modo remoto a través de gateway.remote.* cuando sea aplicable
  • las anulaciones de URL son seguras para la anulación: las anulaciones de CLI no reutilizan credenciales implícitas y las anulaciones de entorno usan solo credenciales de entorno

Las aprobaciones de ejecución caducan después de 30 minutos de forma predeterminada. Si las aprobaciones fallan con IDs de aprobación desconocidos, verifique la resolución del aprobador y la habilitación de funciones.

Documentos relacionados: Aprobaciones de ejecución

Herramientas y puertas de acción

Sección titulada «Herramientas y puertas de acción»

Las acciones de mensaje de Discord incluyen mensajería, administración de canales, moderación, presencia y acciones de metadatos.

Ejemplos principales:

  • mensajería: sendMessage, readMessages, editMessage, deleteMessage, threadReply
  • reacciones: react, reactions, emojiList
  • moderación: timeout, kick, ban
  • presencia: setPresence

Los “action gates” se encuentran en channels.discord.actions.*.

Comportamiento de la puerta predeterminado:

Grupo de accionesPredeterminado
reacciones, mensajes, hilos, fijados, encuestas, búsqueda, memberInfo, roleInfo, channelInfo, canales, voiceStatus, eventos, stickers, emojiUploads, stickerUploads, permisoshabilitado
rolesdeshabilitado
moderacióndeshabilitado
presenciadeshabilitado

Interfaz de usuario de componentes v2

Sección titulada «Interfaz de usuario de componentes v2»

OpenClaw utiliza componentes de Discord v2 para aprobaciones de ejecución y marcadores de contexto cruzado. Las acciones de mensajes de Discord también pueden aceptar components para UI personalizada (avanzado; requiere construir un “payload” de componente a través de la herramienta discord), mientras que los embeds heredados siguen disponibles pero no se recomiendan.

  • channels.discord.ui.components.accentColor establece el color de acento utilizado por los contenedores de componentes de Discord (hex).
  • Configurar por cuenta con channels.discord.accounts.<id>.ui.components.accentColor.
  • Se ignoran los embeds cuando están presentes los componentes v2.

Ejemplo:

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

Canales de voz

Sección titulada «Canales de voz»

OpenClaw puede unirse a canales de voz de Discord para conversaciones en tiempo real y continuas. Esto es independiente de los archivos adjuntos de mensajes de voz.

Requisitos:

  • Habilitar comandos nativos (commands.native o channels.discord.commands.native).
  • Configurar channels.discord.voice.
  • El bot necesita permisos de Conectar + Hablar en el canal de voz de destino.

Use el comando nativo exclusivo de Discord /vc join|leave|status para controlar las sesiones. El comando usa el agente predeterminado de la cuenta y sigue las mismas reglas de lista de permitidos y políticas de grupo que otros comandos de Discord.

Ejemplo de unión automática:

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

Notas:

  • voice.tts anula messages.tts solo para la reproducción de voz.
  • Los turnos de la transcripción de voz derivan el estado de propietario de los allowFrom de Discord (o dm.allowFrom); los hablantes que no son propietarios no pueden acceder a herramientas exclusivas para propietarios (por ejemplo gateway y cron).
  • La voz está habilitada de forma predeterminada; establezca channels.discord.voice.enabled=false para deshabilitarla.
  • voice.daveEncryption y voice.decryptionFailureTolerance se pasan a las opciones de unión de @discordjs/voice.
  • Los valores predeterminados de @discordjs/voice son daveEncryption=true y decryptionFailureTolerance=24 si no están establecidos.
  • OpenClaw también supervisa los fallos de desencriptación de recepción y se recupera automáticamente saliendo y volviendo a entrar al canal de voz después de fallos repetidos en una ventana corta de tiempo.
  • Si los registros de recepción muestran repetidamente DecryptionFailed(UnencryptedWhenPassthroughDisabled), esto puede ser el error de recepción @discordjs/voice de origen rastreado en discord.js #11419.

Mensajes de voz

Sección titulada «Mensajes de voz»

Los mensajes de voz de Discord muestran una vista previa de la forma de onda y requieren audio OGG/Opus más metadatos. OpenClaw genera la forma de onda automáticamente, pero necesita ffmpeg y ffprobe disponibles en el host de la puerta de enlace para inspeccionar y convertir archivos de audio.

Requisitos y restricciones:

  • Proporcione una ruta de archivo local (se rechazan las URL).
  • Omita el contenido de texto (Discord no permite texto + mensaje de voz en la misma carga útil).
  • Se acepta cualquier formato de audio; OpenClaw convierte a OGG/Opus cuando es necesario.

Ejemplo:

Ventana de terminal
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

Solución de problemas

Sección titulada «Solución de problemas»
Usó intents no permitidos o el bot no ve mensajes del gremio
  • habilitar Message Content Intent
  • habilitar Server Members Intent cuando dependas de la resolución de usuario/miembro
  • reiniciar la puerta de enlace después de cambiar los intents
Mensajes del gremio bloqueados inesperadamente
- verificar `groupPolicy`
- verificar la lista de permitidos del gremio bajo `channels.discord.guilds`
- si existe el mapa `channels` del gremio, solo se permiten los canales listados
- verificar el comportamiento de `requireMention` y los patrones de mención


Verificaciones útiles:
Ventana de terminal
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
Requerir mención es falso pero aún bloqueado

Causas comunes:

  • groupPolicy="allowlist" sin una lista de permitidos de gremio/canal coincidente
  • requireMention configurado en el lugar incorrecto (debe estar bajo channels.discord.guilds o la entrada del canal)
  • remitente bloqueado por la lista de permitidos users de gremio/canal
Long-running handlers time out or duplicate replies

Registros típicos:

  • Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE
  • Slow listener detected ...
  • discord inbound worker timed out after ...

Control de presupuesto de escucha (Listener budget knob):

  • single-account: channels.discord.eventQueue.listenerTimeout
  • multi-account: `channels.discord.accounts.

.eventQueue.listenerTimeout`

Control de tiempo de espera de ejecución del trabajador (Worker run timeout knob):


- single-account: `channels.discord.inboundWorker.runTimeoutMs`
- multi-account: `channels.discord.accounts.

.inboundWorker.runTimeoutMs - default:1800000(30 minutes); set0` to disable

Línea de base recomendada:
{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}
Use `eventQueue.listenerTimeout` para una configuración de escucha lenta y `inboundWorker.runTimeoutMs`
solo si desea una válvula de seguridad separada para los turnos del agente en cola.
Permissions audit mismatches

Las comprobaciones de permisos channels status --probe solo funcionan para IDs de canal numéricos.

Si usa claves de slug, la coincidencia en tiempo de ejecución aún puede funcionar, pero la sonda no puede verificar completamente los permisos.

DM and pairing issues
  • DM disabled: channels.discord.dm.enabled=false
  • DM policy disabled: channels.discord.dmPolicy="disabled" (legacy: channels.discord.dm.policy)
  • awaiting pairing approval in pairing mode
Bot to bot loops

De forma predeterminada, se ignoran los mensajes creados por bots.

Si establece channels.discord.allowBots=true, use reglas estrictas de mención y lista de permitidos para evitar un comportamiento de bucle. Prefiera channels.discord.allowBots="mentions" para aceptar solo mensajes de bot que mencionan al bot.

Caídas de voz STT con DecryptionFailed(...)
  • mantener OpenClaw actualizado (openclaw update) para que esté presente la lógica de recuperación de recepción de voz de Discord
  • confirmar channels.discord.voice.daveEncryption=true (predeterminado)
  • comenzar desde channels.discord.voice.decryptionFailureTolerance=24 (predeterminado ascendente) y ajustar solo si es necesario
  • vigilar los registros para:
    • discord voice: DAVE decrypt failures detected
    • discord voice: repeated decrypt failures; attempting rejoin
  • si los fallos continúan después de la reincorporación automática, recopile los registros y compárelos con discord.js #11419

Punteros de referencia de configuración

Sección titulada «Punteros de referencia de configuración»

Referencia principal:

Campos de Discord de alta señal:

  • inicio/autenticación: enabled, token, accounts.*, allowBots
  • política: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
  • comando: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
  • cola de eventos: eventQueue.listenerTimeout (presupuesto del escucha), eventQueue.maxQueueSize, eventQueue.maxConcurrency
  • trabajador de entrada: inboundWorker.runTimeoutMs
  • respuesta/historial: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
  • entrega: textChunkLimit, chunkMode, maxLinesPerMessage
  • transmisión: streaming (alias heredado: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
  • medios/reintentos: mediaMaxMb, retry
    • mediaMaxMb limita las cargas de salida de Discord (predeterminado: 8MB)
  • acciones: actions.*
  • presencia: activity, status, activityType, activityUrl
  • UI: ui.components.accentColor
  • features: threadBindings, nivel superior bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Seguridad y operaciones

Sección titulada «Seguridad y operaciones»
  • Trate los tokens del bot como secretos (DISCORD_BOT_TOKEN preferido en entornos supervisados).
  • Conceda permisos de Discord con el privilegio mínimo.
  • Si el estado de despliegue/comando está obsoleto, reinicie la puerta de enlace y vuelva a verificar con openclaw channels status --probe.

Relacionado

Sección titulada «Relacionado»