Discord

Ejecuta tu agente ZeroClaw como un bot de Discord. Esta guía te acompaña paso a paso, clic a clic, sin necesidad de experiencia previa con bots. Al final tendrás un bot instalado en tu servidor que responde cuando la gente le habla.

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para discord establece channel en discord, enumera los remitentes permitidos en external_peers (para discord, el ID de usuario de Discord (snowflake); ["*"] acepta a cualquiera), opcionalmente nombra agents pares para el despacho entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulta Peer Groups para la referencia de campos.

Dónde configurar esto:

Inicio rápido

Cinco pasos: crea el bot, copia su token, activa dos interruptores, invítalo e inicia ZeroClaw.

1. Crea el bot

1. Ve al Portal de Desarrolladores de Discord.
2. Haz clic en New Application, asígnale un nombre y haz clic en Create.
3. En la barra lateral izquierda, haz clic en Bot.
4. Haz clic en Reset Token, luego en Copy. Esta cadena larga es tu bot_token. Guárdala en un lugar seguro para el paso 3, no podrás verla de nuevo más

El token del bot es una contraseña para tu bot. Cualquiera que lo tenga puede controlar tu bot. Nunca lo pegues en un chat público, lo incluyas en una captura de pantalla ni lo subas a git.

2. Activa los dos interruptores que el bot necesita

Todavía en la página Bot, desplázate hasta Privileged Gateway Intents y activa ambos de estos:

• Message Content Intent para que el bot pueda leer lo que las personas escriben.
• Server Members Intent para que pueda ver quién está en el servidor.

Haz clic en Save Changes. Si omites este paso, el bot se conecta pero nunca ve ningún mensaje, lo cual es la causa más común de “mi bot no hace nada”.

3. Informa a ZeroClaw sobre el bot

Coloca el token del paso 1 en tu configuración. El token es un secreto, así que configúralo a través de una superficie que lo cifre en lugar de escribirlo en config.toml:

channels.discord.<alias>.bot_token es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo a través de uno de estos métodos, que cifran al escribir:

zeroclaw config set channels.discord.<alias>.bot_token    # solicita entrada enmascarada, almacena cifrado

4. Invita el bot a tu servidor

1. De vuelta en el Developer Portal, abre OAuth2 -> URL Generator.
2. En Scopes, marca bot.
3. En Bot Permissions, marca al menos Send Messages, Read Message History y View Channels.
4. Copia la URL que aparece en la parte inferior, ábrela en tu navegador, elige tu servidor y haz clic en Authorize.

El bot ahora aparece en tu lista de miembros (sin conexión hasta que inicies ZeroClaw).

5. Iniciar y probar

Inicia ZeroClaw (zeroclaw service restart o zeroclaw daemon), luego envía un mensaje en un canal que el bot pueda ver. Debería responder. Si no lo hace, ve a Solución de problemas.

Configuración

La lista completa de campos, derivada del esquema en vivo. La mayoría tienen valores predeterminados razonables; para un bot básico solo necesitas configurar bot_token.

zeroclaw config set channels.discord.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__discord__<alias>__approval_timeout_secs=

zeroclaw config set channels.discord.<alias>.archive <value>

export ZEROCLAW_channels__discord__<alias>__archive=

zeroclaw config set channels.discord.<alias>.bot_token    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__discord__<alias>__bot_token=

zeroclaw config set channels.discord.<alias>.channel_ids <value>

export ZEROCLAW_channels__discord__<alias>__channel_ids=

zeroclaw config set channels.discord.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__discord__<alias>__draft_update_interval_ms=

zeroclaw config set channels.discord.<alias>.excluded_tools <value>

export ZEROCLAW_channels__discord__<alias>__excluded_tools=

zeroclaw config set channels.discord.<alias>.guild_ids <value>

export ZEROCLAW_channels__discord__<alias>__guild_ids=

zeroclaw config set channels.discord.<alias>.intents_mask <value>

export ZEROCLAW_channels__discord__<alias>__intents_mask=

zeroclaw config set channels.discord.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__discord__<alias>__interrupt_on_new_message=

zeroclaw config set channels.discord.<alias>.listen_to_bots <value>

export ZEROCLAW_channels__discord__<alias>__listen_to_bots=

zeroclaw config set channels.discord.<alias>.mention_only <value>

export ZEROCLAW_channels__discord__<alias>__mention_only=

zeroclaw config set channels.discord.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__discord__<alias>__multi_message_delay_ms=

zeroclaw config set channels.discord.<alias>.proxy_url <value>

export ZEROCLAW_channels__discord__<alias>__proxy_url=

zeroclaw config set channels.discord.<alias>.reaction_notifications <value>

export ZEROCLAW_channels__discord__<alias>__reaction_notifications=

zeroclaw config set channels.discord.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__discord__<alias>__reply_min_interval_secs=

zeroclaw config set channels.discord.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__discord__<alias>__reply_queue_depth_max=

