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

Ver también

• Quién puede hablar con el agente (grupos de pares)
• Slack
• Visión general de los canales