Mattermost

Estado: plugin descargable (token de bot + eventos WebSocket). Se admiten canales, grupos y MD. Mattermost es una plataforma de mensajería de equipo autohospedable; consulta el sitio oficial en mattermost.com para ver detalles del producto y descargas.

# Instalar

Instala Mattermost antes de configurar el canal:

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./path/to/local/mattermost-plugin

Detalles: Plugins

# Configuración rápida

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

# Comandos slash nativos

Los comandos slash nativos son opcionales. Cuando están habilitados, OpenClaw registra comandos slash oc_* mediante la API de Mattermost y recibe POSTs de callback en el servidor HTTP del gateway.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

# 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

# Modos de chat

Mattermost responde a los MD automáticamente. El comportamiento de canal lo controla chatmode:

Ejemplo de configuración:

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

Notas:

• onchar sigue respondiendo a menciones @ explícitas.
• channels.mattermost.requireMention se respeta para configuraciones heredadas, pero se prefiere chatmode.

# Hilos y sesiones

Usa channels.mattermost.replyToMode para controlar si las respuestas de canales y grupos permanecen en el canal principal o inician un hilo bajo la publicación que las disparó.

• off (predeterminado): responde en un hilo solo cuando la publicación entrante ya está en uno.
• first: para publicaciones de nivel superior de canal/grupo, inicia un hilo bajo esa publicación y enruta la conversación a una sesión con ámbito de hilo.
• all: el mismo comportamiento que first para Mattermost hoy.
• Los mensajes directos ignoran este ajuste y permanecen sin hilo.

Ejemplo de configuración:

{
  channels: {
    mattermost: {
      replyToMode: "all",
    },
  },
}

Notas:

• Las sesiones con ámbito de hilo usan el id de la publicación disparadora como raíz del hilo.
• first y all son actualmente equivalentes porque, una vez que Mattermost tiene una raíz de hilo, los fragmentos de seguimiento y los medios continúan en ese mismo hilo.

# Control de acceso (MD)

• Predeterminado: channels.mattermost.dmPolicy = "pairing" (los remitentes desconocidos reciben un código de emparejamiento).
• Aprueba mediante:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• MD públicos: channels.mattermost.dmPolicy="open" más channels.mattermost.allowFrom=["*"].

# Canales (grupos)

• Predeterminado: channels.mattermost.groupPolicy = "allowlist" (controlado por mención).
• Permite remitentes con channels.mattermost.groupAllowFrom (se recomiendan IDs de usuario).
• Las anulaciones de mención por canal están bajo channels.mattermost.groups.<channelId>.requireMention o channels.mattermost.groups["*"].requireMention para un valor predeterminado.
• La coincidencia de @username es mutable y solo se habilita cuando channels.mattermost.dangerouslyAllowNameMatching: true.
• Canales abiertos: channels.mattermost.groupPolicy="open" (controlados por mención).
• Nota de runtime: si falta por completo channels.mattermost, el runtime recurre a groupPolicy="allowlist" para las comprobaciones de grupo (aunque channels.defaults.groupPolicy esté definido).

Ejemplo:

{
  channels: {
    mattermost: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
    },
  },
}

# Destinos para entrega saliente

Usa estos formatos de destino con openclaw message send o cron/webhooks:

• channel:<id> para un canal
• user:<id> para un MD
• @username para un MD (resuelto mediante la API de Mattermost)

# Reintento de canal de MD

Cuando OpenClaw envía a un destino de MD de Mattermost y primero necesita resolver el canal directo, reintenta de forma predeterminada los fallos transitorios de creación de canal directo.

Usa channels.mattermost.dmChannelRetry para ajustar ese comportamiento globalmente para el plugin de Mattermost, o channels.mattermost.accounts.<id>.dmChannelRetry para una cuenta.

{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

Notas:

• Esto se aplica solo a la creación de canales de MD (/api/v4/channels/direct), no a cada llamada a la API de Mattermost.
• Los reintentos 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 429 se tratan como permanentes y no se reintentan.

# Streaming de vista previa

Mattermost transmite el razonamiento, la actividad de herramientas y el texto parcial de la respuesta en una única publicación de vista previa de borrador que se finaliza en su lugar cuando la respuesta final es segura para enviar. La vista previa se actualiza en el mismo id de publicación en lugar de saturar el canal con mensajes por fragmento. Los finales de medios/error cancelan las ediciones de vista previa pendientes y usan la entrega normal en lugar de vaciar una publicación de vista previa descartable.

Habilítalo mediante channels.mattermost.streaming:

{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

# Reacciones (herramienta de mensajes)

• Usa message action=react con channel=mattermost.
• messageId es el id de publicación de Mattermost.
• emoji acepta nombres como thumbsup o :+1: (los dos puntos son opcionales).
• Establece remove=true (booleano) para eliminar una reacción.
• Los eventos de añadir/eliminar reacción se reenvían como eventos del sistema a la sesión de agente enrutada.

Ejemplos:

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

Configuración:

• channels.mattermost.actions.reactions: habilita/deshabilita 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.

Habilita los botones añadiendo inlineButtons a las capacidades del canal:

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

Usa message action=send con un parámetro buttons. Los botones son un array 2D (filas de botones):

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

Campos de botón:

Cuando un usuario hace clic en un botón:

# 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 herramienta message del agente. Usa buildButtonAttachments() del Plugin cuando sea posible; si publicas JSON sin procesar, sigue estas reglas:

Estructura de la carga útil:

{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only - see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

Generación de tokens HMAC

El Gateway verifica los clics de botones con HMAC-SHA256. Los scripts externos deben generar tokens que coincidan con la lógica de verificación del Gateway:

Ejemplo en Python:

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

# 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 por 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 en channels.mattermost.accounts:

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

# Solución de problemas

# Relacionado

• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Resumen de canales - todos los canales admitidos
• Grupos - comportamiento de chat grupal y control por menciones
• Emparejamiento - autenticación por DM y flujo de emparejamiento
• Seguridad - modelo de acceso y endurecimiento