zeroclaw config set channels.discord.<alias>.slash_command_scope <value>

export ZEROCLAW_channels__discord__<alias>__slash_command_scope=

zeroclaw config set channels.discord.<alias>.slash_commands <value>

export ZEROCLAW_channels__discord__<alias>__slash_commands=

zeroclaw config set channels.discord.<alias>.stall_timeout_secs <value>

export ZEROCLAW_channels__discord__<alias>__stall_timeout_secs=

zeroclaw config set channels.discord.<alias>.stream_mode <value>

export ZEROCLAW_channels__discord__<alias>__stream_mode=

Restricción de dónde escucha el bot

De forma predeterminada, el bot escucha en todos los servidores a los que es invitado y en todos los canales que puede ver. Para limitar su alcance:

• guild_ids: limita el bot a servidores (guilds) específicos. Vacío significa todos.
• channel_ids: limítalo a canales específicos. Vacío significa todos los visibles.

Para encontrar un ID, habilita el Modo desarrollador en Discord (Ajustes de usuario -> Avanzado), luego haz clic derecho en un servidor o canal y selecciona Copiar ID.

Hilos y contexto

Cuando una conversación de Discord ocurre en un hilo, ese hilo es su propia conversación. ZeroClaw deriva una clave de sesión distinta por hilo, de modo que cada hilo lleva una ventana de contexto y un historial independientes: los mensajes de un hilo nunca se filtran a otro, y el agente no ve los turnos anteriores de un hilo hermano. En Discord, los hilos son canales nativos, por lo que cada hilo ya es una conversación separada: no hay ninguna opción que configurar.

• El aislamiento es el objetivo. El contexto de cada hilo es autónomo: no se filtra fuera del hilo, y nada de fuera del hilo se filtra hacia dentro. Los hilos paralelos mantienen estados conversacionales separados, por lo que las tareas no relacionadas nunca se contaminan entre sí.
• Los hilos largos hacen crecer el contexto. Un hilo acumula historial mientras permanece activo, por lo que un hilo muy largo eventualmente llena la ventana de contexto del modelo como cualquier otra conversación larga. Inicia un nuevo hilo para restablecer.
• El trabajo en curso está delimitado por hilo. Un mensaje nuevo en un hilo no cancela una respuesta en curso en otro; la tarea de cada hilo es independiente.

Archivar y buscar

Establece archive = true y el canal abre un almacén de memoria discord.db auxiliar, registra cada mensaje que ve y registra una herramienta discord_search que el agente puede usar para buscar conversaciones anteriores. Déjalo desactivado si no necesitas búsqueda en el historial; el bot responde normalmente de cualquier manera.

Transmisión

Discord transmite respuestas en streaming mediante la configuración stream_mode:

• off (predeterminado): toda la respuesta se publica como un solo mensaje una vez que el agente termina. Es lo más simple, y nunca muestra una respuesta a medio escribir.
• partial: el bot publica un borrador inmediatamente y lo edita en el mismo lugar a medida que la respuesta se transmite. draft_update_interval_ms regula el ritmo de las ediciones; auméntalo si Discord les aplica límites de velocidad.
• multi_message: cada párrafo se publica como un mensaje independiente, separados por multi_message_delay_ms. Útil para respuestas largas que de otro modo serían un solo bloque de texto.

Colócalo sobre cualquier superficie:

zeroclaw config set channels.discord.<alias>.stream_mode <value>

Respuestas que suenan naturales

• mention_only: cuando es true, el bot solo responde a los mensajes que lo @-mencionan, de modo que permanece en silencio en canales con mucha actividad.
• reply_min_interval_secs: un intervalo mínimo entre respuestas a la misma persona, útil si las respuestas instantáneas resultan robóticas.

Solución de problemas

Ejecutar Discord como complemento (experimental)

Todo lo anterior usa el canal de Discord integrado en ZeroClaw. Discord también está disponible como plugin de canal WASM instalable, el paquete discord del registro de plugins. El plugin se ejecuta dentro del sandbox de plugins y solo puede acceder a los hosts que le concedas. Es experimental y solo gestiona mensajes de texto; el canal integrado sigue siendo el predeterminado.

Asigna cada token de bot al canal integrado o al plugin, nunca a ambos. Discord entrega cada evento a cada conexión establecida con el token, por lo que los dos responderían a todos los mensajes. Antes de mover un bot al plugin, elimina su tabla [channels.discord.<alias>]. El plugin nunca lee esa tabla.

Lo que necesitas

