Mattermost

Stato: Plugin scaricabile (token del bot + eventi WebSocket). Sono supportati canali, gruppi e DM. Mattermost è una piattaforma di messaggistica per team self-hostable; consulta il sito ufficiale su mattermost.com per dettagli sul prodotto e download.

# Installazione

Installa Mattermost prima di configurare il canale:

openclaw plugins install @openclaw/mattermost

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

Dettagli: Plugin

# Configurazione rapida

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

# Comandi slash nativi

I comandi slash nativi sono opzionali. Quando sono abilitati, OpenClaw registra i comandi slash oc_* tramite l'API Mattermost e riceve POST di callback sul server 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",
      },
    },
  },
}

# Variabili d'ambiente (account predefinito)

Impostale sull'host del Gateway se preferisci le variabili d'ambiente:

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

# Modalità chat

Mattermost risponde automaticamente ai DM. Il comportamento dei canali è controllato da chatmode:

Esempio di configurazione:

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

Note:

• onchar risponde comunque alle @menzioni esplicite.
• channels.mattermost.requireMention è rispettato per le configurazioni legacy, ma chatmode è preferito.

# Threading e sessioni

Usa channels.mattermost.replyToMode per controllare se le risposte in canali e gruppi restano nel canale principale o avviano un thread sotto il post che le ha attivate.

• off (predefinito): risponde in un thread solo quando il post in ingresso è già in un thread.
• first: per post di canale/gruppo di livello superiore, avvia un thread sotto quel post e instrada la conversazione a una sessione con ambito thread.
• all: stesso comportamento di first per Mattermost oggi.
• I messaggi diretti ignorano questa impostazione e restano senza thread.

Esempio di configurazione:

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

Note:

• Le sessioni con ambito thread usano l'id del post che ha attivato la conversazione come radice del thread.
• first e all sono attualmente equivalenti perché, una volta che Mattermost ha una radice del thread, i chunk successivi e i media continuano nello stesso thread.

# Controllo degli accessi (DM)

• Predefinito: channels.mattermost.dmPolicy = "pairing" (i mittenti sconosciuti ricevono un codice di abbinamento).
• Approva tramite:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DM pubblici: channels.mattermost.dmPolicy="open" più channels.mattermost.allowFrom=["*"].

# Canali (gruppi)

• Predefinito: channels.mattermost.groupPolicy = "allowlist" (con gating tramite menzione).
• Inserisci i mittenti in allowlist con channels.mattermost.groupAllowFrom (ID utente consigliati).
• Le sostituzioni per-canale delle menzioni si trovano sotto channels.mattermost.groups.<channelId>.requireMention o channels.mattermost.groups["*"].requireMention per un valore predefinito.
• La corrispondenza @username è mutabile ed è abilitata solo quando channels.mattermost.dangerouslyAllowNameMatching: true.
• Canali aperti: channels.mattermost.groupPolicy="open" (con gating tramite menzione).
• Nota runtime: se channels.mattermost è completamente assente, il runtime ripiega su groupPolicy="allowlist" per i controlli sui gruppi (anche se channels.defaults.groupPolicy è impostato).

Esempio:

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

# Destinazioni per la consegna in uscita

Usa questi formati di destinazione con openclaw message send o cron/Webhook:

• channel:<id> per un canale
• user:<id> per un DM
• @username per un DM (risolto tramite l'API Mattermost)

# Nuovo tentativo per canale DM

Quando OpenClaw invia a una destinazione DM Mattermost e deve prima risolvere il canale diretto, riprova per impostazione predefinita gli errori transitori di creazione del canale diretto.

Usa channels.mattermost.dmChannelRetry per regolare globalmente questo comportamento per il Plugin Mattermost, oppure channels.mattermost.accounts.<id>.dmChannelRetry per un account.

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

Note:

• Si applica solo alla creazione del canale DM (/api/v4/channels/direct), non a ogni chiamata API Mattermost.
• I nuovi tentativi si applicano a errori transitori come limiti di frequenza, risposte 5xx ed errori di rete o timeout.
• Gli errori client 4xx diversi da 429 sono trattati come permanenti e non vengono riprovati.

# Streaming dell'anteprima

Mattermost trasmette pensieri, attività degli strumenti e testo parziale della risposta in un unico post di anteprima bozza che viene finalizzato sul posto quando la risposta finale è sicura da inviare. L'anteprima si aggiorna sullo stesso id del post invece di riempire il canale con messaggi per chunk. I finali con media/errori annullano le modifiche di anteprima in sospeso e usano la consegna normale invece di scaricare un post di anteprima usa e getta.

Abilita tramite channels.mattermost.streaming:

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

# Reazioni (strumento messaggi)

• Usa message action=react con channel=mattermost.
• messageId è l'id del post Mattermost.
• emoji accetta nomi come thumbsup o :+1: (i due punti sono facoltativi).
• Imposta remove=true (booleano) per rimuovere una reazione.
• Gli eventi di aggiunta/rimozione delle reazioni vengono inoltrati come eventi di sistema alla sessione dell'agente instradata.

Esempi:

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

Configurazione:

• channels.mattermost.actions.reactions: abilita/disabilita le azioni di reazione (predefinito true).
• Sostituzione per-account: channels.mattermost.accounts.<id>.actions.reactions.

# Pulsanti interattivi (strumento messaggi)

Invia messaggi con pulsanti cliccabili. Quando un utente fa clic su un pulsante, l'agente riceve la selezione e può rispondere.

Abilita i pulsanti aggiungendo inlineButtons alle capacità del canale:

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

Usa message action=send con un parametro buttons. I pulsanti sono un array 2D (righe di pulsanti):

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

Campi dei pulsanti:

Quando un utente fa clic su un pulsante:

# Integrazione API diretta (script esterni)

Script esterni e Webhook possono pubblicare pulsanti direttamente tramite l'API REST di Mattermost invece di passare dallo strumento message dell'agente. Usa buildButtonAttachments() dal plugin quando possibile; se pubblichi JSON grezzo, segui queste regole:

Struttura del payload:

{
  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
              },
            },
          },
        ],
      },
    ],
  },
}

Generazione del token HMAC

Il Gateway verifica i clic sui pulsanti con HMAC-SHA256. Gli script esterni devono generare token che corrispondano alla logica di verifica del Gateway:

Esempio 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}

# Adattatore di directory

Il plugin Mattermost include un adattatore di directory che risolve i nomi di canali e utenti tramite l'API di Mattermost. Questo abilita destinazioni #channel-name e @username in openclaw message send e nelle consegne Cron/Webhook.

Non è necessaria alcuna configurazione: l'adattatore usa il token del bot dalla configurazione dell'account.

# Multi-account

Mattermost supporta più account sotto 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" },
      },
    },
  },
}

# Risoluzione dei problemi

# Correlati

• Routing dei canali - routing delle sessioni per i messaggi
• Panoramica dei canali - tutti i canali supportati
• Gruppi - comportamento delle chat di gruppo e controllo tramite menzione
• Associazione - autenticazione DM e flusso di associazione
• Sicurezza - modello di accesso e rafforzamento