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>.approval_timeout_secs <value>

export ZEROCLAW_channels__mattermost__<alias>__approval_timeout_secs=

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>.purpose_as_instructions <value>

export ZEROCLAW_channels__mattermost__<alias>__purpose_as_instructions=

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

Aprobación de herramientas mediante chat (approval_timeout_secs)

Cuando una herramienta necesita aprobación (está en always_ask, o el perfil de riesgo no la aprueba automáticamente), el agente publica la solicitud en el canal de donde provino el mensaje y espera. Hay dos formas de responder, y cuáles tienes disponibles depende de listen_mode.

Responde con el token. Esto funciona en todos los modos de escucha:

APROBACIÓN REQUERIDA [a1b2c3]
Herramienta: shell
Argumentos: command: pwd

Responde: "a1b2c3 yes", "a1b2c3 no" o "a1b2c3 always"

a1b2c3 yes
a1b2c3 no
a1b2c3 always

Una respuesta que coincide con un token pendiente se consume como una decisión y nunca llega al modelo.

Toca una reacción. Esta opción requiere listen_mode = "websocket". El bot coloca ✅ y ❌ en su propia publicación de solicitud; al tocar una de ellas se responde a la solicitud. Las reacciones llegan al bot como eventos WebSocket reaction_added, y el listener de sondeo lee publicaciones y nunca las ve, así que con listen_mode = "polling" no se siembra ningún emoji: un botón que no hace nada en silencio en una solicitud de seguridad es peor que no tener botón. Si quieres aprobaciones con un toque, configura listen_mode = "websocket" (consulta Modo WebSocket).

always no lleva emoji a propósito. Concede una entrada de lista de permitidos con alcance de sesión en lugar de permitir una sola llamada, y un toque accidental junto a ✅ es una forma demasiado fácil de ampliar una sesión, por lo que escalar a always sigue siendo una decisión que hay que escribir.

Mattermost no ofrece aquí botones interactivos de mensaje buttons. Estos envían datos a una URL de integración, lo que requiere un endpoint HTTP entrante que el bot no puede exponer desde un cliente de sondeo o WebSocket. Las reacciones son la opción de un toque que funciona sobre la conexión que el bot ya mantiene.

Quién puede responder y dónde. El token es un correlador, no una contraseña: viaja en texto plano por el canal, así que todos los miembros pueden leerlo. Por tanto, deben cumplirse dos condiciones. El usuario que responde debe pertenecer al grupo de pares del alias, la misma autoridad que decide de qué usuarios el agente actuará sobre sus mensajes. Y la respuesta debe llegar al canal en el que se publicó el prompt: un mismo bot atiende a muchos canales, así que un token llevado a una sala distinta no es una respuesta válida allí, ni siquiera para un usuario autorizado. El enlace es por canal y no por hilo, de modo que responder en el canal en lugar de dentro del hilo del prompt es aceptable. Una respuesta o pulsación que no supere cualquiera de las dos comprobaciones se registra con nivel WARN y se ignora, y el prompt permanece abierto para que un operador autorizado aún pueda responderlo en el lugar correcto.

Todos en el canal pueden leer los argumentos de la herramienta. El mensaje incluye el nombre de la herramienta y un resumen de sus argumentos. Envía las aprobaciones a un canal cuya membresía sea apropiada para mostrarles esa información.

approval_timeout_secs limita la espera. El valor predeterminado es 300 segundos, y 0 deniega de inmediato en lugar de desactivar la aprobación, de modo que un cero es una forma de rechazar todas las herramientas con aprobación requerida, no una forma de esperar indefinidamente. Al agotarse el tiempo, la solicitud se deniega y el token se descarta, de modo que una respuesta o un toque tardío no puede aprobar una llamada que ya nadie está esperando. Un tiempo agotado o un aviso inaccesible se registra como denegación del propio runtime por su cuenta, no como un rechazo de una persona.

