Mattermost

• native und nativeSkills haben standardmäßig den Wert "auto", der für Mattermost als deaktiviert aufgelöst wird. Setzen Sie beide explizit auf true.
• callbackPath ist standardmäßig /api/channels/mattermost/command.
• Wenn callbackUrl nicht angegeben ist, leitet OpenClaw http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath> ab. Platzhalter-Bind-Hosts (0.0.0.0, ::) fallen auf localhost zurück.
• Bei Konfigurationen mit mehreren Konten kann commands auf oberster Ebene oder unter channels.mattermost.accounts.<id>.commands festgelegt werden (Kontowerte überschreiben Felder der obersten Ebene).
• Vorhandene Slash-Befehle mit demselben Auslöser, die von anderen Integrationen erstellt wurden, bleiben unverändert (die Registrierung überspringt sie). Vom Bot erstellte Befehle werden aktualisiert oder neu erstellt, wenn sich die Callback-URL ändert.
• Befehls-Callbacks werden anhand der Token validiert, die Mattermost für jeden Befehl zurückgibt, wenn OpenClaw die oc_*-Befehle registriert.
• OpenClaw aktualisiert die aktuelle Mattermost-Befehlsregistrierung, bevor es einen Callback akzeptiert. Dadurch werden veraltete Token gelöschter oder neu generierter Slash-Befehle ohne Neustart des Gateways nicht mehr akzeptiert.
• Die Callback-Validierung schlägt sicher geschlossen fehl, wenn die Mattermost-API nicht bestätigen kann, dass der Befehl noch aktuell ist. Fehlgeschlagene Validierungen werden kurzzeitig zwischengespeichert, gleichzeitige Abfragen werden zusammengeführt und neue Abfragen werden pro Befehl ratenbegrenzt, um den Replay-Druck zu begrenzen.
• Slash-Callbacks schlagen sicher geschlossen fehl, wenn die Registrierung fehlgeschlagen ist, der Start nur teilweise abgeschlossen wurde oder das Callback-Token nicht mit dem registrierten Token des aufgelösten Befehls übereinstimmt (ein für einen Befehl gültiges Token kann die vorgelagerte Validierung eines anderen Befehls nicht erreichen).
• Akzeptierte Callbacks werden mit einer kurzlebigen Antwort „Verarbeitung läuft ...“ bestätigt; die eigentliche Antwort trifft als normale Nachricht ein.

Der Callback-Endpunkt muss vom Mattermost-Server erreichbar sein.

• Setzen Sie callbackUrl nicht auf localhost, es sei denn, Mattermost wird auf demselben Host bzw. im selben Netzwerk-Namespace wie OpenClaw ausgeführt.
• Setzen Sie callbackUrl nicht auf Ihre Mattermost-Basis-URL, es sei denn, diese URL leitet /api/channels/mattermost/command über einen Reverse-Proxy an OpenClaw weiter.
• Eine schnelle Prüfung ist curl https://<gateway-host>/api/channels/mattermost/command; eine GET-Anfrage sollte von OpenClaw 405 Method Not Allowed und nicht 404 zurückgeben.

Wenn Ihr Callback auf private/Tailnet-/interne Adressen verweist, legen Sie Mattermost ServiceSettings.AllowedUntrustedInternalConnections so fest, dass der Callback-Host bzw. die Callback-Domain enthalten ist.

Verwenden Sie Host-/Domain-Einträge, keine vollständigen URLs.

• Richtig: gateway.tailnet-name.ts.net
• Falsch: https://gateway.tailnet-name.ts.net

• partial (Standard): ein Vorschaubeitrag, der mit zunehmender Antwortlänge bearbeitet und anschließend mit der vollständigen Antwort finalisiert wird.
• block wechselt die Vorschau zwischen abgeschlossenem Text und Werkzeugaktivitätsblöcken, sodass jeder Block als eigener Beitrag sichtbar bleibt, statt direkt an Ort und Stelle überschrieben zu werden. Parallele und aufeinanderfolgende Werkzeugaktualisierungen verwenden gemeinsam den aktuellen Werkzeugaktivitätsbeitrag.
• progress zeigt während der Generierung eine Statusvorschau an und veröffentlicht erst nach Abschluss die endgültige Antwort.
• off deaktiviert das Vorschau-Streaming. Mit blockStreaming: true werden abgeschlossene Assistentenblöcke weiterhin als normale Blockantworten (separate Beiträge) statt als einzelner zusammengefasster Abschlussbeitrag zugestellt.

