Mattermost

Status: herunterladbares Plugin (Bot-Token + WebSocket-Ereignisse). Kanäle, Gruppen und DMs werden unterstützt. Mattermost ist eine selbst hostbare Team-Messaging-Plattform; Produktdetails und Downloads finden Sie auf der offiziellen Website unter mattermost.com.

# Installation

Installieren Sie Mattermost, bevor Sie den Kanal konfigurieren:

openclaw plugins install @openclaw/mattermost

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

Details: Plugins

# Schnelleinrichtung

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

# Native Slash-Befehle

Native Slash-Befehle sind opt-in. Wenn sie aktiviert sind, registriert OpenClaw oc_*-Slash-Befehle über die Mattermost-API und empfängt Callback-POSTs auf dem Gateway-HTTP-Server.

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

# Umgebungsvariablen (Standard-Account)

Setzen Sie diese auf dem Gateway-Host, wenn Sie Umgebungsvariablen bevorzugen:

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

# Chat-Modi

Mattermost antwortet automatisch auf DMs. Das Verhalten in Kanälen wird durch chatmode gesteuert:

Konfigurationsbeispiel:

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

Hinweise:

• onchar antwortet weiterhin auf explizite @Erwähnungen.
• channels.mattermost.requireMention wird für Legacy-Konfigurationen berücksichtigt, aber chatmode wird bevorzugt.

# Threads und Sitzungen

Verwenden Sie channels.mattermost.replyToMode, um zu steuern, ob Kanal- und Gruppenantworten im Hauptkanal bleiben oder einen Thread unter dem auslösenden Beitrag starten.

• off (Standard): nur in einem Thread antworten, wenn der eingehende Beitrag bereits in einem Thread ist.
• first: für Top-Level-Kanal-/Gruppenbeiträge einen Thread unter diesem Beitrag starten und die Unterhaltung an eine Thread-spezifische Sitzung routen.
• all: derzeit dasselbe Verhalten wie first für Mattermost.
• Direktnachrichten ignorieren diese Einstellung und bleiben ohne Thread.

Konfigurationsbeispiel:

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

Hinweise:

• Thread-spezifische Sitzungen verwenden die ID des auslösenden Beitrags als Thread-Root.
• first und all sind derzeit äquivalent, da Folge-Chunks und Medien in demselben Thread fortgesetzt werden, sobald Mattermost einen Thread-Root hat.

# Zugriffskontrolle (DMs)

• Standard: channels.mattermost.dmPolicy = "pairing" (unbekannte Absender erhalten einen Pairing-Code).
• Genehmigen über:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Öffentliche DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

# Kanäle (Gruppen)

• Standard: channels.mattermost.groupPolicy = "allowlist" (erwähnungsgesteuert).
• Absender mit channels.mattermost.groupAllowFrom zulassen (Benutzer-IDs empfohlen).
• Erwähnungsüberschreibungen pro Kanal befinden sich unter channels.mattermost.groups.<channelId>.requireMention oder channels.mattermost.groups["*"].requireMention für einen Standardwert.
• @username-Abgleich ist veränderlich und nur aktiviert, wenn channels.mattermost.dangerouslyAllowNameMatching: true.
• Offene Kanäle: channels.mattermost.groupPolicy="open" (erwähnungsgesteuert).
• Laufzeithinweis: Wenn channels.mattermost vollständig fehlt, fällt die Laufzeit für Gruppenprüfungen auf groupPolicy="allowlist" zurück (auch wenn channels.defaults.groupPolicy gesetzt ist).

Beispiel:

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

# Ziele für ausgehende Zustellung

Verwenden Sie diese Zielformate mit openclaw message send oder Cron/Webhooks:

• channel:<id> für einen Kanal
• user:<id> für eine DM
• @username für eine DM (über die Mattermost-API aufgelöst)

# Wiederholung für DM-Kanäle

Wenn OpenClaw an ein Mattermost-DM-Ziel sendet und zuerst den direkten Kanal auflösen muss, wiederholt es standardmäßig transiente Fehler bei der Erstellung direkter Kanäle.

