Instalación
- registro npm
- Checkout local
Configuración rápida
Asegúrate de que el Plugin esté disponible
Instala
@openclaw/mattermost con el comando anterior y luego reinicia el Gateway si ya está en ejecución.Crea un bot de Mattermost
Crea una cuenta de bot de Mattermost, copia el token del bot y añade el bot a los equipos y canales que deba leer.
Copia la URL base
Copia la URL base de Mattermost (por ejemplo,
https://chat.example.com). Un /api/v4 final se elimina automáticamente.Mattermost autoalojado en una dirección privada/LAN/tailnet: las solicitudes salientes a la API de Mattermost pasan por una protección SSRF que bloquea IP privadas e internas de forma predeterminada. Habilítalo explícitamente con
channels.mattermost.network.dangerouslyAllowPrivateNetwork: true (por cuenta: channels.mattermost.accounts.<id>.network.dangerouslyAllowPrivateNetwork).Comandos slash nativos
Los comandos slash nativos son opcionales. Cuando están habilitados, OpenClaw registra comandos slashoc_* en cada equipo del que el bot es miembro y recibe POST de callback en el servidor HTTP del Gateway.
/oc_status, /oc_model, /oc_models, /oc_new, /oc_help, /oc_think, /oc_reasoning, /oc_verbose, /oc_queue. Con nativeSkills: true, los comandos de Skills también se registran como /oc_<skill>.
Notas de comportamiento
Notas de comportamiento
nativeynativeSkillstienen el valor predeterminado"auto", que se resuelve como deshabilitado para Mattermost. Configúralos explícitamente comotrue.callbackPathtiene el valor predeterminado/api/channels/mattermost/command.- Si se omite
callbackUrl, OpenClaw derivahttp://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Los hosts de vinculación comodín (0.0.0.0,::) recurren alocalhost. - Para configuraciones de varias cuentas,
commandsse puede definir en el nivel superior o bajochannels.mattermost.accounts.<id>.commands(los valores de cuenta sobrescriben los campos de nivel superior). - Los comandos slash existentes con el mismo disparador creados por otras integraciones se dejan intactos (el registro los omite); los comandos creados por el bot se actualizan o recrean cuando la URL de callback deriva.
- Los callbacks de comandos se validan con los tokens por comando devueltos por Mattermost cuando OpenClaw registra comandos
oc_*. - OpenClaw actualiza el registro actual de comandos de Mattermost antes de aceptar cada callback, por lo que los tokens obsoletos de comandos slash eliminados o regenerados dejan de aceptarse sin reiniciar el Gateway.
- La validación de callback falla cerrada si la API de Mattermost no puede confirmar que el comando sigue vigente; las validaciones fallidas se almacenan brevemente en caché, las búsquedas concurrentes se fusionan y los inicios de búsquedas nuevas se limitan por frecuencia por comando para acotar la presión de reproducción.
- Los callbacks slash fallan cerrados cuando el registro falló, el inicio fue parcial o el token de callback no coincide con el token registrado del comando resuelto (un token válido para un comando no puede alcanzar la validación upstream para otro comando).
- Los callbacks aceptados se confirman con una respuesta efímera “Processing…”; la respuesta real llega como un mensaje normal.
Requisito de accesibilidad
Requisito de accesibilidad
El endpoint de callback debe ser accesible desde el servidor Mattermost.
- No configures
callbackUrlcomolocalhosta menos que Mattermost se ejecute en el mismo host/espacio de nombres de red que OpenClaw. - No configures
callbackUrlcomo tu URL base de Mattermost a menos que esa URL haga reverse proxy de/api/channels/mattermost/commandhacia OpenClaw. - Una comprobación rápida es
curl https://<gateway-host>/api/channels/mattermost/command; un GET debería devolver405 Method Not Alloweddesde OpenClaw, no404.
Lista de permitidos de salida de Mattermost
Lista de permitidos de salida de Mattermost
Si tu callback apunta a direcciones privadas/tailnet/internas, configura
ServiceSettings.AllowedUntrustedInternalConnections de Mattermost para incluir el host/dominio del callback.Usa entradas de host/dominio, no URL completas.- Correcto:
gateway.tailnet-name.ts.net - Incorrecto:
https://gateway.tailnet-name.ts.net
Variables de entorno (cuenta predeterminada)
Configúralas en el host del Gateway si prefieres variables de entorno:MATTERMOST_BOT_TOKEN=...MATTERMOST_URL=https://chat.example.com
Las variables de entorno se aplican solo a la cuenta predeterminada (
default). Otras cuentas deben usar valores de configuración.MATTERMOST_URL no se puede definir desde un .env del workspace; consulta Archivos .env de workspace.Modos de chat
Mattermost responde automáticamente a los DM. El comportamiento en canales se controla conchatmode:
- oncall (predeterminado)
- onmessage
- onchar
Responde solo cuando se le @menciona en canales.
oncharsigue respondiendo a @menciones explícitas.channels.mattermost.requireMentionse sigue respetando, pero se prefierechatmode. Las opciones por canalgroups.<channelId>.requireMentionprevalecen sobre ambas.- Después de que el bot envía una respuesta visible en un hilo de canal, los mensajes posteriores en ese mismo hilo se responden sin una nueva @mención ni prefijo
onchar, por lo que las conversaciones de hilo de varios turnos siguen fluyendo. La participación se recuerda durante 7 días después de la última respuesta del bot en ese hilo y persiste entre reinicios del Gateway. Los hilos que el bot solo ha observado no se ven afectados; inicia un nuevo mensaje de nivel superior para exigir de nuevo una mención explícita.
Hilos y sesiones
Usachannels.mattermost.replyToMode para controlar si las respuestas de canales y grupos permanecen en el canal principal o inician un hilo bajo la publicación disparadora.
off(predeterminado): solo responde en un hilo cuando la publicación entrante ya está en uno.first: para publicaciones de canal/grupo de nivel superior, inicia un hilo bajo esa publicación y enruta la conversación a una sesión con alcance de hilo.allybatched: el mismo comportamiento quefirstpara Mattermost hoy, porque una vez que Mattermost tiene una raíz de hilo, los fragmentos y medios posteriores continúan en ese mismo hilo.- Los mensajes directos ignoran esta opción y permanecen sin hilos.
Control de acceso (DM)
- Predeterminado:
channels.mattermost.dmPolicy = "pairing"(los remitentes desconocidos reciben un código de vinculación). Otros valores:allowlist,open,disabled. - Aprueba con:
openclaw pairing list mattermostopenclaw pairing approve mattermost <CODE>
- DM públicos:
channels.mattermost.dmPolicy="open"máschannels.mattermost.allowFrom=["*"](el esquema de configuración exige el comodín). channels.mattermost.allowFromacepta ids de usuario (recomendado) y entradasaccessGroup:<name>. Consulta Grupos de acceso.
Canales (grupos)
- Predeterminado:
channels.mattermost.groupPolicy = "allowlist"(restringido por mención). - Permite remitentes con
channels.mattermost.groupAllowFrom(se recomiendan IDs de usuario). channels.mattermost.groupAllowFromacepta entradasaccessGroup:<name>. Consulta Grupos de acceso.- Las sobrescrituras de mención por canal viven bajo
channels.mattermost.groups.<channelId>.requireMentionochannels.mattermost.groups["*"].requireMentionpara un valor predeterminado. - La coincidencia de
@usernamees mutable y solo está habilitada cuandochannels.mattermost.dangerouslyAllowNameMatching: true. - Canales abiertos:
channels.mattermost.groupPolicy="open"(restringido por mención). - Orden de resolución:
channels.mattermost.groupPolicy, luegochannels.defaults.groupPolicy, luego"allowlist". - Nota de runtime: si falta por completo la sección
channels.mattermost, el runtime falla cerrado agroupPolicy="allowlist"para comprobaciones de grupo (incluso sichannels.defaults.groupPolicyestá definido) y registra una advertencia única.
Destinos para entrega saliente
Usa estos formatos de destino conopenclaw message send o cron/webhooks:
| Destino | Entrega a |
|---|---|
channel:<id> | Canal por id |
channel:<name> o #channel-name | Canal por nombre, buscado entre los equipos a los que pertenece el bot |
user:<id> o mattermost:<id> | DM con ese usuario |
@username | DM (nombre de usuario resuelto mediante la API de Mattermost) |
Reintento de canal de DM
Cuando OpenClaw envía a un destino de DM de Mattermost y necesita resolver primero el canal directo, reintenta de forma predeterminada los fallos transitorios de creación de canal directo. Usachannels.mattermost.dmChannelRetry para ajustar ese comportamiento globalmente para el Plugin de Mattermost, o channels.mattermost.accounts.<id>.dmChannelRetry para una cuenta. Valores predeterminados:
- Esto se aplica solo a la creación de canal de DM (
/api/v4/channels/direct), no a cada llamada a la API de Mattermost. - Los reintentos usan backoff exponencial con jitter y se aplican a fallos transitorios como límites de frecuencia, respuestas 5xx y errores de red o timeout.
- Los errores de cliente 4xx distintos de
429se tratan como permanentes y no se reintentan.
Streaming de vista previa
Mattermost transmite el razonamiento, la actividad de herramientas y el texto parcial de respuesta en una única publicación de vista previa de borrador que se finaliza en el mismo lugar cuando la respuesta final es segura para enviarse. La vista previa se actualiza en el mismo id de publicación en lugar de saturar el canal con mensajes por fragmento. Las respuestas finales de medios/errores cancelan las ediciones pendientes de la vista previa y usan la entrega normal en lugar de vaciar una publicación de vista previa descartable. La transmisión de vista previa está activada de forma predeterminada en modopartial. Configúrala mediante channels.mattermost.streaming (una cadena de modo, un booleano o un objeto como { mode: "progress" }):
Modos de transmisión
Modos de transmisión
partial(predeterminado): una publicación de vista previa que se edita a medida que crece la respuesta y luego se finaliza con la respuesta completa.blockusa fragmentos de borrador de estilo anexado dentro de la publicación de vista previa.progressmuestra una vista previa de estado mientras se genera y solo publica la respuesta final al completarse.offdesactiva la transmisión de vista previa.
Notas sobre el comportamiento de transmisión
Notas sobre el comportamiento de transmisión
- Si la transmisión no se puede finalizar en el mismo lugar (por ejemplo, si la publicación se eliminó a mitad de transmisión), OpenClaw vuelve a enviar una publicación final nueva para que la respuesta nunca se pierda.
- Las cargas útiles solo de razonamiento se suprimen de las publicaciones del canal, incluido el texto que llega como una cita en bloque
> Thinking. Configura/reasoning onpara ver el razonamiento en otras superficies; la publicación final de Mattermost conserva solo la respuesta. - Consulta Transmisión para ver la matriz de asignación de canales.
Reacciones (herramienta de mensajes)
- Usa
message action=reactconchannel=mattermost. messageIdes el id de publicación de Mattermost.emojiacepta nombres comothumbsupo:+1:(los dos puntos son opcionales).- Configura
remove=true(booleano) para eliminar una reacción. - Los eventos de agregar/eliminar reacción se reenvían como eventos del sistema a la sesión de agente enrutada, sujetos a las mismas comprobaciones de política de DM/grupo que los mensajes.
channels.mattermost.actions.reactions: activa/desactiva acciones de reacción (predeterminado true).- Anulación por cuenta:
channels.mattermost.accounts.<id>.actions.reactions.
Botones interactivos (herramienta de mensajes)
Envía mensajes con botones clicables. Cuando un usuario hace clic en un botón, el agente recibe la selección y puede responder. Los botones provienen de la carga útil semánticapresentation (en respuestas normales del agente y en message action=send). OpenClaw renderiza los botones de valor como botones interactivos de Mattermost, mantiene visibles los botones de URL en el texto del mensaje y degrada los menús de selección a texto legible.
Etiqueta visible (alias:
text).Valor enviado de vuelta al hacer clic, usado como ID de acción (alias:
callback_data, callbackData). Obligatorio para un botón clicable salvo que url esté configurado.Botón de enlace; se renderiza como texto
label: url en el cuerpo del mensaje en lugar de como botón interactivo.Estilo del botón. Mattermost aplica el estilo predeterminado a los valores que no admite.
inlineButtons a las capacidades del canal:
Comprobación de acceso
Quien hace clic debe pasar las mismas comprobaciones de política de DM/grupo que quien envía un mensaje; los clics no autorizados reciben un aviso efímero y se ignoran.
Botones reemplazados por confirmación
Todos los botones se reemplazan por una línea de confirmación (por ejemplo, ”✓ Yes selected by @user”).
Notas de implementación
Notas de implementación
- Las devoluciones de llamada de botones usan verificación HMAC-SHA256 (automática, sin configuración necesaria).
- Todo el bloque de adjunto se reemplaza al hacer clic, por lo que todos los botones se eliminan juntos; no es posible la eliminación parcial.
- Los ID de acción que contienen guiones o guiones bajos se sanea automáticamente (limitación de enrutamiento de Mattermost).
- Los clics cuyo
action_idno coincide con una acción de la publicación original se rechazan con403(“Unknown action”).
Configuración y accesibilidad
Configuración y accesibilidad
channels.mattermost.capabilities: arreglo de cadenas de capacidad. Agrega"inlineButtons"para activar la descripción de la herramienta de botones en el prompt del sistema del agente.channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para devoluciones de llamada de botones (por ejemplo,https://gateway.example.com). Úsala cuando Mattermost no pueda alcanzar el Gateway directamente en su host de enlace.- En configuraciones con varias cuentas, también puedes establecer el mismo campo en
channels.mattermost.accounts.<id>.interactions.callbackBaseUrl. - Si se omite
interactions.callbackBaseUrl, OpenClaw deriva la URL de devolución de llamada degateway.customBindHost+gateway.port(predeterminado 18789) y luego recurre ahttp://localhost:<port>. La ruta de devolución de llamada es/mattermost/interactions/<accountId>. - Regla de accesibilidad: la URL de devolución de llamada del botón debe ser accesible desde el servidor Mattermost.
localhostsolo funciona cuando Mattermost y OpenClaw se ejecutan en el mismo host/espacio de nombres de red. channels.mattermost.interactions.allowedSourceIps: lista de IP de origen permitidas para devoluciones de llamada de botones. Sin ella, solo se aceptan orígenes de loopback (127.0.0.1,::1), por lo que un servidor Mattermost remoto debe estar permitido aquí o sus clics se rechazan con403. Detrás de un proxy inverso, configura tambiéngateway.trustedProxiespara que la IP real del cliente se derive de los encabezados reenviados.- Si tu destino de devolución de llamada es privado/tailnet/interno, agrega su host/dominio a
ServiceSettings.AllowedUntrustedInternalConnectionsde Mattermost.
Integración directa con API (scripts externos)
Los scripts externos y webhooks pueden publicar botones directamente mediante la API REST de Mattermost en lugar de pasar por la herramientamessage del agente. Usa buildButtonAttachments() del plugin cuando sea posible; si publicas JSON sin procesar, sigue estas reglas:
Estructura de la carga útil:
Derivar el secreto del token del bot
HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken), codificado en hexadecimal.Construir el objeto de contexto
Construye el objeto de contexto con todos los campos excepto
_token.Serializar con claves ordenadas
Serializa con claves ordenadas recursivamente y sin espacios (el gateway también canonicaliza objetos anidados y produce JSON compacto).
Problemas comunes con HMAC
Problemas comunes con HMAC
json.dumpsde Python agrega espacios de forma predeterminada ({"key": "val"}). Usaseparators=(",", ":")para coincidir con la salida compacta de JavaScript ({"key":"val"}).- Firma siempre todos los campos de contexto (menos
_token). El gateway elimina_tokeny luego firma todo lo restante. Firmar un subconjunto causa un fallo de verificación silencioso. - Usa
sort_keys=True; el gateway ordena las claves antes de firmar y Mattermost puede reordenar los campos de contexto al almacenar la carga útil. - Deriva el secreto del token del bot (determinista), no de bytes aleatorios. El secreto debe ser el mismo en el proceso que crea los botones y en el gateway que verifica.
Adaptador de directorio
El plugin de Mattermost incluye un adaptador de directorio que resuelve nombres de canales y usuarios mediante la API de Mattermost. Esto habilita destinos#channel-name y @username en openclaw message send y entregas de cron/webhook.
No se necesita configuración; el adaptador usa el token del bot de la configuración de la cuenta.
Varias cuentas
Mattermost admite varias cuentas enchannels.mattermost.accounts:
channels.mattermost.defaultAccount elige qué cuenta se usa cuando no se especifica ninguna.
Solución de problemas
No hay respuestas en canales
No hay respuestas en canales
Asegúrate de que el bot esté en el canal y menciónalo (oncall), usa un prefijo disparador (onchar) o configura
chatmode: "onmessage".Errores de autenticación o de varias cuentas
Errores de autenticación o de varias cuentas
- Comprueba el token del bot, la URL base y si la cuenta está activada.
- Problemas de varias cuentas: las variables de entorno solo se aplican a la cuenta
default. - Los hosts privados/LAN de Mattermost necesitan
network.dangerouslyAllowPrivateNetwork: true(la protección SSRF bloquea las IP privadas de forma predeterminada).
Los comandos slash nativos fallan
Los comandos slash nativos fallan
Unauthorized: invalid command token.: OpenClaw no aceptó el token de callback. Causas típicas:- el registro del comando slash falló o solo se completó parcialmente al inicio
- el callback está llegando al gateway o la cuenta equivocados
- Mattermost todavía tiene comandos antiguos que apuntan a un destino de callback anterior
- el gateway se reinició sin reactivar los comandos slash
- Si los comandos slash nativos dejan de funcionar, revisa los registros para
mattermost: failed to register slash commandsomattermost: native slash commands enabled but no commands could be registered. - Si se omite
callbackUrly los registros advierten que el callback se resolvió a una URL de loopback comohttp://localhost:18789/..., probablemente esa URL solo sea accesible cuando Mattermost se ejecuta en el mismo host/espacio de nombres de red que OpenClaw. En su lugar, define explícitamentecommands.callbackUrlcomo una URL accesible externamente.
Problemas con botones
Problemas con botones
- Los botones aparecen como cuadros blancos o no aparecen: los datos del botón están mal formados. Cada botón de presentación necesita un
labely unvalue(los botones a los que les falte cualquiera de los dos se descartan). - Los botones se renderizan, pero los clics no hacen nada: verifica que se pueda acceder al gateway desde el servidor Mattermost, que la IP del servidor Mattermost esté incluida en
channels.mattermost.interactions.allowedSourceIps(sin ello, solo se acepta loopback) y queServiceSettings.AllowedUntrustedInternalConnectionsincluya el host de callback para destinos privados. - Los botones devuelven 404 al hacer clic: es probable que el
iddel botón contenga guiones o guiones bajos. El enrutador de acciones de Mattermost falla con ID no alfanuméricos. Usa solo[a-zA-Z0-9]. - Los registros del Gateway muestran
rejected callback source: el clic provino de una IP fuera deinteractions.allowedSourceIps. Agrega a la lista de permitidos el servidor Mattermost o tu entrada, y configuragateway.trustedProxiesdetrás de un proxy inverso. - Los registros del Gateway muestran
invalid _token: discrepancia de HMAC. Comprueba que firmes todos los campos de contexto (no un subconjunto), que uses claves ordenadas y JSON compacto (sin espacios). Consulta la sección de HMAC anterior. - Los registros del Gateway muestran
missing _token in context: el campo_tokenno está en el contexto del botón. Asegúrate de incluirlo al construir la carga útil de integración. - El Gateway rechaza el clic con
Unknown action:context.action_idno coincide con ningúnidde acción en la publicación. Configura ambos con el mismo valor saneado. - El agente no ofrece botones: añade
capabilities: ["inlineButtons"]a la configuración del canal Mattermost.
Relacionado
- Enrutamiento de canales - enrutamiento de sesiones para mensajes
- Resumen de canales - todos los canales admitidos
- Grupos - comportamiento del chat grupal y control de menciones
- Emparejamiento - autenticación por DM y flujo de emparejamiento
- Seguridad - modelo de acceso y endurecimiento