• Wenn der Stream nicht direkt an Ort und Stelle finalisiert werden kann (beispielsweise weil der Beitrag während des Streamings gelöscht wurde), sendet OpenClaw ersatzweise einen neuen Abschlussbeitrag, damit die Antwort nie verloren geht.
• Nutzlasten, die ausschließlich Denkprozesse enthalten, werden in Kanalbeiträgen unterdrückt. Dies gilt auch für Text, der als > Thinking-Blockzitat eintrifft. Legen Sie /reasoning on fest, um Denkprozesse in anderen Oberflächen anzuzeigen; der Mattermost-Abschlussbeitrag enthält nur die Antwort.
• Die Zuordnungsmatrix für Kanäle finden Sie unter Streaming.

• Schaltflächen-Callbacks verwenden eine HMAC-SHA256-Verifizierung (automatisch, keine Konfiguration erforderlich).
• Beim Klicken wird der gesamte Anhangsblock ersetzt, sodass alle Schaltflächen gemeinsam entfernt werden – eine teilweise Entfernung ist nicht möglich.
• Aktions-IDs mit Bindestrichen oder Unterstrichen werden automatisch bereinigt (Einschränkung des Mattermost-Routings).
• Klicks, deren action_id keiner Aktion im ursprünglichen Beitrag entspricht, werden mit 403 („Unbekannte Aktion“) abgelehnt.

