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

Mattermost ist für OpenClaw interessant, wenn der Team-Chat in der eigenen Infrastruktur bleiben soll. Beim Einrichten können jedoch voneinander unabhängige Fehler auftreten: DMs erreichen den Bot, während ein Channel still bleibt. Slash-Commands sind sichtbar, aber ihr Callback kommt nicht am Gateway an.

Eine feste Reihenfolge grenzt diese Fehler ein. Prüfe zuerst Runtime und Transport, danach DMs und Channels getrennt. Slash-Commands und ausgehendes Routing folgen erst, wenn normale Nachrichten funktionieren.

Grundlagen zur Konfigurationsdatei findest du im Artikel zur Gateway-Konfiguration mit openclaw.json (JSON5).

Was der Mattermost-Kanal unterstützt

Das separat installierbare Mattermost-Plugin unterstützt öffentliche Channels, private Channels, Gruppen-DMs und DMs. Es authentifiziert sich mit einem Bot-Token und empfängt Nachrichten über WebSocket-Ereignisse.

Native Slash-Commands sind optional. OpenClaw kann dafür oc_*-Commands registrieren und deren Callback-POSTs am HTTP-Server des Gateways empfangen.

Antworten auf eingehende Nachrichten werden deterministisch in den Ursprungskontext zurückgeleitet. Bei expliziten ausgehenden Zielen unterscheiden Präfixe wie channel:<id> und user:<id> zwischen Channel und Nutzer.

Voraussetzungen prüfen

Lege in Mattermost einen Bot-Account an und kopiere dessen Bot-Token. Füge den Bot anschließend den Teams und Channels hinzu, deren Nachrichten er lesen soll.

Notiere die Basis-URL der Mattermost-Instanz, zum Beispiel https://chat.example.com. Ein angehängtes /api/v4 entfernt OpenClaw automatisch.

Beginne den Test mit einem eigenen Channel und beschränke die Mitgliedschaft des Bots zunächst auf diesen Kontext. So kannst du Zugriffsregeln und Logs prüfen, ohne einen produktiven Raum zu öffnen.

Kläre außerdem beide Netzwege:

• Das Gateway muss die Mattermost-API erreichen.
• Für native Slash-Commands muss der Mattermost-Server den HTTP-Callback des Gateways erreichen.

Plugin installieren und Gateway prüfen

Installiere das Mattermost-Plugin:

openclaw plugins install @openclaw/mattermost

Läuft das Gateway bereits, starte es danach neu:

openclaw gateway restart

Ein Neustart kann laufende Gateway-Arbeit unterbrechen. Die installierte CLI unterstützt mit openclaw gateway restart --safe auch einen OpenClaw-aware Neustart, der zunächst auf aktive Arbeit wartet.

Prüfe danach Runtime und Gateway:

openclaw status
openclaw gateway status

Die Runtime sollte als laufend erscheinen. Meldet bereits einer dieser Schritte einen Fehler, behebe ihn vor der Mattermost-Konfiguration.

Minimalkonfiguration setzen

Die dokumentierte Minimalkonfiguration besteht aus aktiviertem Channel, Bot-Token, Basis-URL und DM-Policy:

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

Alternativ kannst du den Channel-Account nicht-interaktiv anlegen:

openclaw channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

Setze für <token> den echten Bot-Token ein, ohne die spitzen Klammern. Auf gemeinsam genutzten Systemen kann ein direkt übergebenes Secret in Shell-Historie oder Prozessinformationen sichtbar werden. Verwende dort die geführte Einrichtung mit openclaw channels add oder den für deine Installation vorgesehenen Secret-Loader.

Starte das Gateway nach einer manuellen Konfigurationsänderung neu und prüfe gezielt den Channel:

openclaw gateway restart
openclaw channels status --channel mattermost --probe

Das erwartete Ergebnis ist ein geladener Mattermost-Channel mit erfolgreicher Transport- beziehungsweise Credential-Prüfung. Scheitert die Probe, kontrolliere Plugin-Ladestatus, Basis-URL, Token und den Netzweg zur Mattermost-API.

Private Mattermost-Adressen freigeben

OpenClaw schützt ausgehende Mattermost-API-Aufrufe mit einem SSRF-Filter. Private und interne IP-Adressen sind standardmäßig blockiert. Das betrifft beispielsweise Mattermost-Instanzen im LAN oder Tailnet.

