Discord

OpenClaw se conecta a Discord como bot mediante el gateway oficial de Discord. Se admiten los mensajes directos y los canales de servidor.

Configuración rápida

Cree una aplicación de Discord con un bot, añada el bot a su servidor y emparéjelo con OpenClaw. Si es posible, use un servidor privado; si es necesario, cree uno primero (Create My Own > For me and my friends).

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" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

Recomendación: configurar un espacio de trabajo de servidor

Cuando los mensajes directos funcionen, puede convertir el servidor en un espacio de trabajo completo donde cada canal tenga su propia sesión de agente con su propio contexto. Se recomienda para servidores privados donde solo estén el usuario y el bot.

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

Ahora cree canales y empiece a chatear. El agente ve el nombre del canal y cada canal es una sesión aislada: configure #coding, #home, #research o lo que mejor se adapte al flujo de trabajo.

Modelo de ejecución

• El Gateway gestiona la conexión con Discord.
• El enrutamiento de respuestas es determinista: las respuestas a entradas de Discord vuelven a Discord.
• Los metadatos de servidores/canales de Discord se añaden al prompt del modelo como contexto no fiable, no como prefijo visible para el usuario en la respuesta. Si un modelo vuelve a copiar ese envoltorio, OpenClaw elimina los metadatos copiados de las respuestas salientes y del contexto de reproducción futuro.
• De forma predeterminada (session.dmScope=main), los chats directos comparten la sesión principal del agente (agent:main:main).
• Los canales del servidor tienen claves de sesión aisladas (agent:<agentId>:discord:channel:<channelId>).
• Los mensajes directos de grupo se ignoran de forma predeterminada (channels.discord.dm.groupEnabled=false).
• Los comandos de barra nativos se ejecutan en sesiones de comandos aisladas (agent:<agentId>:discord:slash:<userId>), pero siguen llevando CommandTargetSessionKey a la sesión de conversación enrutada.
• La entrega a Discord de anuncios de cron/heartbeat solo de texto se reduce a la respuesta final visible del asistente, que se envía una sola vez. Los elementos multimedia y las cargas útiles de componentes estructurados siguen usando varios mensajes cuando el agente emite varias cargas útiles entregables.

Canales de foro

Los canales de foro y multimedia de Discord solo aceptan publicaciones en hilos. OpenClaw permite crearlas de dos maneras:

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

Envía al foro principal para crear un hilo:

openclaw message send --channel discord --target channel:<forumId> \  --message "Título del tema\nCuerpo de la publicación"

Crea explícitamente un hilo de foro:

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Título del tema" --message "Cuerpo de la publicación"

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

Componentes interactivos

OpenClaw admite contenedores de componentes v2 de Discord para los mensajes del agente. Usa la herramienta de mensajes con una carga 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 único menú de selección
• Tipos de selección: string, user, role, mentionable, channel

De forma predeterminada, los componentes son de un solo uso. Establece components.reusable=true para permitir que los botones, las selecciones y los formularios se usen varias veces hasta que caduquen.

Para restringir quién puede hacer clic en un botón, establece allowedUsers en ese botón (ID de usuario de Discord, etiquetas o *). Los usuarios que no coincidan reciben una denegación efímera.

De forma predeterminada, las devoluciones de llamada de los componentes caducan después de 30 minutos. Establece channels.discord.agentComponents.ttlMs para cambiar la duración del registro de devoluciones de llamada de la cuenta predeterminada, o channels.discord.accounts.<accountId>.agentComponents.ttlMs para cada cuenta. El valor se expresa en milisegundos, debe ser un entero positivo y tiene un límite de 86400000 (24 horas). Los TTL más largos son adecuados para flujos de revisión o aprobación que necesitan mantener utilizables los botones, pero amplían el intervalo durante el cual un mensaje antiguo de Discord aún puede activar una acción. Usa el TTL más corto que resulte adecuado y conserva el valor predeterminado cuando las devoluciones de llamada obsoletas pudieran resultar inesperadas.

