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 Diagnoseleiter grenzt diese Fehler ein. Prüfe zuerst Runtime und Transport. Danach testest du DMs und Channels getrennt. Erst anschließend kümmerst du dich um Slash-Commands und ausgehendes Routing.

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

Was der Mattermost-Kanal unterstützt

Das herunterladbare Mattermost-Plugin unterstützt öffentliche Channels, private Channels, Gruppen-DMs und DMs. Es nutzt einen Bot-Token und empfängt Nachrichten über WebSocket-Ereignisse.

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

Antworten auf eingehende Nachrichten gehen deterministisch in den Ursprungskanal zurück. Für explizite ausgehende Ziele stehen unter anderem channel:<id> und user:<id> zur Verfügung.

Voraussetzungen prüfen

Lege zunächst einen Mattermost-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 außerdem die Basis-URL deiner Mattermost-Instanz, zum Beispiel https://chat.example.com. Ein angehängtes /api/v4 entfernt OpenClaw automatisch.

Bereite für den Testlauf einen eigenen Channel vor. So kannst du Bot-Mitgliedschaft, Nachrichtenfluss 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 umgekehrt der Mattermost-Server den Callback des Gateways erreichen können.

Plugin installieren und Gateway neu starten

Installiere das Mattermost-Plugin:

openclaw plugins install @openclaw/mattermost

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

openclaw gateway restart

Prüfe anschließend den Zustand von Runtime und Gateway:

openclaw status
openclaw gateway status

Beide Prüfungen sollten einen laufenden Zustand melden. Ist das nicht der Fall, behebe zuerst den Gateway- oder Runtime-Fehler.

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

Starte das Gateway nach einer manuellen Konfigurationsänderung neu. Prüfe danach den Channel:

openclaw gateway restart
openclaw channels status --probe

Das gewünschte Ergebnis ist ein geladener und verbundener Mattermost-Transport. Scheitert die Probe, kontrolliere zuerst Plugin-Ladestatus, Basis-URL, Token und Netzweg.

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 für ein privates Netz, dem du vertraust. Die Option lockert eine Schutzgrenze für ausgehende Mattermost-Anfragen. Sie repariert keine DNS-, TLS- oder Proxyfehler.

Hinweise zur Erreichbarkeit über Tailscale findest du auch 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 --probe

Eine gesunde Basis zeigt Runtime: running und Connectivity probe: ok. Die Capability kann abhängig von den Berechtigungen als read-only, write-capable oder admin-capable erscheinen.

Die Channel-Probe sollte einen verbundenen Transport melden. Wo die Prüfung unterstützt wird, können zusätzlich Ergebnisse wie works oder audit ok erscheinen.

Lass openclaw logs --follow während eines kontrollierten Tests geöffnet. Sende anschließend genau eine klar erkennbare Nachricht in Mattermost. So siehst du, ob das Ereignis das Gateway erreicht und an welcher Stelle die Verarbeitung endet.

Channel-Verhalten mit chatmode prüfen

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

Eine schema-konforme Konfiguration sieht beispielsweise so aus:

{
  channels: {
    mattermost: {
      chatmode: "oncall",
    },
  },
}

Wenn der Bot als verbunden erscheint, im Channel aber schweigt, prüfe den gesetzten Wert. Ändere jeweils nur diesen einen Schalter, starte das Gateway neu und sende dieselbe Testnachricht erneut.

Das erwartete Ergebnis ist ein nachvollziehbarer Unterschied im Channel-Verhalten oder ein erklärender Logeintrag. Konkrete Präfixfelder solltest du erst ergänzen, wenn sie für deine installierte Plugin-Version dokumentiert oder im Runtime-Schema bestätigt sind.

Typische Fehlerbilder

Symptom	Zuerst prüfen	Erwartetes Ergebnis
DM erzeugt nur einen Code	dmPolicy, offene Pairing-Anfrage	Nach Freigabe wird eine neue DM verarbeitet
Channel bleibt still	Bot-Mitgliedschaft, Transport, chatmode	Testnachricht erscheint im Gateway-Log
Slash-Command antwortet nicht	Registrierung, callbackUrl, Proxy und Firewall	Callback-POST erscheint im Gateway-Log
Nachricht geht an die falsche Zielart	Zielpräfix	channel:<id> erreicht einen Channel, user:<id> einen Nutzer
Plugin fehlt nach einem Update	openclaw status --all	Ladefehler wird sichtbar und kann gezielt repariert werden

Die Logzeilen entscheiden, welche Schicht als Nächstes geprüft werden muss. Die bloße Online-Anzeige des Bots belegt weder Channel-Zugriff noch erfolgreiche Agent-Verarbeitung.

DMs per Pairing freigeben

channels.mattermost.dmPolicy verwendet standardmäßig den Wert pairing. Nachrichten unbekannter Absender werden dabei 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>

Sende nach der Freigabe eine neue DM. Die Nachricht sollte nun verarbeitet werden. Bei mehreren Mattermost-Accounts ergänzt du den betreffenden Account mit --account <id>.