Für einen solchen Host musst du die Ausnahme bewusst konfigurieren:

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

Aktiviere dangerouslyAllowPrivateNetwork nur, wenn die konfigurierte Basis-URL tatsächlich in ein vertrauenswürdiges privates Netz zeigt. Die Option lockert eine Schutzgrenze für ausgehende Mattermost-Anfragen. Sie behebt keine DNS-, TLS- oder Proxyfehler.

Bei mehreren Mattermost-Accounts kann die Ausnahme auch accountbezogen unter channels.mattermost.accounts.<id>.network.dangerouslyAllowPrivateNetwork gesetzt werden.

Hinweise zur Erreichbarkeit über Tailscale findest du unter OpenClaw Remote Nodes sicher einrichten.

Diagnoseleiter ausführen

Wenn Mattermost verbunden aussieht, sich aber falsch verhält, führe die dokumentierten Prüfungen in dieser Reihenfolge aus:

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

Eine gesunde Basis zeigt Runtime: running und Connectivity probe: ok. Abhängig von den Berechtigungen kann die Capability als read-only, write-capable oder admin-capable erscheinen. Wo der Channel es unterstützt, kann die Probe zusätzlich Ergebnisse wie works oder audit ok melden.

Lass openclaw logs --follow während eines kontrollierten Tests geöffnet. Sende genau eine eindeutig benannte Nachricht, zum Beispiel mattermost-test-01. Dadurch lässt sich im Log erkennen, ob das Ereignis das Gateway erreicht und an welcher Schicht die Verarbeitung endet.

DMs per Pairing freigeben

channels.mattermost.dmPolicy hat im aktuellen Runtime-Schema den Standardwert pairing. Eine Nachricht eines unbekannten Absenders wird nicht verarbeitet, bevor du den Absender freigegeben hast.

Zeige offene Mattermost-Anfragen an und genehmige den passenden Code:

openclaw pairing list mattermost
openclaw pairing approve mattermost <CODE>

Pairing-Codes laufen nach einer Stunde ab. Pro Channel-Account können höchstens drei Anfragen gleichzeitig offen sein.

Sende nach der Freigabe eine neue DM. Nicht die bereits blockierte Nachricht, sondern erst diese neue Nachricht sollte verarbeitet werden. Bei mehreren Mattermost-Accounts ergänzt du den betreffenden Account mit --account <id>.

Alternativ findest du offene Anfragen in der Control UI unter Settings → Channels → DM access requests. Prüfe dort Channel, Account und Absender, bevor du auf Approve klickst.

Channel-Zugriff und groupPolicy prüfen

Das aktuelle Runtime-Schema bestätigt für channels.mattermost.groupPolicy die Werte open, disabled und allowlist. Die Voreinstellung ist allowlist.

Bot-Mitgliedschaft und eine erfolgreiche Channel-Probe reichen deshalb nicht als Nachweis, dass eine Channel-Nachricht verarbeitet wird. Bleibt der Test-Channel still, prüfe die aktive Gruppenrichtlinie zusammen mit dem Live-Log.

Für eine eng begrenzte Diagnose kannst du groupPolicy vorübergehend auf open setzen:

{
  channels: {
    mattermost: {
      groupPolicy: "open",
    },
  },
}

Dieser Test ist nur vertretbar, wenn der Bot ausschließlich dem vorbereiteten Testkontext angehört. open gilt sonst auch für weitere erreichbare Mattermost-Kontexte. Starte das Gateway neu, sende mattermost-channel-test-01 und prüfe das Log.

Erscheint die Nachricht nun, lag die Blockade an der Zugriffsrichtlinie. Dieser Schritt ist ausschließlich eine Diagnose: Stelle groupPolicy: "allowlist" sofort danach wieder her. Eine dauerhafte, produktive Freigabe einzelner Channels mit stabilen IDs setzt zusätzliche Allowlist-Felder voraus, deren genaue Bezeichnung von der installierten Mattermost-Plugin-Version abhängt und die durch das hier geprüfte Runtime-Schema nicht bestätigt sind. Schlage diese Felder in der Dokumentation deiner installierten Plugin-Version nach, bevor du den Channel dauerhaft öffnest. Bleibt die Nachricht weiterhin unsichtbar, prüfe Bot-Mitgliedschaft, WebSocket-Transport und Logs statt weitere Zugriffsregeln zu öffnen.