• channels.mattermost.capabilities: Array von Funktionszeichenfolgen. Fügen Sie "inlineButtons" hinzu, um die Werkzeugbeschreibung für Schaltflächen im Agenten-Systemprompt zu aktivieren.
• channels.mattermost.interactions.callbackBaseUrl: optionale externe Basis-URL für Schaltflächen-Callbacks (beispielsweise https://gateway.example.com). Verwenden Sie diese, wenn Mattermost den Gateway unter seinem Bind-Host nicht direkt erreichen kann.
• In Konfigurationen mit mehreren Konten können Sie dasselbe Feld auch unter channels.mattermost.accounts.<id>.interactions.callbackBaseUrl festlegen.
• Wenn interactions.callbackBaseUrl nicht angegeben ist, leitet OpenClaw die Callback-URL aus gateway.customBindHost + gateway.port (Standardwert 18789) ab und verwendet anschließend ersatzweise http://localhost:<port>. Der Callback-Pfad lautet /mattermost/interactions/<accountId>.
• Erreichbarkeitsregel: Die Schaltflächen-Callback-URL muss vom Mattermost-Server aus erreichbar sein. localhost funktioniert nur, wenn Mattermost und OpenClaw auf demselben Host beziehungsweise im selben Netzwerk-Namespace ausgeführt werden.
• channels.mattermost.interactions.allowedSourceIps: Zulassungsliste für Quell-IP-Adressen von Schaltflächen-Callbacks. Ohne diese werden nur local loopback-Quellen (127.0.0.1, ::1) akzeptiert. Daher muss ein entfernter Mattermost-Server hier zugelassen werden, andernfalls werden seine Klicks mit 403 abgelehnt. Legen Sie hinter einem Reverse-Proxy außerdem gateway.trustedProxies fest, damit die tatsächliche Client-IP aus weitergeleiteten Headern abgeleitet wird.
• Wenn Ihr Callback-Ziel privat, im Tailnet oder intern ist, fügen Sie dessen Host/Domain in Mattermost zu ServiceSettings.AllowedUntrustedInternalConnections hinzu.

• Pythons json.dumps fügt standardmäßig Leerzeichen hinzu ({"key": "val"}). Verwenden Sie separators=(",", ":"), damit die Ausgabe dem kompakten JavaScript-Format ({"key":"val"}) entspricht.
• Signieren Sie stets alle Kontextfelder (mit Ausnahme von _token). Der Gateway entfernt _token und signiert anschließend alle verbleibenden Felder. Das Signieren nur einer Teilmenge führt zu einem Verifizierungsfehler ohne Meldung.
• Verwenden Sie sort_keys=True – der Gateway sortiert die Schlüssel vor dem Signieren, und Mattermost kann die Kontextfelder beim Speichern der Nutzlast neu anordnen.
• Leiten Sie das Geheimnis deterministisch aus dem Bot-Token ab, nicht aus zufälligen Bytes. Das Geheimnis muss in dem Prozess, der die Schaltflächen erstellt, und im verifizierenden Gateway identisch sein.

Stellen Sie sicher, dass sich der Bot im Kanal befindet, und erwähnen Sie ihn (oncall), verwenden Sie ein Auslösepräfix (onchar) oder setzen Sie chatmode: "onmessage".

• Überprüfen Sie das Bot-Token, die Basis-URL und ob das Konto aktiviert ist.
• Probleme mit mehreren Konten: Umgebungsvariablen gelten nur für das Konto default.
• Private Mattermost-Hosts oder Mattermost-Hosts im LAN benötigen network.dangerouslyAllowPrivateNetwork: true (der SSRF-Schutz blockiert standardmäßig private IP-Adressen).

• Unauthorized: invalid command token.: OpenClaw hat das Callback-Token nicht akzeptiert. Typische Ursachen:
  • Die Registrierung des Slash-Befehls ist fehlgeschlagen oder wurde beim Start nur teilweise abgeschlossen.
  • Der Callback erreicht den falschen Gateway oder das falsche Konto.
  • Mattermost verfügt noch über alte Befehle, die auf ein früheres Callback-Ziel verweisen.
  • Der Gateway wurde neu gestartet, ohne die Slash-Befehle erneut zu aktivieren.
• Wenn native Slash-Befehle nicht mehr funktionieren, suchen Sie in den Protokollen nach mattermost: failed to register slash commands oder mattermost: native slash commands enabled but no commands could be registered.
• Wenn callbackUrl nicht angegeben ist und die Protokolle davor warnen, dass der Callback in eine Loopback-URL wie http://localhost:18789/... aufgelöst wurde, ist diese URL wahrscheinlich nur erreichbar, wenn Mattermost auf demselben Host bzw. im selben Netzwerk-Namespace wie OpenClaw ausgeführt wird. Legen Sie stattdessen eine explizite, extern erreichbare commands.callbackUrl fest.

• Schaltflächen werden als weiße Kästchen oder gar nicht angezeigt: Die Schaltflächendaten sind fehlerhaft. Jede Präsentationsschaltfläche benötigt ein label und einen value (Schaltflächen, denen eines davon fehlt, werden verworfen).
• Schaltflächen werden dargestellt, aber Klicks bewirken nichts: Überprüfen Sie, ob der Gateway vom Mattermost-Server aus erreichbar ist, ob die IP-Adresse des Mattermost-Servers in channels.mattermost.interactions.allowedSourceIps enthalten ist (ohne diese Einstellung wird nur local loopback akzeptiert) und ob ServiceSettings.AllowedUntrustedInternalConnections bei privaten Zielen den Callback-Host enthält.
• Schaltflächen geben beim Klicken den Fehler 404 zurück: Die Schaltflächen-id enthält wahrscheinlich Bindestriche oder Unterstriche. Der Action-Router von Mattermost funktioniert nicht mit IDs, die nicht alphanumerisch sind. Verwenden Sie ausschließlich [a-zA-Z0-9].
• Der Gateway protokolliert rejected callback source: Der Klick stammt von einer IP-Adresse außerhalb von interactions.allowedSourceIps. Setzen Sie den Mattermost-Server oder Ihren Ingress auf die Zulassungsliste und legen Sie bei Verwendung eines Reverse-Proxys gateway.trustedProxies fest.
• Der Gateway protokolliert invalid _token: HMAC stimmt nicht überein. Stellen Sie sicher, dass Sie alle Kontextfelder signieren (nicht nur eine Teilmenge), sortierte Schlüssel und kompaktes JSON (ohne Leerzeichen) verwenden. Weitere Informationen finden Sie im obigen HMAC-Abschnitt.
• Der Gateway protokolliert missing _token in context: Das Feld _token ist nicht im Kontext der Schaltfläche enthalten. Stellen Sie sicher, dass es beim Erstellen der Integrationsnutzlast einbezogen wird.
• Der Gateway lehnt den Klick mit Unknown action ab: context.action_id stimmt mit keiner Action-id im Beitrag überein. Setzen Sie beide auf denselben bereinigten Wert.
• Der Agent bietet keine Schaltflächen an: Fügen Sie der Mattermost-Kanalkonfiguration capabilities: ["inlineButtons"] hinzu.