OpenClaw mit Mattermost verbinden: Bot, Channels und Self-Hosting ohne Blindflug

Mattermost ist für OpenClaw vor allem dann spannend, wenn du Team-Chat nicht an Slack oder Discord auslagern willst. Genau dort kippt der Kanal aber schnell von “self-hosted Kontrolle” in “Bot wirkt halb lebendig”: DMs antworten, Channels bleiben still; Slash-Commands sind registriert, aber Callback-POSTs kommen nie an; Threads laufen, bis ein gelöschter Preview-Post die sichtbare Antwort verschluckt.

Die gute Nachricht: Die aktuelle OpenClaw-Doku ist an dieser Stelle deutlich konkreter geworden. Der saubere Weg ist kein blindes Plugin-Install, sondern eine feste Diagnoseleiter. Erst prüfst du Runtime und Transport. Danach trennst du DMs, Channel-Verhalten und Gruppenregeln. Zum Schluss klärst du Callback-Erreichbarkeit, Threading und Routing. Genau diese Reihenfolge spart Zeit.

Wenn du andere Team-Kanäle danebenhalten willst, helfen die Nachbarartikel zu Slack mit OpenClaw verbinden, OpenClaw mit Discord verbinden und OpenClaw mit Matrix verbinden. Für Mattermost ist der entscheidende Unterschied aber das Self-Hosting: Callback-Erreichbarkeit, interne Allowlists und saubere Zielsyntax sind hier wichtiger als hübsche Admin-Menüs.

Was der Mattermost-Kanal wirklich kann

Laut offizieller OpenClaw-Dokumentation läuft Mattermost als herunterladbares Plugin mit Bot-Token und WebSocket-Events. Unterstützt werden Channels, Gruppen und DMs. Dazu kommen native Slash-Commands, Thread-Antworten, Preview-Streaming sowie ausgehende Zustellung an explizite Ziele wie channel:<id> oder user:<id>.

Wichtiger als die Feature-Liste ist die Betriebslogik dahinter:

• DMs gehen standardmäßig über channels.mattermost.dmPolicy: "pairing" und brauchen deshalb zuerst eine Freigabe.
• Channel-Verhalten wird primär über channels.mattermost.chatmode gesteuert.
• Gruppen- und Channel-Zugriff bleibt standardmäßig defensiv, solange du nichts explizit öffnest.
• Replies werden deterministisch in denselben Mattermost-Kontext zurückgeroutet, aus dem die Nachricht kam.
• Native Slash-Commands funktionieren nur, wenn Mattermost den Callback-Endpunkt des OpenClaw-Gateways wirklich erreicht.

Damit ist Mattermost kein “Slack mit anderer Oberfläche”, sondern ein Kanal, bei dem Self-Hosting-Fragen direkt in die Zustellung hineinragen.

Was du vor dem Setup geklärt haben solltest

Bevor du irgendetwas in OpenClaw einträgst, kläre diese Punkte:

• Das Mattermost-Plugin ist in deiner OpenClaw-Version bereits gebündelt oder wird bewusst nachinstalliert.
• Du kannst in Mattermost einen Bot-Account anlegen und dessen Token kopieren.
• Du kennst die Basis-URL der Mattermost-Instanz, zum Beispiel https://chat.example.com.
• Das OpenClaw-Gateway läuft oder kann auf dem Zielhost gestartet werden.
• Du weißt, ob Mattermost den Gateway-Endpunkt direkt erreicht oder ob ein Reverse Proxy bzw. eine öffentliche URL nötig ist.
• Du hast mindestens einen privaten Test-Channel, einen DM-Testnutzer und den Bot bereits dem Test-Channel hinzugefügt.

Wenn einer dieser Punkte fehlt, beginnt die Fehlersuche später gleichzeitig in Runtime, Rechtevergabe und Callback-Strecke.

Installieren und minimal sauber starten

Der dokumentierte Installationsweg lautet:

openclaw plugins install @openclaw/mattermost

Danach nennt die Doku als Minimal-Konfiguration einen aktivierten Kanal mit Bot-Token, Base-URL und DM-Policy:

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

Alternativ kannst du für den Default-Account die Umgebungsvariablen MATTERMOST_BOT_TOKEN und MATTERMOST_URL setzen. Wichtig ist dabei eine kleine, aber entscheidende Grenze aus der Doku: MATTERMOST_URL kann nicht aus einer Workspace-.env kommen. Wenn du das übersiehst, wirkt das Setup korrekt, obwohl die Runtime auf dem Gateway-Host die URL gar nicht sauber auflöst.