chatmode ohne Blindflug prüfen

Das aktuelle Runtime-Schema führt channels.mattermost.chatmode als gültigen Pfad. Zulässig sind oncall, onmessage und onchar.

Das Schema bestätigt jedoch nur Pfad und Werte, nicht deren Auslöseverhalten. Ändere chatmode deshalb nicht allein aufgrund eines stillen Channels. Prüfe zuerst, ob der konfigurierte Wert überhaupt zu den drei zulässigen Werten gehört, und gleiche seine Bedeutung anschließend mit der Dokumentation der installierten Plugin-Version ab.

Ein schema-konformer Wert ist noch kein Funktionsnachweis. Maßgeblich bleibt, ob die eindeutig benannte Testnachricht im Gateway-Log erscheint und verarbeitet wird.

Native Slash-Commands testen

Native Slash-Commands sind optional. Wenn sie aktiviert sind, registriert OpenClaw oc_*-Commands in den Teams, denen der Bot angehört. Die Aufrufe erreichen das Gateway als HTTP POST.

Eine dokumentierte Konfiguration sieht so aus:

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
      },
    },
  },
}

callbackPath legt nur den Pfad fest, unter dem der Callback am Gateway ankommt. Mattermost sendet den POST an die für den Mattermost-Server extern erreichbare Basis-Adresse deines Gateways plus diesen Pfad. Kann Mattermost das Gateway nicht direkt erreichen, etwa hinter NAT, sorgst du über einen Reverse Proxy oder Tunnel wie Tailscale Serve/Funnel dafür, dass diese kombinierte Adresse tatsächlich beim Gateway ankommt. Ob deine installierte Plugin-Version zusätzlich einen expliziten Basis-URL-Schlüssel für diesen Fall anbietet, prüfst du in der Dokumentation der installierten Version, bevor du ihn in die Konfiguration aufnimmst.

Bei einem Reverse Proxy muss der konfigurierte Pfad unverändert bis zum Gateway weitergeleitet werden. Prüfe DNS, TLS und Firewall aus Sicht des Mattermost-Servers. localhost funktioniert nur, wenn Mattermost und Gateway tatsächlich denselben Netzkontext teilen.

Ein unauthentifizierter GET-Aufruf ist kein verlässlicher Test für den POST-Callback. Starte stattdessen das Live-Log:

openclaw logs --follow

Rufe danach einen registrierten oc_*-Command im Test-Channel auf. Ein erfolgreicher Test zeigt sowohl den eingehenden Callback im Gateway-Log als auch eine Antwort im aufrufenden Mattermost-Kontext.

Fehlt der Callback im Log, liegt der Fehler vor der Agent-Verarbeitung. Prüfe dann Command-Registrierung, Callback-Adresse, Reverse Proxy und Firewall. Erscheint der Callback, aber keine Antwort, untersuche ab diesem Logeintrag die Agent- und Zustellfehler.

Routing eindeutig halten

OpenClaw leitet Antworten auf eingehende Nachrichten deterministisch in den Ursprungskontext zurück. Das Modell wählt diesen Kanal nicht selbst.

Bei expliziten ausgehenden Nachrichten gibst du den Zieltyp an. channel:<id> bezeichnet einen Channel, user:<id> einen Nutzer. Die Präfixe wählen nicht selbst den Provider; der aufrufende Versandpfad muss weiterhin Mattermost verwenden.

Verwende in Automationen keine nackte ID, wenn daraus nicht eindeutig hervorgeht, ob ein Channel oder ein Nutzer gemeint ist.

Typische Fehlerbilder

