Slack

Ejecuta tu agente ZeroClaw como un bot de Slack. Esta guía te muestra el proceso paso a paso. Al final tendrás un bot en tu espacio de trabajo que responde cuando las personas le envían mensajes o lo @-mencionan.

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 slack establece channel en slack, lista los remitentes permitidos en external_peers (para slack, el ID de usuario de Slack; ["*"] 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

Slack necesita dos tokens: un token de bot (con el que habla el bot) y un token de aplicación (permite que el bot se conecte sin que tengas que alojar una URL pública). Ambos provienen de la misma página de la aplicación.

1. Crea la aplicación de Slack

1. Ve a api.slack.com/apps y haz clic en Create New App -> From scratch.
2. Asígnale un nombre, elige tu espacio de trabajo y haz clic en Create App.

2. Agrega los permisos que el bot necesita

1. En la barra lateral izquierda, abre OAuth & Permissions.
2. En Scopes -> Bot Token Scopes, agrega: app_mentions:read, channels:history, chat:write y channels:read. (Agrega también im:history e im:write si quieres mensajes directos.)

3. Activa el Modo Socket y obtén el token de la aplicación

1. En la barra lateral izquierda, abre Socket Mode y actívalo (on).
2. Slack te solicita crear un token a nivel de aplicación. Asígnale un nombre, otórgale el alcance connections:write y haz clic en Generate.
3. Copia el token que comienza con xapp-. Este es tu app_token.

Socket Mode permite que el bot mantenga una conexión saliente hacia Slack, por lo que no necesitas una URL pública de webhook ni ningún reenvío de puertos. Este es el camino fácil.

4. Instala la aplicación y obtén el token del bot

1. Abre Install App en la barra lateral y haz clic en Install to Workspace, luego en Allow.
2. De vuelta en OAuth & Permissions, copia el Bot User OAuth Token que comienza con xoxb-. Este es tu bot_token.

5. Informa a ZeroClaw sobre ambos tokens

Ambos tokens son secretos, así que configúralos a través de una superficie que los cifre:

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

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

Configura app_token de la misma manera (es el token xapp- del paso 3).

Alternativa con variables de entorno. Ambos tokens pueden suministrarse desde el entorno del daemon en lugar del archivo de configuración: bot_token se resuelve a partir de ZEROCLAW_SLACK_BOT_TOKEN y luego SLACK_BOT_TOKEN; app_token a partir de ZEROCLAW_SLACK_APP_TOKEN y luego SLACK_APP_TOKEN. Un valor en el archivo de configuración tiene prioridad sobre el entorno. Esto te permite omitir bot_token de config.toml por completo (por ejemplo, para gestores de secretos que inyectan variables de entorno) sin que la configuración falle al cargarse.

6. Invita al bot y pruébalo

En Slack, ve a un canal y escribe /invite @YourBotName. Luego envía un mensaje o menciona al bot con @. Inicia ZeroClaw (zeroclaw service restart o zeroclaw daemon) y debería responder. Si no, consulta Solución de problemas.

Configuración

La lista completa de campos, derivada del esquema en vivo. Para un bot básico de Socket Mode solo se configuran bot_token y app_token.

zeroclaw config set channels.slack.<alias>.app_token    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__slack__<alias>__app_token=

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

export ZEROCLAW_channels__slack__<alias>__approval_timeout_secs=

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

export ZEROCLAW_channels__slack__<alias>__bot_token=

zeroclaw config set channels.slack.<alias>.cancel_reaction <value>

export ZEROCLAW_channels__slack__<alias>__cancel_reaction=

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

export ZEROCLAW_channels__slack__<alias>__channel_ids=

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

export ZEROCLAW_channels__slack__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__slack__<alias>__excluded_tools=

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

export ZEROCLAW_channels__slack__<alias>__interrupt_on_new_message=

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

export ZEROCLAW_channels__slack__<alias>__mention_only=

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

export ZEROCLAW_channels__slack__<alias>__proxy_url=

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

export ZEROCLAW_channels__slack__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__slack__<alias>__reply_queue_depth_max=

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

export ZEROCLAW_channels__slack__<alias>__stream_drafts=

zeroclaw config set channels.slack.<alias>.strict_mention_in_thread <value>

export ZEROCLAW_channels__slack__<alias>__strict_mention_in_thread=

zeroclaw config set channels.slack.<alias>.thread_context_max_messages <value>

export ZEROCLAW_channels__slack__<alias>__thread_context_max_messages=

zeroclaw config set channels.slack.<alias>.thread_replies <value>

export ZEROCLAW_channels__slack__<alias>__thread_replies=

zeroclaw config set channels.slack.<alias>.use_markdown_blocks <value>

export ZEROCLAW_channels__slack__<alias>__use_markdown_blocks=

Modo Socket vs HTTP

Cuando app_token está configurado, el bot usa Socket Mode: establece la conexión saliente hacia Slack, por lo que no se requiere una URL pública. Esta es la configuración recomendada y la que usa el inicio rápido anterior. Sin un app_token, Slack debe comunicarse con tu bot a través de HTTP, lo que implica alojar un endpoint público de eventos, más configuración y más aspectos que proteger.

Hilos y contexto

Cuando una conversación de Slack 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. Para Slack esto se controla con thread_replies: cuando está activado, los mensajes de nivel superior abren un hilo y cada hilo es una conversación separada; cuando está desactivado, las respuestas se publican en la raíz del canal y el historial se indexa por remitente y destino en lugar de por hilo.

• 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.

Establece el comportamiento del hilo en cualquier superficie:

zeroclaw config set channels.slack.<alias>.thread_replies true     # respuestas de hilo activadas
zeroclaw config set channels.slack.<alias>.thread_replies false    # de respuestas en la raíz del canal

strict_mention_in_thread restringe esto aún más: cuando es true, el bot solo responde dentro de un hilo si un mensaje en él lo @-menciona, en lugar de responder a cada mensaje de un hilo del que forma parte.

En el primer mensaje que ZeroClaw procesa en un hilo existente, obtiene las respuestas anteriores y antepone un bloque limitado de [Thread context] para que el agente pueda responder teniendo en cuenta la conversación anterior. thread_context_max_messages controla cuántos de los mensajes anteriores más recientes disponibles dentro de la ventana de obtención se incluyen, manteniendo el orden cronológico. El valor predeterminado es 0, el máximo es 50 y 0 desactiva esta incorporación automática. Establece un valor explícito distinto de cero para habilitarla.

Una hidratación realiza como máximo tres intentos totales de conversations.replies, incluidos los reintentos tras respuestas HTTP 429. ZeroClaw respeta el valor Retry-After de Slack antes de reintentar mientras quede presupuesto de solicitudes. Si un hilo más largo aún tiene otra página, ZeroClaw usa el contexto parcial acotado, añade un marcador de omisión y registra el hilo como hidratado para que las respuestas posteriores no reinicien el análisis. Un error de la API de Slack no descarta el mensaje actual; omite la hidratación y libera la reserva para que la siguiente respuesta elegible pueda volver a intentarlo.

Menciones y formato

• mention_only: cuando es true, el bot solo responde a los mensajes que lo @-mencionan, manteniéndolo en silencio en canales con mucha actividad.
• use_markdown_blocks: muestra las respuestas con el formato Block Kit de Slack para un diseño más enriquecido. Desactívalo para texto sin formato.

Transmisión

Slack transmite respuestas en streaming mediante el booleano stream_drafts:

• false (predeterminado): toda la respuesta se publica como un solo mensaje una vez que el agente termina.
• true: el bot publica un marcador de posición de inmediato y lo edita en el lugar a medida que la respuesta se va transmitiendo. draft_update_interval_ms marca el ritmo de las ediciones; auméntalo si Slack las limita por tasa de solicitudes.

Colócalo sobre cualquier superficie:

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

draft_update_interval_ms controla la frecuencia con la que se edita el borrador en streaming (auméntalo si Slack limita la tasa de las ediciones), y cancel_reaction establece un emoji con el que los usuarios pueden reaccionar para cancelar una respuesta en curso.

Solución de problemas

Ver también

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