• Un binario de zeroclaw cuyo host de plugins compila componentes .wasm, es decir, uno compilado con la característica plugins-wasm-cranelift (véase características de compilación). En un binario sin el host de plugins, el comando zeroclaw plugin no existe. zeroclaw plugin install comprueba que el paquete se carga en este host antes de instalar nada.
• El bot de la Guía de inicio rápido: su token, el Message Content Intent activado y el bot invitado a tu servidor.
• En un canal privado, el bot (o uno de sus roles) necesita Ver canal, Enviar mensajes y Leer el historial de mensajes en ese canal. Discord no envía eventos de un canal que el bot no puede ver, y el plugin no registra nada al respecto: el bot se conecta y parece correcto, pero nunca ve un mensaje. Lo mismo ocurre cuando channel_ids nombra un canal que el bot no puede ver.
• El ID numérico de usuario de cada persona autorizada para hablar con el agente. Activa el Modo de desarrollador (Configuración de usuario -> Avanzado), haz clic derecho en el usuario y haz clic en Copiar ID de usuario.

1. Instala el paquete y vincula una instancia

Elige un alias para la instancia, aquí main, e instala el paquete vinculado a él:

zeroclaw plugin install discord --channel-alias main --egress declared

El comando descarga discord desde el registro, lo verifica, escribe un enlace [channels.plugin.main] y crea la fila de configuración de la instancia. --egress declared concede acceso a los hosts que declara el paquete: discord.com para la API REST y *.discord.gg para el WebSocket de la pasarela, ya que Discord asigna sus hosts de pasarela y de reanudación bajo ese dominio. Con --egress none, en cambio, la instancia no tiene acceso a la red hasta que lo concedas.

Si el paquete ya está instalado, vincula el alias por sí solo:

zeroclaw plugin bind discord --channel-alias main --egress declared

Vinculación de una instancia de canal describe tanto los comandos como el informe que imprimen.

La instancia guarda su configuración bajo una clave derivada del paquete, la capacidad channel y el alias. Para el alias main, la clave es zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ, y zeroclaw plugin info discord muestra la clave de cada alias vinculado.

2. Configura el token del bot

El token es un secreto. Omite el valor de la línea de comandos y zeroclaw config set lo solicitará sin mostrarlo en pantalla y lo almacenará cifrado:

zeroclaw config set plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.bot_token

Los demás ajustes se encuentran junto al token bajo .config. y son opcionales: guild_ids y channel_ids limitan en qué lugares escucha el bot (consulta Limitar dónde escucha el bot), y mention_only y listen_to_bots aceptan true o false. ZeroClaw almacena cada ajuste del plugin cifrado, así que zeroclaw config set solicita cada uno de ellos, igual que hace con el token; usa --no-interactive para indicar en la línea de comandos un ajuste que no es secreto. Define una lista como texto JSON:

zeroclaw config set --no-interactive plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.channel_ids '["123456789012345678"]'

3. Actívalo y enrútalo a un agente

Binding nunca activa el sistema de plugins y nunca asigna la instancia a un agente. Activa el sistema de plugins:

zeroclaw config set plugins.enabled true

Luego añade plugin.main a la lista channels del agente que debe responder, manteniendo los canales que ya tiene, y admite a tus usuarios con un grupo de pares en el mismo canal:

[agents.assistant]
channels = ["plugin.main"]

[peer_groups.discord_plugin]
channel = "plugin.main"
external_peers = ["111111111111111111"]

El plugin informa de cada remitente mediante su ID de usuario numérico, y un canal de plugin compara a los remitentes de forma exacta, por lo que debes indicar los ID de usuario, no los nombres de usuario. Reinicia ZeroClaw (zeroclaw service restart) para iniciar la instancia.

4. Comprueba que se ejecuta

• zeroclaw plugin info discord indica si el paquete se carga en este host, muestra la clave de la instancia y enumera todo lo que la instancia aún necesita antes de poder iniciarse.
• Al iniciarse, la lista de canales del daemon incluye plugin.main, y la instantánea de /health del gateway muestra un componente channel:plugin.main. El componente muestra error cuando falla el sondeo del plugin; en los demás casos sigue el propio chequeo de estado del plugin, que ZeroClaw solicita aproximadamente cada 30 segundos. Lo que cubre ese chequeo depende del plugin, así que la prueba de que el bot está conectado a Discord es que un mensaje de un usuario admitido llegue al agente y que la respuesta del agente aparezca en Discord.
• Un mensaje de un usuario admitido se registra como channel inbound message con zeroclaw.channel = plugin.main. Un mensaje de cualquier otra persona se descarta y se registra con error_key = plugin_channel_sender_denied.
• Se rechaza una conexión a un host que queda fuera de la concesión. Una solicitud HTTP rechazada se registra con error_key = plugin_egress_denied, el host rechazado y el comando zeroclaw config set que lo concede. Una conexión rechazada al gateway todavía no se registra, así que un bot que permanece sin conexión tras un cambio en egress_hosts probablemente ha perdido *.discord.gg.

Cómo se diferencia el plugin del canal integrado

Las conversaciones se guardan por nombre de canal, por lo que un bot que se mueva de discord.main a plugin.main inicia conversaciones nuevas.

Ver también

• Quién puede hablar con el agente (grupos de pares)
• Plugins (instalación y vinculación de plugins de canal)
• Slack
• Visión general de los canales