Mattermost

Statut : Plugin téléchargeable (jeton de bot + événements WebSocket). Les canaux, les groupes et les MP sont pris en charge. Mattermost est une plateforme de messagerie d’équipe auto-hébergeable ; consultez le site officiel mattermost.com pour les détails du produit et les téléchargements.

# Installation

Installez Mattermost avant de configurer le canal :

openclaw plugins install @openclaw/mattermost

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

Détails : Plugins

# Configuration rapide

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

# Commandes slash natives

Les commandes slash natives sont optionnelles. Lorsqu’elles sont activées, OpenClaw enregistre les commandes slash oc_* via l’API Mattermost et reçoit les POST de rappel sur le serveur HTTP du 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 d’environnement (compte par défaut)

Définissez-les sur l’hôte du Gateway si vous préférez les variables d’environnement :

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

# Modes de discussion

Mattermost répond automatiquement aux MP. Le comportement dans les canaux est contrôlé par chatmode :

Exemple de configuration :

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

Notes :

• onchar répond toujours aux @mentions explicites.
• channels.mattermost.requireMention est respecté pour les configurations héritées, mais chatmode est préférable.

# Fils de discussion et sessions

Utilisez channels.mattermost.replyToMode pour contrôler si les réponses de canal et de groupe restent dans le canal principal ou démarrent un fil sous la publication déclencheuse.

• off (par défaut) : répondre dans un fil uniquement lorsque la publication entrante s’y trouve déjà.
• first : pour les publications de canal/groupe de premier niveau, démarrer un fil sous cette publication et acheminer la conversation vers une session limitée au fil.
• all : même comportement que first pour Mattermost aujourd’hui.
• Les messages directs ignorent ce paramètre et restent sans fil.

Exemple de configuration :

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

Notes :

• Les sessions limitées au fil utilisent l’identifiant de la publication déclencheuse comme racine du fil.
• first et all sont actuellement équivalents, car dès que Mattermost dispose d’une racine de fil, les fragments de suivi et les médias continuent dans ce même fil.

# Contrôle d’accès (MP)

• Par défaut : channels.mattermost.dmPolicy = "pairing" (les expéditeurs inconnus reçoivent un code d’appairage).
• Approuver via :
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• MP publics : channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

# Canaux (groupes)

• Par défaut : channels.mattermost.groupPolicy = "allowlist" (soumis à mention).
• Autorisez les expéditeurs avec channels.mattermost.groupAllowFrom (identifiants utilisateur recommandés).
• Les remplacements de mention par canal se trouvent sous channels.mattermost.groups.<channelId>.requireMention ou channels.mattermost.groups["*"].requireMention pour une valeur par défaut.
• La correspondance @username est modifiable et activée uniquement lorsque channels.mattermost.dangerouslyAllowNameMatching: true.
• Canaux ouverts : channels.mattermost.groupPolicy="open" (soumis à mention).
• Note d’exécution : si channels.mattermost est complètement absent, l’exécution revient à groupPolicy="allowlist" pour les vérifications de groupe (même si channels.defaults.groupPolicy est défini).

Exemple :

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

# Cibles pour la livraison sortante

Utilisez ces formats de cible avec openclaw message send ou les cron/Webhooks :

• channel:<id> pour un canal
• user:<id> pour un MP
• @username pour un MP (résolu via l’API Mattermost)

# Nouvelle tentative de canal MP

Quand OpenClaw envoie vers une cible MP Mattermost et doit d’abord résoudre le canal direct, il réessaie par défaut les échecs transitoires de création du canal direct.

Utilisez channels.mattermost.dmChannelRetry pour ajuster ce comportement globalement pour le Plugin Mattermost, ou channels.mattermost.accounts.<id>.dmChannelRetry pour un compte.

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

Notes :

• Cela s’applique uniquement à la création de canal MP (/api/v4/channels/direct), pas à chaque appel de l’API Mattermost.
• Les nouvelles tentatives s’appliquent aux échecs transitoires tels que les limites de débit, les réponses 5xx et les erreurs réseau ou de délai d’expiration.
• Les erreurs client 4xx autres que 429 sont traitées comme permanentes et ne sont pas réessayées.

# Streaming d’aperçu

Mattermost diffuse le raisonnement, l’activité des outils et le texte de réponse partiel dans une seule publication d’aperçu brouillon qui est finalisée sur place lorsque la réponse finale peut être envoyée en toute sécurité. L’aperçu est mis à jour sur le même identifiant de publication au lieu d’inonder le canal avec des messages par fragment. Les finales de média/d’erreur annulent les modifications d’aperçu en attente et utilisent la livraison normale au lieu de vider une publication d’aperçu jetable.

Activez via channels.mattermost.streaming :

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

# Réactions (outil de message)

• Utilisez message action=react avec channel=mattermost.
• messageId est l’identifiant de publication Mattermost.
• emoji accepte des noms comme thumbsup ou :+1: (les deux-points sont facultatifs).
• Définissez remove=true (booléen) pour supprimer une réaction.
• Les événements d’ajout/suppression de réaction sont transmis comme événements système à la session d’agent acheminée.

Exemples :

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

Configuration :

• channels.mattermost.actions.reactions : activer/désactiver les actions de réaction (true par défaut).
• Remplacement par compte : channels.mattermost.accounts.<id>.actions.reactions.

# Boutons interactifs (outil de message)

Envoyez des messages avec des boutons cliquables. Lorsqu’un utilisateur clique sur un bouton, l’agent reçoit la sélection et peut répondre.

Activez les boutons en ajoutant inlineButtons aux capacités du canal :

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

Utilisez message action=send avec un paramètre buttons. Les boutons sont un tableau 2D (lignes de boutons) :

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

Champs de bouton :

Lorsqu’un utilisateur clique sur un bouton :

# Intégration directe de l’API (scripts externes)

Les scripts externes et les webhooks peuvent publier des boutons directement via l’API REST Mattermost au lieu de passer par l’outil message de l’agent. Utilisez buildButtonAttachments() depuis le plugin lorsque c’est possible ; si vous publiez du JSON brut, suivez ces règles :

Structure de la charge utile :

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

Génération du jeton HMAC

Le gateway vérifie les clics sur les boutons avec HMAC-SHA256. Les scripts externes doivent générer des jetons qui correspondent à la logique de vérification du gateway :

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

# Adaptateur d’annuaire

Le plugin Mattermost inclut un adaptateur d’annuaire qui résout les noms de canaux et d’utilisateurs via l’API Mattermost. Cela active les cibles #channel-name et @username dans openclaw message send et les livraisons cron/webhook.

Aucune configuration n’est nécessaire - l’adaptateur utilise le jeton du bot depuis la configuration du compte.

# Multi-compte

Mattermost prend en charge plusieurs comptes sous 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" },
      },
    },
  },
}

# Dépannage

# Connexe

• Routage des canaux - routage de session pour les messages
• Vue d’ensemble des canaux - tous les canaux pris en charge
• Groupes - comportement des discussions de groupe et contrôle par mention
• Appairage - authentification DM et flux d’appairage
• Sécurité - modèle d’accès et durcissement