Für einen vollständig offenen DM-Zugang müssen dmPolicy: "open" und eine effektive Allowlist mit "*" zusammenkommen. In einer Team-Installation ist Pairing die defensivere Ausgangslage.

Gruppen und Channels begrenzen

Das Runtime-Schema bestätigt channels.mattermost.groupPolicy mit den Werten open, disabled und allowlist. Die Voreinstellung ist allowlist.

Außerdem existieren die Mattermost-Pfade groupAllowFrom, groups und dangerouslyAllowNameMatching. Damit lassen sich Gruppen- und Channel-Zugriffe weiter eingrenzen.

Beginne mit der Voreinstellung und öffne nur den vorbereiteten Testkontext. Prüfe danach mit einer einzelnen Nachricht und dem Live-Log, ob der gewünschte Absender zugelassen wird.

dangerouslyAllowNameMatching sollte nur bewusst aktiviert werden. Namen sind als Zugriffskriterium weniger eindeutig als stabile IDs und können sich ändern oder mehrfach vorkommen.

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",
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

callbackUrl muss aus Sicht des Mattermost-Servers erreichbar sein. localhost funktioniert nur, wenn Mattermost und Gateway tatsächlich denselben Netzkontext teilen.

Bei einem Reverse Proxy muss der konfigurierte Pfad bis zum Gateway weitergeleitet werden. Prüfe auch DNS, TLS und Firewall aus Sicht des Mattermost-Servers.

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

openclaw logs --follow

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

Fehlt der Callback im Log, liegt der Fehler vor der Agent-Verarbeitung. Prüfe dann Registrierung, Callback-Adresse, Reverse Proxy und Firewall.

In internen Installationen kann zusätzlich ServiceSettings.AllowedUntrustedInternalConnections auf Mattermost-Seite relevant sein. Dort wird der freizugebende Callback-Host als Hostname eingetragen, nicht als vollständige URL.

Routing eindeutig halten

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

Bei expliziten ausgehenden Nachrichten solltest du den Zieltyp angeben. channel:<id> bezeichnet einen Channel, user:<id> einen Nutzer.

Eine nackte ID enthält keinen eindeutigen Zieltyp. Verwende deshalb bei Automationen und manuellen Sends durchgehend das passende Präfix.

Der Artikel verwendet bewusst keine replyToMode-Konfiguration. Die bereitgestellten Quellen und das geprüfte Runtime-Schema belegen weder deren Mattermost-Werte noch deren genaue Wirkung.

Preview-Antworten getrennt diagnostizieren

Mattermost kann laufende Antworten als bearbeiteten Preview-Post darstellen. Konkrete Modusnamen oder einen Standardwert solltest du ohne Beleg für deine installierte Version nicht konfigurieren.

Wenn ein Preview-Post erscheint, aber kein finaler Inhalt ankommt, wiederhole den Test mit geöffnetem Gateway-Log. Prüfe, ob der Post während der Verarbeitung gelöscht wurde und ob die abschließende Zustellung einen Fehler meldet.

Damit bleibt die Diagnose auf beobachtbares Verhalten beschränkt. Unbelegte Werte wie partial, block oder progress werden nicht als Mattermost-Konfiguration empfohlen.

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 auf einen beschädigten Plugin-Abhängigkeitsbaum hin.

Nach der Reparatur sollte openclaw status --all das Plugin wieder als geladen anzeigen. Führe anschließend erneut openclaw channels status --probe und einen einzelnen Mattermost-Test aus.

Änderungen zurücknehmen

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

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.

Bewahre keine temporären Test-Tokens oder vollständig geöffneten DM-Regeln als Dauerlösung auf.

Reality Check

• Geprüfte Grundlage: offizielle OpenClaw-Dokumentation, CLI-Hilfe und aktuelles Runtime-Schema; kein eigener Mattermost-End-to-End-Test.
• Geeignet für: selbst gehostete Team-Chats mit kontrollierbarem Bot-Zugriff und bekanntem Netzweg.
• Häufige Fehlergrenzen: Plugin-Ladestatus, Bot-Mitgliedschaft, Pairing, private Zielnetze und Callback-Erreichbarkeit.
• Sicherheitsrelevant: Bot-Token, offene Allowlists und dangerouslyAllowPrivateNetwork.
• Recovery: Runtime prüfen, Fehler im Live-Log reproduzieren und beschädigte Plugin-Abhängigkeiten mit openclaw doctor --fix reparieren.

Kernpunkte

Ein belastbares Mattermost-Setup beginnt mit Plugin, Bot-Mitgliedschaft und einer erfolgreichen Channel-Probe. Danach testest du DMs per Pairing und Channel-Nachrichten mit geöffnetem Gateway-Log.

channels.mattermost.chatmode ist ein gültiger Runtime-Pfad. Die zulässigen Werte sind oncall, onmessage und onchar. Gruppen bleiben mit groupPolicy: "allowlist" standardmäßig begrenzt.

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