Mattermost

Cliente REST v4 de sondeo y WebSocket. Por defecto, el bot sondea los canales cada 3 segundos en busca de nuevas publicaciones; establece listen_mode = "websocket" para la entrega de eventos en tiempo casi real a través de una conexión WebSocket persistente. Las publicaciones de respuesta siempre se envían mediante POST /api/v4/posts independientemente del modo de escucha.

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 mattermost establece channel en mattermost, enumera los remitentes permitidos en external_peers (para mattermost, el UUID de usuario de Mattermost (no un nombre de usuario); ["*"] 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 Grupos de Pares para la referencia de campos.

Dónde configurar esto:

Para incluir en la lista de permitidos a una persona específica, copie su ID de usuario desde System Console → User Management. Mattermost compara el UUID del usuario, no un nombre de usuario, y no resuelve nombres de usuario en el momento de recibir el mensaje.

Inicio rápido

Configura un canal de Mattermost (url más un secreto bot_token, consulta Autenticación) a través de una de las superficies a continuación. Solo con eso obtienes:

1. Detección automática de cada canal que el bot puede leer en todos los equipos a los que pertenece.
2. Los canales de MD y de MD grupales se descubren automáticamente y se sondean junto con los canales del equipo.
3. Los nuevos mensajes directos (creados después de que el bot se inicia) se detectan en la siguiente actualización de descubrimiento de 60 segundos.
4. mention_only se omite dentro de los canales de DM y group-DM (para que las conversaciones 1:1 no necesiten que se mencione al bot con @).

Para restringir el bot, acote con channel_ids, team_ids o discover_dms.

Configuración

bot_token y password son secretos:

channels.mattermost.<alias>.bot_token es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

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

Referencia de campos

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

export ZEROCLAW_channels__mattermost__<alias>__bot_token=

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

export ZEROCLAW_channels__mattermost__<alias>__channel_ids=

zeroclaw config set channels.mattermost.<alias>.discover_dms <value>

export ZEROCLAW_channels__mattermost__<alias>__discover_dms=

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

export ZEROCLAW_channels__mattermost__<alias>__excluded_tools=

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

export ZEROCLAW_channels__mattermost__<alias>__interrupt_on_new_message=

zeroclaw config set channels.mattermost.<alias>.listen_mode <value>

export ZEROCLAW_channels__mattermost__<alias>__listen_mode=

zeroclaw config set channels.mattermost.<alias>.login_id <value>

export ZEROCLAW_channels__mattermost__<alias>__login_id=

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

export ZEROCLAW_channels__mattermost__<alias>__mention_only=

zeroclaw config set channels.mattermost.<alias>.password    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__mattermost__<alias>__password=

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

export ZEROCLAW_channels__mattermost__<alias>__proxy_url=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_queue_depth_max=

zeroclaw config set channels.mattermost.<alias>.team_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__team_ids=

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

export ZEROCLAW_channels__mattermost__<alias>__thread_replies=

zeroclaw config set channels.mattermost.<alias>.url <value>

export ZEROCLAW_channels__mattermost__<alias>__url=

Descubrimiento de canales

Hay dos modos de alcance.

1. Detección automática (cuando channel_ids está vacío o es ["*"]). Al iniciar y cada 60 segundos a partir de entonces, el bot llama a GET /api/v4/users/me/channels, filtra el resultado por team_ids (canales públicos/privados) y discover_dms (DMs/DMs grupales), y sondea cada canal restante. Los nuevos DMs creados durante la ejecución aparecen en la siguiente actualización.
2. Explícito (cuando channel_ids es una lista no vacía de IDs distintos de *). Al iniciarse, el bot llama a GET /api/v4/channels/{id} para cada entrada con el fin de conocer su type (de modo que sepa cuáles son DMs para la excepción de mention_only), y luego sondea exactamente esos canales de forma indefinida. Sin redescubrimiento periódico.

En ambos modos cada canal tiene su propio cursor since: el bot rastrea el create_at más alto que ha procesado por canal y lo pasa como since=<ms> en la siguiente llamada GET /api/v4/channels/{id}/posts. Los cursores no se filtran entre canales, por lo que un canal de movimiento lento no suprime las publicaciones en uno activo.

Modo WebSocket

Establece listen_mode = "websocket" para cambiar del sondeo REST a una conexión WebSocket persistente (wss://<server>/api/v4/websocket). El modo WebSocket:

• Entrega nuevas publicaciones en tiempo casi real (sin retraso de sondeo de 3 segundos).
• Reduce la carga HTTP en el servidor Mattermost (una conexión frente a N sondeos/3s).
• Devuelve las sesiones fallidas al supervisor de canales compartido, que se reconecta mediante un retroceso exponencial acotado usando los valores configurados de reliability.channel_initial_backoff_secs y reliability.channel_max_backoff_secs.
• Requiere Mattermost v4.0+ (el endpoint /api/v4/websocket).

El descubrimiento de canales, mention_only, thread_replies, la transcripción de audio y la autorización de grupos de pares funcionan de manera idéntica en ambos modos.

Compromisos:

• El modo WebSocket debe mantener una conexión TCP+TLS persistente.
• Durante una ventana de reconexión, pueden perderse mensajes publicados en un canal porque este listener aún no solicita la reanudación/repetición de la conexión de Mattermost. El sondeo se pone al día mediante cursores since=.
• El modo de sondeo es más resistente a las interrupciones transitorias de red, a costa de un tráfico HTTP constante.

Para revertir, establece listen_mode = "polling" (o elimina el campo; polling es el valor predeterminado).

Mensajes directos

Mattermost clasifica los canales por type:

G y D reciben el mismo tratamiento por parte de ZeroClaw: ninguno de los dos lleva team_id, ambos están controlados por discover_dms y ambos omiten implícitamente mention_only (una conversación privada no tiene ruido ambiental contra el que filtrar).

La autorización para los remitentes de DM sigue pasando por el resolutor de grupos de pares del canal, igual que cualquier otro canal. discover_dms es un ajuste, no un límite de seguridad; los grupos de pares deciden quién está autorizado a dirigirse al agente.

Hilo

1. La publicación entrante está dentro de un hilo existente (root_id está definido) → la respuesta siempre se ubica en ese hilo, independientemente de thread_replies.
2. La publicación entrante es de nivel superior y thread_replies = true (predeterminado) → la respuesta abre un hilo basado en la publicación entrante.
3. La publicación entrante es de nivel superior y thread_replies = false → la respuesta se publica en la raíz del canal.

Gestión de contexto

Cuando una conversación de Mattermost 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 tiene 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 Mattermost 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.mattermost.<alias>.thread_replies true     # respuestas de hilo activadas
zeroclaw config set channels.mattermost.<alias>.thread_replies false    # de respuestas en la raíz del canal

Autenticación

Dos rutas:

1. Token de bot (recomendado). Créalo en System Console → Integrations → Bot Accounts, copia el token de acceso y guárdalo en bot_token. Los tokens sobreviven a los cambios de contraseña y son más fáciles de revocar.
2. Flujo de inicio de sesión. Configura login_id (email o nombre de usuario) y password. El bot llama a POST /api/v4/users/login al iniciar y almacena en caché el token de sesión devuelto en memoria. Sin persistencia en disco.

bot_token tiene prioridad cuando ambos están configurados.

Mensajes de voz

Cuando [transcription] está configurado y una publicación entrante tiene un adjunto de audio (tipo MIME audio/* o extensión ogg/mp3/m4a/wav/opus/flac) sin cuerpo de texto, el audio se descarga mediante GET /api/v4/files/{file_id} y se enruta a través del proveedor de transcripción configurado. La transcripción se prefija con [Voice] y se convierte en el contenido del mensaje. Los adjuntos de más de 25 MB o con una duración superior a transcription.max_duration_secs se descartan con una advertencia WARN.

Configuración

1. En Mattermost: System Console → Integrations → Bot Accounts → Add Bot Account. Define un nombre de usuario (p. ej. zeroclaw), habilita los scopes que quieras.
2. Copia el token de acceso. Almacénalo en tu backend de secretos de ZeroClaw.
3. Invita al bot a los equipos en los que quieras que esté activo. Para la detección automática de mensajes directos, no se necesitan invitaciones adicionales: cualquier usuario puede enviar un mensaje directo al bot.
4. Crea el canal mattermost.<alias> haciendo referencia al token a través del gateway, zerocode o zeroclaw config set.
5. Vincula el canal a un agente en [agents.<alias>] mediante channels = ["mattermost.<alias>"].

Notas operativas

1. La cadencia de sondeo es de 3 segundos por canal. N canales descubiertos = N llamadas HTTP cada 3 segundos contra el servidor de Mattermost. Las configuraciones predeterminadas autoalojadas manejan esto fácilmente; si estás en un tenant de nube compartido con límites de tasa estrictos, considera acotar el alcance con channel_ids o team_ids.
2. La identidad del bot se obtiene una vez mediante GET /api/v4/users/me y se almacena en caché durante toda la vida del proceso. Los cambios de nombre de usuario requieren reiniciar.
3. El token de sesión del flujo de inicio de sesión con contraseña solo se mantiene en memoria. Un reinicio vuelve a iniciar sesión.

Ver también

• Visión general de los canales
• Grupos de pares
• Referencia: esquema de configuración