Symptom	Zuerst prüfen	Erwartetes Ergebnis
DM erzeugt nur einen Code	Offene Pairing-Anfrage	Eine neue DM wird nach Freigabe verarbeitet
Channel bleibt still	Bot-Mitgliedschaft, groupPolicy, Transport	Die benannte Testnachricht erscheint im Gateway-Log
Probe scheitert bei privater URL	SSRF-Block, DNS, TLS und Netzweg	Die Mattermost-Probe erreicht die konfigurierte API
Slash-Command antwortet nicht	Registrierung, Callback-Adresse, Proxy und Firewall	Callback-POST und Antwort sind im Test nachvollziehbar
Nachricht erreicht die falsche Zielart	Zielpräfix	channel:<id> und user:<id> werden eindeutig aufgelöst
Plugin fehlt nach einem Update	openclaw status --all	Ein Ladefehler wird sichtbar und gezielt repariert

Die Online-Anzeige des Bots belegt weder Channel-Zugriff noch eine erfolgreiche Agent-Verarbeitung. Entscheidend sind Probe, reproduzierbare Testnachricht und zugehörige Logzeilen.

Recovery nach Updates

Wenn der Mattermost-Channel nach einem Update fehlt oder nur teilweise geladen wird, nutze den dokumentierten Recovery-Pfad:

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

Achte auf die Meldung plugin load failed: dependency tree corrupted; run openclaw doctor --fix. Sie weist darauf hin, dass die Channel-Konfiguration vorhanden ist, der Plugin-Abhängigkeitsbaum aber nicht korrekt geladen wurde.

Nach der Reparatur sollte openclaw status --all das Plugin wieder als geladen anzeigen. Führe anschließend erneut die Mattermost-Probe aus:

openclaw channels status --channel mattermost --probe

Erst danach wiederholst du eine einzelne DM oder Channel-Nachricht.

Änderungen zurücknehmen

Wenn eine neue Einstellung das Verhalten verschlechtert, entferne nur das zuletzt ergänzte Mattermost-Feld. Starte das Gateway neu und wiederhole denselben Test mit derselben Nachricht.

Setze den Channel vorübergehend auf enabled: false, wenn bis zur Klärung keine Mattermost-Nachrichten verarbeitet werden sollen. Entferne dangerouslyAllowPrivateNetwork, sobald der private Netz-Override nicht mehr benötigt wird, und stelle einen diagnostisch geöffneten groupPolicy wieder auf allowlist.

Widerrufe einen offengelegten Bot-Token in Mattermost und ersetze ihn in OpenClaw. Temporäre Tokens und offene Zugriffsregeln gehören nicht in die dauerhafte Konfiguration.

Reality Check

• Grundlage: offizielle OpenClaw-Dokumentation, Hilfe der installierten CLI und aktuelles Runtime-Schema; kein eigener Mattermost-End-to-End-Test.
• Geeignet für: selbst gehostete Team-Chats mit kontrollierter Bot-Mitgliedschaft und bekannten Netzwegen.
• Nicht abgedeckt: eine dauerhafte, produktive Channel-Allowlist mit stabilen IDs; die dafür nötigen Felder sind plugin- und versionsabhängig und nicht Teil der hier geprüften Schema-Ground-Truth.
• Häufige Fehlergrenzen: Plugin-Ladestatus, Pairing, Gruppenrichtlinie, private Zielnetze und Callback-Erreichbarkeit.
• Sicherheitsrelevant: Bot-Token, offene Zugriffsregeln und dangerouslyAllowPrivateNetwork.
• Recovery: Runtime prüfen, den Fehler mit einer benannten Nachricht reproduzieren und beschädigte Plugin-Abhängigkeiten mit openclaw doctor --fix reparieren.

Kernpunkte

Ein nachvollziehbares Mattermost-Setup beginnt mit Plugin, Bot-Mitgliedschaft und einer erfolgreichen Channel-Probe. Danach testest du eine neue DM nach dem Pairing und eine eindeutig benannte Channel-Nachricht mit geöffnetem Gateway-Log.

channels.mattermost.chatmode und channels.mattermost.groupPolicy sind gültige Runtime-Pfade. Nur für groupPolicy ist die Voreinstellung allowlist belegt; die Bedeutung einzelner chatmode-Werte sollte mit der installierten Plugin-Version abgeglichen werden. Eine dauerhafte Channel-Allowlist bleibt außerhalb dieses Diagnoseablaufs Sache der installierten Plugin-Dokumentation.

Native Slash-Commands benötigen einen Callback, den der Mattermost-Server tatsächlich erreicht. Explizite ausgehende Ziele werden mit channel:<id> oder user:<id> eindeutig adressiert.