Los comandos de barra /model y /models abren un selector de modelos interactivo con listas desplegables de proveedor, modelo y entorno de ejecución compatible, además de un paso de envío. /models add está obsoleto y devuelve un mensaje de obsolescencia en lugar de registrar modelos desde el chat. La respuesta del selector es efímera y solo puede usarla el usuario que lo invocó. Los menús de selección de Discord tienen un límite de 25 opciones, por lo que debes añadir entradas provider/* a agents.defaults.modelPolicy.allow cuando quieras que el selector muestre modelos detectados dinámicamente solo para determinados proveedores, como openai o vllm.

Archivos adjuntos:

• Los bloques file deben apuntar a una referencia de archivo adjunto (attachment://<filename>)
• Proporciona el archivo adjunto mediante media/path/filePath (un solo archivo); usa media-gallery para varios archivos
• Usa filename para sustituir el nombre de carga cuando deba coincidir con la referencia del archivo adjunto

Formularios modales:

• Añade 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: "Texto alternativo opcional",  components: {    reusable: true,    text: "Elige una ruta",    blocks: [      {        type: "actions",        buttons: [          {            label: "Aprobar",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Rechazar", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Elige una opción",          options: [            { label: "Opción A", value: "a" },            { label: "Opción B", value: "b" },          ],        },      },    ],    modal: {      title: "Detalles",      triggerLabel: "Abrir formulario",      fields: [        { type: "text", label: "Solicitante" },        {          type: "select",          label: "Prioridad",          options: [            { label: "Baja", value: "low" },            { label: "Alta", value: "high" },          ],        },      ],    },  },}

Control de acceso y enrutamiento

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

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

Enrutamiento de agentes basado en roles

Usa bindings[].match.roles para enrutar a los miembros de servidores de Discord hacia distintos agentes según el ID del rol. Las vinculaciones basadas en roles solo aceptan ID de roles y se evalúan después de las vinculaciones de pares o pares principales y antes de las vinculaciones exclusivas del servidor. Si una vinculación 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",      },    },  ],}

Comandos nativos y autorización de comandos

• commands.native tiene como valor predeterminado "auto" y está habilitado para Discord.
• Anulación por canal: channels.discord.commands.native.
• commands.native=false omite el registro y la limpieza de comandos de barra de Discord durante el inicio. Los comandos registrados anteriormente pueden seguir visibles en Discord hasta que se eliminen de la aplicación de Discord.
• La autorización de comandos nativos utiliza las mismas listas de permitidos y políticas de Discord que el procesamiento normal de mensajes.
• Los comandos pueden seguir visibles en la interfaz de Discord para usuarios no autorizados; durante su ejecución, se aplica la autorización de OpenClaw y se responde "no autorizado".
• Configuración predeterminada de los comandos de barra: ephemeral: true (channels.discord.slashCommand.ephemeral).

Consulte Comandos de barra para ver el catálogo y el comportamiento de los comandos.

Detalles de las funciones

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      maxLines: 8,      maxLineChars: 120,      toolProgress: false,      commentary: false,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,  spawnSessions: true,  defaultSpawnContext: "fork",},},}

{channels: {discord: {  subagentProgress: true,},},}

{agents: {entries: {  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,        },      },    },  },},},}

{  channels: {    discord: {      intents: { presence: true },      guilds: {        "111111111111111111": {          presenceEvents: {            channelId: "222222222222222222",            users: ["333333333333333333"], // opcional; restringe aún más los usuarios del canal            reconnectSuppressSeconds: 300, // opcional; periodo de silencio de la nueva sesión (0 lo desactiva)            burstLimit: 8, // opcional; máximo de eventos por ventana de ráfaga            burstWindowSeconds: 60, // opcional; ventana deslizante de detección de ráfagas          },        },      },    },  },}

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

{channels: {discord: {  proxy: "http://proxy.example:8080",},},}

{channels: {discord: {  accounts: {    primary: {      proxy: "http://proxy.example:8080",    },  },},},}

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

{channels: {discord: {  mentionAliases: {    SupportLead: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{channels: {discord: {  status: "idle",},},}

{channels: {discord: {  activity: "Tiempo de concentración",  activityType: 4,},},}

{channels: {discord: {  activity: "Programación en directo",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "tokens agotados",  },},},}

Herramientas y controles de acciones

Las acciones de mensajes de Discord abarcan la mensajería, la administración de canales, la moderación, la presencia y los metadatos.

Ejemplos principales:

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

La acción event-create acepta un parámetro opcional image (URL o ruta de archivo local) para establecer la imagen de portada del evento programado.

Los controles de acciones se encuentran en channels.discord.actions.*.

Comportamiento predeterminado de los controles:

Interfaz de usuario de componentes v2

OpenClaw utiliza los componentes v2 de Discord para las aprobaciones de ejecución y los marcadores entre contextos. Las acciones de mensajes de Discord también pueden aceptar components para interfaces de usuario personalizadas (avanzado; requiere construir una carga útil de componentes mediante la herramienta de Discord), mientras que los embeds heredados siguen disponibles, pero no se recomiendan.

• channels.discord.ui.components.accentColor establece el color de énfasis utilizado por los contenedores de componentes de Discord (hexadecimal). Por cuenta: channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs controla durante cuánto tiempo permanecen registradas las devoluciones de llamada de los componentes de Discord enviados (valor predeterminado: 1800000; máximo: 86400000). Por cuenta: channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds se ignoran cuando hay componentes v2 presentes.
• Las vistas previas de URL simples se suprimen de forma predeterminada. Establezca suppressEmbeds: false en una acción de mensaje cuando se deba expandir un único enlace saliente.

Ejemplo:

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

Voz

Discord tiene dos superficies de voz distintas: canales de voz en tiempo real (conversaciones continuas) y archivos adjuntos de mensajes de voz (el formato de vista previa de la forma de onda). El Gateway admite ambas.

Canales de voz

Lista de comprobación de configuración:

1. Habilite Message Content Intent en Discord Developer Portal.
2. Habilite Server Members Intent cuando se utilicen listas de usuarios o roles permitidos.
3. Invite al bot con los ámbitos bot y applications.commands.
4. Conceda Connect, Speak, Send Messages y Read Message History en el canal de voz de destino.
5. Habilite los comandos nativos (commands.native o channels.discord.commands.native).
6. Configure channels.discord.voice.

Utilice /vc join|leave|status para controlar las sesiones. El comando utiliza el agente predeterminado de la cuenta y sigue las mismas reglas de listas de permitidos y políticas de grupo que los demás comandos de Discord.

/vc join channel:<voice-channel-id>/vc status/vc leave

Para consultar los permisos efectivos del bot antes de unirse:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

Ejemplo de unión automática:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        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.1",          speakerVoice: "cedar",        },      },    },  },}

Notas:

• La voz de Discord es opcional para las configuraciones de solo texto; establezca channels.discord.voice.enabled=true (o conserve un bloque channels.discord.voice existente) para habilitar los comandos /vc, el entorno de ejecución de voz y la intención del Gateway GuildVoiceStates. channels.discord.intents.voiceStates puede anular explícitamente la suscripción a la intención; déjelo sin establecer para seguir la habilitación efectiva de la voz.
• voice.mode controla la ruta de conversación. El valor predeterminado es agent-proxy: una interfaz de voz en tiempo real gestiona los tiempos de los turnos, las interrupciones y la reproducción, delega el trabajo sustancial al agente de OpenClaw enrutado mediante openclaw_agent_consult y trata el resultado como una solicitud escrita de Discord de ese hablante. stt-tts conserva el flujo anterior de STT por lotes más TTS. bidi permite que el modelo en tiempo real converse directamente mientras expone openclaw_agent_consult para el cerebro de OpenClaw.
• voice.agentSession controla qué conversación de OpenClaw recibe los turnos de voz. Déjelo sin establecer para usar la sesión propia del canal de voz, o establezca { mode: "target", target: "channel:<text-channel-id>" } para que el canal de voz actúe como extensión de micrófono y altavoz de una sesión existente de un canal de texto de Discord, como #maintainers.
• voice.model anula el cerebro del agente de OpenClaw para las respuestas de voz de Discord y las consultas en tiempo real. Déjelo sin establecer para heredar el modelo del agente enrutado. Es independiente de voice.realtime.model.
• voice.followUsers permite que el bot se una, se desplace y salga de la voz de Discord junto con los usuarios seleccionados. Consulte Seguir usuarios en la voz.
• agent-proxy enruta el habla mediante discord-voice, que conserva la autorización normal del propietario y de las herramientas para el hablante y la sesión de destino, pero oculta la herramienta tts del agente porque la voz de Discord controla la reproducción. De forma predeterminada, agent-proxy concede a la consulta acceso completo a herramientas equivalente al del propietario para los hablantes propietarios (voice.realtime.toolPolicy: "owner") y prioriza firmemente consultar al agente de OpenClaw antes de ofrecer respuestas sustanciales (voice.realtime.consultPolicy: "always"). En ese modo always predeterminado, la capa en tiempo real no pronuncia automáticamente contenido de relleno antes de la respuesta de la consulta; captura y transcribe el habla y, a continuación, pronuncia la respuesta enrutada de OpenClaw. Si varias respuestas de consultas forzadas terminan mientras Discord aún reproduce la primera respuesta, las respuestas posteriores con el texto exacto que se debe pronunciar se ponen en cola hasta que la reproducción queda inactiva, en lugar de sustituir el habla a mitad de una frase.
• En el modo stt-tts, STT utiliza tools.media.audio; voice.model no afecta a la transcripción.
• En los modos en tiempo real, voice.realtime.provider, voice.realtime.model y voice.realtime.speakerVoice configuran la sesión de audio en tiempo real. Para OpenAI Realtime 2.1 con el cerebro Codex, utilice voice.realtime.model: "gpt-realtime-2.1" y voice.model: "openai/gpt-5.6-sol".
• De forma predeterminada, los modos de voz en tiempo real incluyen pequeños archivos de perfil IDENTITY.md, USER.md y SOUL.md en las instrucciones del proveedor en tiempo real, para que los turnos directos rápidos mantengan la misma identidad, fundamentación sobre el usuario y personalidad que el agente de OpenClaw enrutado. Establezca voice.realtime.bootstrapContextFiles en un subconjunto para personalizarlo, o [] para deshabilitarlo. Solo se admiten esos archivos de perfil; AGENTS.md permanece en el contexto normal del agente. El contexto de perfil inyectado no sustituye a openclaw_agent_consult para el trabajo en el espacio de trabajo, los hechos actuales, la consulta de memoria o las acciones respaldadas por herramientas.
• En el modo en tiempo real agent-proxy de OpenAI, el control mediante nombre de activación se adapta de forma predeterminada a la sala: una persona puede hablar con naturalidad sin un nombre de activación, mientras que dos o más personas deben comenzar o terminar cada turno con uno. Los demás bots no cuentan como personas. Establezca voice.realtime.requireWakeName: true para exigir siempre un nombre de activación o false para no exigirlo nunca. Los nombres de activación configurados deben tener una o dos palabras. Si voice.realtime.wakeNames no está establecido, OpenClaw utiliza el name del agente enrutado junto con OpenClaw y, como alternativa, el identificador del agente junto con OpenClaw. Un control activo mediante nombre de activación deshabilita la respuesta automática del proveedor en tiempo real, enruta los turnos aceptados por la ruta de consulta del agente de OpenClaw y proporciona una breve confirmación hablada cuando se reconoce un nombre de activación inicial a partir de una transcripción parcial antes de que llegue la transcripción final. La política sigue las incorporaciones y salidas en directo sin volver a conectar la voz.
• El proveedor en tiempo real de OpenAI acepta los nombres de eventos actuales de Realtime 2 y los alias heredados compatibles con Codex para los eventos de audio de salida y transcripción, por lo que las instantáneas compatibles del proveedor pueden divergir sin perder el audio del asistente.
• voice.realtime.bargeIn controla si los eventos de inicio del habla de Discord interrumpen la reproducción activa en tiempo real. Si no está establecido, sigue la configuración de interrupción por audio de entrada del proveedor en tiempo real.
• voice.realtime.minBargeInAudioEndMs controla la duración mínima de reproducción del asistente antes de que una interrupción de OpenAI en tiempo real trunque el audio. Valor predeterminado: 250. Establezca 0 para una interrupción inmediata en salas con poco eco, o auméntelo para configuraciones de altavoces con mucho eco.
• voice.tts anula tts solo para la reproducción de voz stt-tts; los modos en tiempo real utilizan voice.realtime.speakerVoice en su lugar. Para usar una voz de OpenAI en la reproducción de Discord, establezca voice.tts.provider: "openai" y elija una voz de texto a voz en voice.tts.providers.openai.speakerVoice. cedar es una buena opción de sonido masculino en el modelo TTS actual de OpenAI.
• Las anulaciones systemPrompt de Discord por canal se aplican a los turnos de transcripción de voz de ese canal de voz.
• Cuando OpenClaw se une a un canal de voz, la sesión del agente enrutado recibe un evento silencioso del sistema con la lista actual de participantes. Las incorporaciones y salidas posteriores de participantes actualizan esa sesión sin provocar una respuesta hablada no solicitada; los nombres para mostrar de Discord se tratan como etiquetas no fiables. Los turnos de voz autorizados también reciben una instantánea actualizada de la lista de participantes.
• Los turnos de transcripción de voz y los comandos /vc utilizan las entradas de Discord en commands.ownerAllowFrom para determinar el estado de propietario. Cuando no se configura ningún propietario de comandos de Discord, el allowFrom de la cuenta de Discord seleccionada (o el dm.allowFrom heredado) aún puede autorizar el acceso por voz sin conceder el estado de propietario. La visibilidad de las herramientas del agente sigue la política de herramientas configurada para la sesión enrutada.
• Si voice.autoJoin tiene varias entradas para el mismo servidor, OpenClaw se une al último canal configurado para ese servidor.
• voice.allowedChannels es una lista de permitidos opcional para la permanencia. Déjela sin establecer para permitir /vc join en cualquier canal de voz de Discord autorizado. Cuando está establecida, /vc join, la unión automática durante el inicio y los desplazamientos del estado de voz del bot quedan restringidos a las entradas { guildId, channelId } enumeradas. Establézcala en una matriz vacía para denegar todas las uniones a la voz de Discord. Si Discord desplaza el bot fuera de la lista de permitidos, OpenClaw sale de ese canal y vuelve a unirse al destino de unión automática configurado cuando hay uno disponible.
• voice.daveEncryption y voice.decryptionFailureTolerance se transfieren a las opciones de unión de @discordjs/voice; los valores predeterminados del componente de nivel superior son daveEncryption=true y decryptionFailureTolerance=24.
• OpenClaw utiliza el códec libopus-wasm incluido para la recepción de voz de Discord y la reproducción de PCM sin procesar en tiempo real. Incluye una compilación WebAssembly fijada de libopus y no requiere complementos nativos de opus.
• voice.connectTimeoutMs controla la espera inicial de Ready de @discordjs/voice para /vc join y los intentos de unión automática. Valor predeterminado: 30000.
• voice.reconnectGraceMs controla cuánto tiempo espera OpenClaw a que una sesión de voz desconectada comience a reconectarse antes de destruirla. Valor predeterminado: 15000.
• En el modo stt-tts, la reproducción de voz no se detiene únicamente porque otro usuario empiece a hablar. Para evitar bucles de realimentación, OpenClaw ignora las nuevas capturas de voz mientras se reproduce TTS; hable después de que termine la reproducción para iniciar el siguiente turno. Los modos en tiempo real reenvían los inicios del habla como señales de interrupción al proveedor en tiempo real.
• En los modos en tiempo real, el eco de los altavoces que entra en un micrófono abierto puede parecer una interrupción y detener la reproducción. Para salas de Discord con mucho eco, establezca voice.realtime.providers.openai.interruptResponseOnInputAudio: false para impedir que OpenAI interrumpa automáticamente por el audio de entrada. Añada voice.realtime.bargeIn: true si aun así desea que los eventos de inicio del habla de Discord interrumpan la reproducción activa. El puente en tiempo real de OpenAI ignora como probable eco o ruido los truncamientos de reproducción inferiores a voice.realtime.minBargeInAudioEndMs y los registra como omitidos en lugar de borrar la reproducción de Discord.
• voice.captureSilenceGraceMs controla cuánto tiempo espera OpenClaw después de que Discord indique que un hablante ha dejado de hablar antes de finalizar ese segmento de audio para STT. Valor predeterminado: 2000; auméntelo si Discord divide las pausas normales en transcripciones parciales entrecortadas.
• Cuando ElevenLabs es el proveedor de TTS seleccionado, la reproducción de voz de Discord utiliza TTS por streaming y comienza a partir del flujo de respuesta del proveedor. Los proveedores sin compatibilidad con streaming recurren a la ruta del archivo temporal sintetizado.
• OpenClaw supervisa los fallos de descifrado de recepción y se recupera automáticamente saliendo del canal de voz y volviendo a unirse después de varios fallos en un intervalo breve.
• Si los registros de recepción muestran repetidamente DecryptionFailed(UnencryptedWhenPassthroughDisabled) después de actualizar, recopile un informe de dependencias y los registros. La línea @discordjs/voice incluida contiene la corrección de relleno del componente de nivel superior procedente del PR #11449 de discord.js, que cerró el issue #11419 de discord.js.
• Los eventos de recepción The operation was aborted son esperados cuando OpenClaw finaliza un segmento capturado de un hablante; son diagnósticos detallados, no advertencias.
• Los registros detallados de voz de Discord incluyen una vista previa acotada de una línea de la transcripción STT para cada segmento de hablante aceptado, de modo que la depuración muestre tanto el lado del usuario como el de la respuesta del agente sin volcar texto de transcripción sin límites.
• En el modo agent-proxy, la alternativa de consulta forzada omite fragmentos de transcripción probablemente incompletos, como texto que termina en ... o un conector final como «y», además de cierres evidentemente no procesables como «vuelvo enseguida» o «adiós». Los registros muestran forced agent consult skipped reason=... cuando esto evita una respuesta obsoleta en cola.

Seguir usuarios en la voz

Utilice voice.followUsers cuando desee que el bot de voz de Discord permanezca con uno o varios usuarios conocidos de Discord, en lugar de unirse a un canal fijo durante el inicio o esperar a /vc join.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

Comportamiento:

• followUsers acepta ID de usuario de Discord sin procesar y valores discord:<id>. OpenClaw normaliza ambas formas antes de comparar los eventos de estado de voz.
• followUsersEnabled tiene como valor predeterminado true cuando se configura followUsers. Establézcalo en false para conservar la lista guardada, pero detener el seguimiento de voz automático.
• followUsers solo controla la permanencia en el canal de voz. No concede acceso como hablante ni autoridad de propietario; configure commands.ownerAllowFrom y los usuarios y roles del servidor o canal por separado.
• Cuando un usuario seguido se une a un canal de voz permitido, OpenClaw se une a ese canal. Cuando el usuario cambia de canal, OpenClaw cambia con él. Cuando el usuario seguido activo se desconecta, OpenClaw abandona el canal.
• Si hay varios usuarios seguidos en el mismo servidor y el usuario seguido activo se va, OpenClaw cambia al canal de otro usuario seguido rastreado antes de abandonar el servidor. Si varios usuarios seguidos cambian de canal a la vez, prevalece el evento de estado de voz observado más recientemente.
• allowedChannels continúa aplicándose. Se ignora a un usuario seguido que esté en un canal no permitido, y una sesión gestionada mediante seguimiento cambia a otro usuario seguido o abandona el canal.
• OpenClaw concilia los eventos de estado de voz omitidos al iniciarse y en intervalos acotados. La conciliación toma muestras de los servidores configurados y limita las consultas REST por ejecución, por lo que las listas followUsers muy grandes pueden necesitar más de un intervalo para converger.
• Si Discord o un administrador mueve el bot mientras sigue a un usuario, OpenClaw reconstruye la sesión de voz y conserva la propiedad del seguimiento cuando el destino está permitido. Si se mueve el bot fuera de allowedChannels, OpenClaw abandona el canal y vuelve a unirse al destino configurado cuando existe uno.
• La recuperación de recepción de DAVE puede abandonar el canal y volver a unirse a él después de varios errores de descifrado. Las sesiones gestionadas mediante seguimiento conservan la propiedad del seguimiento durante ese proceso de recuperación, por lo que una desconexión posterior del usuario seguido aún hace que se abandone el canal.

Elija entre los modos de unión:

• Use followUsers para configuraciones personales o de operadores en las que el bot deba estar automáticamente en el canal de voz cuando usted lo esté.
• Use autoJoin para bots de sala fija que deban estar presentes incluso cuando ningún usuario rastreado esté en el canal de voz.
• Use /vc join para uniones puntuales o salas en las que una presencia de voz automática resultaría inesperada.

Códec de voz de Discord:

• Los registros de recepción de voz muestran discord voice: opus decoder: libopus-wasm.
• La reproducción en tiempo real codifica PCM estéreo sin procesar de 48 kHz a Opus con el mismo paquete libopus-wasm incluido antes de entregar los paquetes a @discordjs/voice.
• La reproducción de archivos y flujos de proveedores transcodifica a PCM estéreo sin procesar de 48 kHz con ffmpeg y luego usa libopus-wasm para el flujo de paquetes Opus enviado a Discord.

Pipeline de STT y TTS:

• La captura PCM de Discord se convierte en un archivo WAV temporal.
• tools.media.audio gestiona STT, por ejemplo, openai/gpt-4o-mini-transcribe.
• La transcripción se envía a través de la entrada y el enrutamiento de Discord mientras el LLM de respuesta se ejecuta con una política de salida de voz que oculta la herramienta tts del agente y solicita que se devuelva texto, porque la voz de Discord gestiona la reproducción TTS final.
• voice.model, cuando se establece, sustituye únicamente el LLM de respuesta para este turno del canal de voz.
• voice.tts se combina sobre tts; los proveedores compatibles con streaming envían el audio directamente al reproductor; de lo contrario, el archivo de audio resultante se reproduce en el canal al que se ha unido.

Ejemplo de sesión de canal de voz predeterminada con proxy de agente:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

Sin un bloque voice.agentSession, cada canal de voz obtiene su propia sesión de OpenClaw enrutada. Por ejemplo, /vc join channel:234567890123456789 se comunica con la sesión de ese canal de voz de Discord. El modelo en tiempo real es solo la interfaz de voz; las solicitudes sustanciales se entregan al agente de OpenClaw configurado. Si el modelo en tiempo real genera una transcripción final sin llamar a la herramienta de consulta, OpenClaw fuerza la consulta como mecanismo alternativo para que el comportamiento predeterminado siga siendo equivalente a hablar con el agente.

Ejemplo de STT y TTS heredado:

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

Ejemplo bidireccional en tiempo real:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Voz como extensión de una sesión existente de canal de Discord:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.6-sol",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

En el modo agent-proxy, el bot se une al canal de voz configurado, pero los turnos del agente de OpenClaw usan la sesión enrutada y el agente normales del canal de destino. La sesión de voz en tiempo real reproduce oralmente el resultado devuelto en el canal de voz. El agente supervisor puede seguir usando las herramientas de mensajes normales de acuerdo con su política de herramientas, incluido el envío de un mensaje independiente de Discord si esa es la acción adecuada.

Mientras hay una ejecución delegada de OpenClaw activa, las nuevas transcripciones de voz de Discord se tratan como control en directo de la ejecución antes de iniciar otro turno del agente. Frases como «estado», «cancela eso», «usa la corrección más pequeña» o «cuando termines, comprueba también las pruebas» se clasifican como entrada de estado, cancelación, orientación o seguimiento para la sesión activa. Los resultados de estado, cancelación, orientación aceptada y seguimiento se reproducen oralmente en el canal de voz para que quien llama sepa si OpenClaw gestionó la solicitud.

Formas de destino útiles:

• target: "channel:123456789012345678" se enruta a través de una sesión de canal de texto de Discord.
• target: "123456789012345678" se trata como un destino de canal.
• target: "dm:123456789012345678" o target: "user:123456789012345678" se enruta a través de esa sesión de mensajes directos.

Ejemplo de OpenAI Realtime con mucho eco:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Use esta configuración cuando el modelo oiga su propia reproducción de Discord a través de un micrófono abierto, pero aun así se quiera poder interrumpirlo hablando. OpenClaw impide que OpenAI interrumpa automáticamente a partir del audio de entrada sin procesar, mientras que bargeIn: true permite que los eventos de inicio de habla de Discord y el audio de un hablante ya activo cancelen las respuestas en tiempo real activas antes de que el siguiente turno capturado llegue a OpenAI. Las señales de interrupción muy tempranas con audioEndMs por debajo de minBargeInAudioEndMs se consideran probablemente eco o ruido y se ignoran para que el modelo no se interrumpa en el primer fotograma de reproducción.

Registros de voz esperados:

• Al unirse: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Al iniciar el modo en tiempo real: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Al recibir audio de un hablante: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... y discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Al omitir habla obsoleta: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... o reason=non-actionable-closing ...
• Al completarse la respuesta en tiempo real: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Al detener o restablecer la reproducción: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Al realizar una consulta en tiempo real: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Al responder el agente: discord voice: agent turn answer ...
• Al poner en cola habla exacta: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., seguido de discord voice: realtime exact speech dequeued reason=player-idle ...
• Al detectar una interrupción mediante voz: discord voice: realtime barge-in detected source=speaker-start ... o discord voice: realtime barge-in detected source=active-speaker-audio ..., seguido de discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Al interrumpir el modo en tiempo real: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, seguido de discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... o discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Al ignorar eco o ruido: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Al desactivar la interrupción mediante voz: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Durante la reproducción inactiva: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Para depurar audio entrecortado, lea los registros de voz en tiempo real como una cronología:

1. realtime audio playback started significa que Discord ha comenzado a reproducir audio del asistente. A partir de este punto, el puente empieza a contar los fragmentos de salida del asistente, los bytes PCM de Discord, los bytes en tiempo real del proveedor y la duración del audio sintetizado.
2. realtime speaker turn opened indica que un hablante de Discord pasa a estar activo. Si la reproducción ya está activa y bargeIn está habilitado, puede ir seguido de barge-in detected source=speaker-start.
3. realtime input audio started indica el primer fotograma de audio real recibido para ese turno del hablante. outputActive=true o un valor outputAudioMs distinto de cero en este punto significa que el micrófono está enviando entrada mientras la reproducción del asistente continúa activa.
4. barge-in detected source=active-speaker-audio significa que OpenClaw detectó audio en directo del hablante mientras la reproducción del asistente estaba activa. Esto resulta útil para distinguir una interrupción real de un evento de inicio de habla de Discord sin audio útil.
5. barge-in requested reason=... significa que OpenClaw solicitó al proveedor en tiempo real cancelar o truncar la respuesta activa. Incluye outputAudioMs, outputActive y playbackChunks para mostrar cuánto audio del asistente se había reproducido realmente antes de la interrupción.
6. realtime audio playback stopped reason=... es el punto de restablecimiento local de la reproducción de Discord. El motivo indica quién detuvo la reproducción: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close o session-close.
7. realtime speaker turn closed resume el turno de entrada capturado. chunks=0 o hasAudio=false significa que el turno del hablante se abrió, pero ningún audio utilizable llegó al puente en tiempo real. interruptedPlayback=true significa que ese turno de entrada se solapó con la salida del asistente y activó la lógica de interrupción mediante voz.

Campos útiles:

• outputAudioMs: duración del audio del asistente generado por el proveedor en tiempo real antes de la línea del registro.
• audioMs: duración del audio del asistente que OpenClaw contabilizó antes de que se detuviera la reproducción.
• elapsedMs: tiempo de reloj transcurrido entre la apertura y el cierre del flujo de reproducción o del turno del hablante.
• discordBytes: bytes PCM estéreo de 48 kHz enviados a la voz de Discord o recibidos de ella.
• realtimeBytes: bytes PCM en el formato del proveedor enviados al proveedor en tiempo real o recibidos de él.
• playbackChunks: fragmentos de audio del asistente reenviados a Discord para la respuesta activa.
• sinceLastAudioMs: intervalo entre el último fotograma de audio capturado del hablante y el cierre de su turno.

Patrones comunes:

• La interrupción inmediata con source=active-speaker-audio, un valor bajo de outputAudioMs y el mismo usuario cerca suele indicar que el eco del altavoz está entrando en el micrófono. Aumente voice.realtime.minBargeInAudioEndMs, reduzca el volumen del altavoz, use auriculares o configure voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start seguido de speaker turn closed ... hasAudio=false significa que Discord notificó el inicio de un hablante, pero ningún audio llegó a OpenClaw. Puede deberse a un evento de voz transitorio de Discord, al comportamiento de la puerta de ruido o a que un cliente activó brevemente el micrófono.
• audio playback stopped reason=stream-close sin una interrupción cercana ni provider-clear-audio significa que el flujo de reproducción local de Discord terminó inesperadamente. Compruebe los registros anteriores del proveedor y del reproductor de Discord.
• capture ignored during playback (barge-in disabled) significa que OpenClaw descartó intencionadamente la entrada mientras el audio del asistente estaba activo. Habilite voice.realtime.bargeIn si desea que la voz interrumpa la reproducción.
• barge-in ignored ... outputActive=false significa que Discord o el VAD del proveedor detectaron voz, pero OpenClaw no tenía ninguna reproducción activa que interrumpir. Esto no debería cortar el audio.

Las credenciales se resuelven por componente: autenticación de la ruta del LLM para voice.model, autenticación de STT para tools.media.audio, autenticación de TTS para tts/voice.tts y autenticación del proveedor en tiempo real para voice.realtime.providers o la configuración de autenticación habitual del proveedor.

Mensajes de voz

Los mensajes de voz de Discord muestran una vista previa de la forma de onda y requieren audio OGG/Opus. OpenClaw genera la forma de onda automáticamente, pero necesita ffmpeg y ffprobe en el host del Gateway para inspeccionar y convertir el audio.

• Proporcione una ruta de archivo local (se rechazan las URL).
• Omita el contenido de texto (Discord rechaza el texto y el mensaje de voz en la misma carga útil).
• Se acepta cualquier formato de audio; OpenClaw lo convierte a OGG/Opus según sea necesario.

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

Solución de problemas

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Sustitución opcional para todo Discord. Los bloques de cuenta sustituyen campos  // individuales y heredan de aquí los campos omitidos.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha solo escucha a otros bots cuando lo mencionan.      allowBots: "mentions",    },    bravo: {      // Bravo escucha todos los mensajes de Discord creados por bots.      allowBots: true,      mentionAliases: {        // Permite que Bravo escriba una mención de Alpha en Discord con el identificador de usuario configurado.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Permite hasta cinco mensajes por minuto antes de suprimir el par.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Referencia de configuración

Referencia principal: Referencia de configuración: Discord.

Actividades de Discord

Configure channels.discord.activities para permitir que los agentes publiquen widgets HTML autónomos que se abren dentro de Discord. El bloque es opcional; cuando no está presente, OpenClaw no registra rutas de actividades, herramientas ni controladores de interacciones. Consulte Actividades de Discord para configurar Developer Portal, el túnel, la seguridad y la solución de problemas.

• activities.clientSecret: secreto del cliente OAuth2 para la aplicación de Discord; utiliza DISCORD_CLIENT_SECRET como alternativa
• activities.applicationId: identificador opcional de la aplicación de actividades; el valor predeterminado es el identificador de la aplicación del bot obtenido al iniciar el Gateway

Seguridad y operaciones

• Trate los tokens del bot como secretos (se prefiere DISCORD_BOT_TOKEN en entornos supervisados).
• Conceda los permisos mínimos necesarios en Discord.
• Si el despliegue o el estado de los comandos está obsoleto, reinicie el Gateway y vuelva a comprobarlo con openclaw channels status --probe.

Contenido relacionado