Diagnose zuerst: Läuft die Runtime überhaupt gesund?

Wenn Mattermost “verbunden aussieht”, aber das Verhalten falsch ist, empfiehlt OpenClaw zuerst diese feste Kommandoleiter:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Die Doku nennt dafür eine klare Baseline:

• Runtime: running
• Connectivity probe: ok
• eine sinnvolle Capability wie read-only, write-capable oder admin-capable
• ein Channel-Probe-Ergebnis, bei dem der Mattermost-Transport wirklich verbunden ist

Wenn schon diese Basis rot ist, lohnt sich Debugging an Mentions, Threads oder Slash-Commands nicht. Dann sitzt der Fehler tiefer in Plugin-Ladepfad, Runtime oder Erreichbarkeit.

Der häufige Denkfehler: Channel-Verhalten hängt heute an chatmode

Viele ältere Integrations-Guides erklären Mattermost fast nur über Mentions. Die aktuelle OpenClaw-Doku ist präziser: Für Channels ist channels.mattermost.chatmode der wichtigste Schalter.

Es gibt drei Modi:

• oncall ist der Default und antwortet nur bei @mention im Channel.
• onmessage antwortet auf jede Channel-Nachricht.
• onchar antwortet, wenn eine Nachricht mit einem Trigger-Präfix beginnt.

Ein Minimalbeispiel für onchar sieht so aus:

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

Wichtig dabei:

• onchar reagiert weiterhin auf explizite @mentions.
• channels.mattermost.requireMention wird laut Doku zwar für Legacy-Konfigurationen noch beachtet, bevorzugt ist aber chatmode.
• Wenn ein Bot im Channel online ist, aber nichts sagt, prüfst du heute zuerst chatmode, nicht irgendeine diffuse Mention-Magie.

Typische Mattermost-Fehlerbilder

Die häufigsten Ausfälle lassen sich sauber nach Symptom sortieren:

Symptom	Wahrscheinlich zuerst prüfen	Warum
DM kommt an, aber keine echte Unterhaltung startet	dmPolicy, Pairing-Freigabe	DMs sind standardmäßig nicht offen
Bot ist online, der Channel bleibt aber still	Bot-Mitgliedschaft im Channel, chatmode	Online heißt nicht triggerbar
Channel reagiert nur auf direkte Anstupser	chatmode: "oncall" oder onchar	Das ist oft der Default, kein Defekt
Slash-Commands tauchen auf, antworten aber nicht	commands.native, callbackUrl, Reachability	Mattermost muss den Gateway-Callback erreichen
Antworten landen als DM statt im Channel	Zielsyntax	Nackte IDs sind in Mattermost absichtlich mehrdeutig
Antworten landen im falschen Thread oder gar nicht im erwarteten Verlauf	replyToMode, Thread-Kontext	Threading hängt an dokumentierten Regeln
Preview-Post entsteht, finaler Inhalt fehlt	Streaming-Modus, gelöschter Post, Finalisierung	Preview-Streaming finalisiert in place und braucht funktionierende Rückwege

Gerade bei selbst gehosteten Setups wirkt das schnell wie ein einziges “Bot kaputt”. In Wirklichkeit brechen unterschiedliche Schichten.

DMs: Pairing ist der harte Filter

Für direkte Nachrichten beschreibt die Mattermost-Doku dieselbe Schutzidee wie bei anderen OpenClaw-Kanälen: channels.mattermost.dmPolicy steht standardmäßig auf "pairing". Unbekannte Absender bekommen also erst einen Pairing-Code.

Praktisch heißt das:

• Ein erreichbarer Bot ohne Freigabe ist noch kein benutzbarer Bot.
• Wer schnell testen will, muss Pairing bewusst abschließen.
• channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"] öffnet DMs vollständig, ist aber für Team-Umgebungen nicht die vernünftigste Ausgangslage.

Die Doku nennt dafür auch die konkreten Freigabe-Kommandos:

openclaw pairing list mattermost
openclaw pairing approve mattermost <CODE>

Wenn dein Mattermost-Bot im DM sichtbar reagiert, aber keine nutzbare Unterhaltung aufmacht, prüfst du vor dem Modell den Pairing-Zustand.

Gruppen und Channels: Zugriff und Antwortmodus sind zwei verschiedene Dinge

Die kanalübergreifende Groups-Doku ist hier wichtiger als viele einzelne Setup-Tutorials. OpenClaw behandelt Gruppenräume über Messenger hinweg konsistent:

• Gruppen sind standardmäßig eingeschränkt (groupPolicy: "allowlist").
• Replies brauchen standardmäßig eine Mention, sofern du das Verhalten nicht pro Raum änderst.
• Sichtbare Gruppenantworten laufen zunächst über den normalen sichtbaren Reply-Pfad.

Für Mattermost heißt das konkret:

• channels.mattermost.groupPolicy="allowlist" bleibt die defensive Voreinstellung.
• channels.mattermost.groupAllowFrom steuert erlaubte Sender.
• Per Raum liegen Mention-Overrides unter channels.mattermost.groups.<channelId>.requireMention oder channels.mattermost.groups["*"].requireMention.
• channels.mattermost.dangerouslyAllowNameMatching: true aktiviert veränderliche @username-Zuordnung und ist deshalb nur mit Vorsicht sinnvoll.

Ein wichtiger Unterschied zur verkürzten Lesart vieler Tutorials: Zugriff und Antwortmodus sind nicht dasselbe. Selbst wenn ein Channel erlaubt ist, antwortet der Bot dort ohne @mention nicht automatisch, solange chatmode das nicht vorsieht.

Slash-Commands brechen meist an der Callback-Strecke

Mattermost ist besonders dann interessant, wenn du Channel-Arbeit über native Befehle anstoßen willst. Laut Doku sind native Slash-Commands opt-in. Erst wenn commands.native: true gesetzt ist, registriert OpenClaw oc_*-Commands über die Mattermost-API und erwartet Callback-POSTs auf dem Gateway.

Die dokumentierte Konfiguration sieht so aus:

{
  "channels": {
    "mattermost": {
      "commands": {
        "native": true,
        "nativeSkills": true,
        "callbackPath": "/api/channels/mattermost/command",
        "callbackUrl": "https://gateway.example.com/api/channels/mattermost/command"
      }
    }
  }
}

Der häufigste Denkfehler dabei: callbackUrl darf nicht einfach localhost sein, wenn Mattermost und OpenClaw nicht im selben Netzraum laufen. Ebenso darf die Mattermost-Basis-URL nicht blind als Callback-Ziel herhalten, solange sie den OpenClaw-Pfad nicht wirklich dorthin weiterleitet.

Die Doku empfiehlt dafür einen simplen Reachability-Test:

curl https://<gateway-host>/api/channels/mattermost/command

Ein 405 Method Not Allowed ist hier gut, weil er zeigt, dass du am OpenClaw-Endpunkt landest. Ein 404 heißt eher: falscher Host, falscher Proxy oder falscher Pfad.

Für interne oder Tailnet-Ziele kommt noch eine Mattermost-Eigenheit dazu: ServiceSettings.AllowedUntrustedInternalConnections muss den Callback-Host oder die Domain enthalten. Und zwar als Hostname, nicht als volle URL.

Wenn native Slash-Commands plötzlich mit ungültigem Token scheitern, nennt die Doku typische Ursachen:

• Registrierung der Commands beim Start ist fehlgeschlagen oder nur teilweise passiert.
• Der Callback trifft den falschen Gateway oder den falschen Account.
• Mattermost zeigt noch alte Commands auf ein früheres Ziel.
• Der Gateway wurde neu gestartet, ohne dass die Slash-Commands sauber reaktiviert wurden.

Threads, Replies und Routing sauber trennen

OpenClaw legt laut Routing-Doku fest zurück, wohin eine Antwort geht. Das Modell wählt den Zielkanal nicht selbst. Für Mattermost sind dafür drei Stellen wichtig:

• replyToMode entscheidet, ob Antworten für Top-Level-Posts direkt im Channel bleiben oder einen Thread unter dem Ausgangspost beginnen.
• channel:<id> und user:<id> sind die sauberen expliziten Zielpräfixe für Outbound-Nachrichten.
• Bare IDs sind in Mattermost absichtlich mehrdeutig und werden deshalb user-first aufgelöst.

Genau daraus entsteht ein typischer Betriebsfehler: Jemand nimmt eine nackte ID aus der Oberfläche, nutzt sie für einen Cron oder einen Outbound-Send und wundert sich, warum statt eines Channels eine DM getroffen wird. Die Doku ist an der Stelle deutlich: Wenn du deterministisches Verhalten willst, nimm durchgehend explizite Präfixe wie user:<id> oder channel:<id>.

Für Threading gilt:

• replyToMode: "off" bleibt bei Top-Level-Posts im Channel, außer der eingehende Post war bereits im Thread.
• replyToMode: "first" startet für neue Top-Level-Posts einen Thread und bindet die Session an diesen Thread-Kontext.
• replyToMode: "all" entspricht für Mattermost aktuell praktisch first.
• DMs ignorieren replyToMode und bleiben nicht-threaded.

Wenn Antworten also “am falschen Ort” auftauchen, prüfst du zuerst replyToMode und Zielsyntax, nicht das Modell.

Preview-Streaming ist praktisch, aber kein Selbstläufer

Die Mattermost-Doku beschreibt Preview-Streaming als einen einzelnen Draft-Post, der fortlaufend editiert und am Ende in place finalisiert wird. Das ist für Team-Channels viel angenehmer als pro Chunk neue Nachrichten.

Der Haken steckt in den Kanten:

• Wird der Preview-Post gelöscht, fällt OpenClaw auf einen frischen Final-Post zurück.
• Medien- oder Fehler-Finals brechen die Preview-Logik ab und nutzen normale Zustellung.
• partial ist der robusteste Standardmodus.
• block und progress ändern nur, wie der Preview-Verlauf dargestellt wird; sie lösen keine Reachability-Probleme.

Wenn dein Team keine halbfertigen Antworten sehen soll, ist Preview-Streaming sinnvoll. Wenn aber Finalisierung oder Editing im konkreten Raum wackeln, ist streaming: "off" oder ein konservativerer Test-Channel oft der bessere Recovery-Pfad.

Recovery nach Updates oder merkwürdigen Plugin-Zuständen

Die allgemeine Channel-Troubleshooting-Doku nennt für verschwundene oder halb geladene Plugin-Kanäle nach Updates einen klaren Pfad:

openclaw status --all
openclaw doctor --fix
openclaw gateway restart
openclaw status --all

Relevant ist dabei besonders die Fehlersignatur plugin load failed: dependency tree corrupted; run openclaw doctor --fix. Dann ist der Mattermost-Kanal nicht “falsch konfiguriert”, sondern der Plugin-Ladepfad selbst ist kaputt. Genau dieser Unterschied entscheidet darüber, ob du an Tokens und Rules drehst oder besser zuerst die Runtime reparierst.

Reality Check

• Getestet mit: nicht selbst getestet; Grundlage sind die offiziellen OpenClaw-Dokumentationsseiten zu Mattermost, Groups, Channel Routing und Channel Troubleshooting.
• Funktioniert gut für: selbst gehostete Team-Chats, in denen du Bot-Zugriff, Gateway-Erreichbarkeit und Channel-Regeln bewusst kontrollierst.
• Bricht wahrscheinlich bei: falsch gesetztem callbackUrl, nicht erreichbarem Gateway, fehlender Bot-Mitgliedschaft im Ziel-Channel, Default-chatmode mit falscher Erwartungshaltung, nackten statt präfixierten Ziel-IDs und nicht abgeschlossenem Pairing.
• Nicht getestet: konkrete Mattermost-Admin-Oberflächen, Reverse-Proxy-Setups einzelner Distributionen, Multi-Account-Mattermost in einer Live-Organisation und das Verhalten exotischer Plugins oder stark angepasster Self-Hosted-Cluster.
• Sicherheitsrisiko: mittel, weil ein zu offenes dmPolicy oder groupPolicy="open" den Agenten schnell in Räume bringt, in denen er zwar lesen, aber nicht sauber begrenzt arbeiten sollte.
• Betriebsaufwand: mittel bis hoch, weil Self-Hosting, Callback-Erreichbarkeit und Channel-Regeln enger zusammenspielen als bei rein gehosteten Messenger-Integrationen.
• Recovery: ja, wenn du Runtime, Pairing, chatmode, Gruppenregeln, Callback-Strecke und Zielsyntax getrennt prüfst.

Fazit: Mattermost lohnt sich, wenn du die Kontrollpunkte ernst nimmst

OpenClaw passt gut zu Mattermost, gerade weil beide eher in kontrollierten Team-Umgebungen zu Hause sind. Aber genau deshalb verzeiht der Kanal kein unsauberes Setup. DMs brauchen oft zuerst Pairing, Channels einen bewusst gesetzten chatmode, Gruppenräume klare Allowlist-Regeln, Slash-Commands einen wirklich erreichbaren Callback-Pfad und Outbound-Ziele eine saubere Prefix-Syntax.

Wenn du diese Kontrollpunkte in der richtigen Reihenfolge abarbeitest, wird Mattermost nicht zum fragilen Spezialfall, sondern zu einem der klarer diagnostizierbaren OpenClaw-Kanäle.