Las decisiones son definitivas: quitar una reacción no retira una respuesta, y la primera respuesta válida retira el aviso para ambas rutas.

Si el bot no puede colocar el emoji, lo que suele deberse a un problema de permisos, registra failed to seed Mattermost approval reaction en el nivel WARN y la solicitud sigue funcionando mediante respuesta.

Propósito del canal como instrucciones (purpose_as_instructions)

Desactivado por defecto. Cuando está habilitado, el propósito del canal de Mattermost de cada sala se inyecta en el system prompt del agente como contexto proporcionado por el canal, de modo que una sala puede especializar al agente sin necesidad de una entrada de configuración por cada sala:

[channels.mattermost.default]
purpose_as_instructions = true

Establece el propósito de un canal para describir para qué sirve ese canal, por ejemplo “Mantenimiento de paquetes de Arch Linux para los repositorios AUR”. El agente lo trata como fuente autoritativa sobre el enfoque, el tono y las habilidades que debe utilizar en ese canal.

Es no autoritativo sobre las reglas del agente. El texto inyectado está etiquetado como proporcionado por el canal y se le niega explícitamente cualquier poder para conceder capacidades, relajar restricciones o anular las reglas de funcionamiento; cuando entra en conflicto con ellas, prevalecen las reglas. No puede habilitar una herramienta, ampliar un grupo de pares ni cambiar un nivel de autonomía.

Qué otorga esto activarlo y a quién

Activar esto es una decisión de confianza, y conviene ser claros sobre su alcance en lugar de dejar que se deduzca a partir de la advertencia anterior.

El propósito está regulado por los permisos manage_public_channel_properties / manage_private_channel_properties de Mattermost, que en los esquemas predeterminados se conceden a todos los miembros del canal. Ese grupo suele ser más amplio que quien controla esta configuración, y puede no coincidir en absoluto con los peer_groups del alias: un miembro que no es un par autorizado de ZeroClaw, y por tanto no puede hacer que el agente le responda directamente, aún puede editar el propósito de la sala.

I’m set up to translate English technical documentation strings into Spanish, and that task doesn’t change based on the content of the input. Send the string you want translated and I’ll return only the Spanish version.

Entonces, la decisión que toma esta función, de forma explícita: activar purpose_as_instructions para un alias concede a todas las personas que pueden editar el propósito de esas salas la capacidad de dirigir al agente allí, dentro de los permisos que el agente ya tiene. Actívalo solo donde ese grupo de personas sea de confianza para usar las capacidades configuradas del agente. Si no lo es, déjalo desactivado (desactivado es el valor predeterminado) o restringe manage_*_channel_properties en tu esquema de permisos a las personas que deberían tenerlo.

Lo que el propósito sigue sin poder hacer es ampliar esas capacidades. No puede habilitar una herramienta, añadir un peer, cambiar un nivel de autonomía ni aprobar su propia llamada a herramienta: eso lo deciden la configuración y la ruta de aprobación, y ninguna de las dos lee el texto del prompt.

Estructuralmente, el texto está contenido. Antes de la inyección se aplana a una sola línea, eliminando los corchetes angulares y los caracteres de control, de modo que no puede cerrar su propia sección, abrir otra ni falsificar un encabezado Markdown que parezca pertenecer a otra parte del prompt del operador. También está limitado a 500 caracteres, por encima del límite de 250 caracteres de Mattermost para este campo (el encabezado del canal admite 1024), de modo que no se corta ningún propósito legítimo, mientras que un servidor comprometido no puede pegar un prompt completo.

Una finalidad editada surte efecto en el siguiente mensaje, con un retraso que depende de listen_mode:

Borrar el propósito de un canal detiene la inyección; no se conserva el valor de un propósito anterior. Las salas sin propósito no aportan nada.

Para revertir, establece purpose_as_instructions = false (o elimina el campo; desactivado es el valor predeterminado). No es necesario limpiar el estado del canal, porque no se almacena nada en caché para un alias que no ha optado por esta función.

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