Verwenden Sie channels.mattermost.dmChannelRetry, um dieses Verhalten global für das Mattermost-Plugin abzustimmen, oder channels.mattermost.accounts.<id>.dmChannelRetry für einen Account.

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

Hinweise:

• Dies gilt nur für die Erstellung von DM-Kanälen (/api/v4/channels/direct), nicht für jeden Mattermost-API-Aufruf.
• Wiederholungen gelten für transiente Fehler wie Ratenbegrenzungen, 5xx-Antworten sowie Netzwerk- oder Timeout-Fehler.
• 4xx-Clientfehler außer 429 werden als dauerhaft behandelt und nicht wiederholt.

# Preview-Streaming

Mattermost streamt Denken, Tool-Aktivität und partiellen Antworttext in einen einzelnen Entwurfsvorschau-Beitrag, der direkt finalisiert wird, wenn die endgültige Antwort sicher gesendet werden kann. Die Vorschau wird auf derselben Beitrags-ID aktualisiert, statt den Kanal mit Nachrichten pro Chunk zu überfluten. Medien-/Fehler-Endzustände brechen ausstehende Vorschau-Bearbeitungen ab und verwenden die normale Zustellung, statt einen wegwerfbaren Vorschau-Beitrag zu leeren.

Aktivieren über channels.mattermost.streaming:

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

# Reaktionen (Nachrichten-Tool)

• Verwenden Sie message action=react mit channel=mattermost.
• messageId ist die Mattermost-Beitrags-ID.
• emoji akzeptiert Namen wie thumbsup oder :+1: (Doppelpunkte sind optional).
• Setzen Sie remove=true (boolesch), um eine Reaktion zu entfernen.
• Ereignisse zum Hinzufügen/Entfernen von Reaktionen werden als Systemereignisse an die geroutete Agent-Sitzung weitergeleitet.

Beispiele:

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

Konfiguration:

• channels.mattermost.actions.reactions: Reaktionsaktionen aktivieren/deaktivieren (standardmäßig true).
• Überschreibung pro Account: channels.mattermost.accounts.<id>.actions.reactions.

# Interaktive Buttons (Nachrichten-Tool)

Senden Sie Nachrichten mit anklickbaren Buttons. Wenn ein Benutzer auf einen Button klickt, erhält der Agent die Auswahl und kann antworten.

Aktivieren Sie Buttons, indem Sie inlineButtons zu den Kanal-Capabilities hinzufügen:

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

Verwenden Sie message action=send mit einem buttons-Parameter. Buttons sind ein 2D-Array (Button-Zeilen):

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

Button-Felder:

Wenn ein Benutzer auf einen Button klickt:

# Direkte API-Integration (externe Skripte)

Externe Skripte und Webhooks können Buttons direkt über die Mattermost REST API posten, statt über das message-Tool des Agents zu gehen. Verwenden Sie nach Möglichkeit buildButtonAttachments() aus dem Plugin; wenn Sie rohes JSON posten, befolgen Sie diese Regeln:

Payload-Struktur:

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

HMAC-Token-Generierung

Das Gateway verifiziert Button-Klicks mit HMAC-SHA256. Externe Skripte müssen Tokens generieren, die zur Verifizierungslogik des Gateways passen:

Python-Beispiel:

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}

# Verzeichnisadapter

Das Mattermost-Plugin enthält einen Verzeichnisadapter, der Kanal- und Benutzernamen über die Mattermost API auflöst. Dies aktiviert #channel-name- und @username-Ziele in openclaw message send sowie bei Cron-/Webhook-Zustellungen.

Es ist keine Konfiguration erforderlich - der Adapter verwendet das Bot-Token aus der Account-Konfiguration.

# Multi-Account

Mattermost unterstützt mehrere Accounts unter 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" },
      },
    },
  },
}

# Fehlerbehebung

# Verwandte Themen

• Kanal-Routing - Sitzungs-Routing für Nachrichten
• Kanäle im Überblick - alle unterstützten Kanäle
• Gruppen - Verhalten von Gruppenchats und Erwähnungs-Gating
• Pairing - DM-Authentifizierung und Pairing-Ablauf
• Sicherheit - Zugriffsmodell und Härtung