Mattermost

• native und nativeSkills verwenden standardmäßig "auto", was für Mattermost als deaktiviert aufgelöst wird. Setzen Sie sie ausdrücklich auf true.
• callbackPath verwendet standardmäßig /api/channels/mattermost/command.
• Wenn callbackUrl weggelassen wird, leitet OpenClaw http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath> ab. Bei Platzhalter-Bind-Hosts (0.0.0.0, ::) wird auf localhost zurückgegriffen.
• Bei Konfigurationen mit mehreren Konten kann commands auf der obersten 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 (sie werden bei der Registrierung übersprungen); vom Bot erstellte Befehle werden aktualisiert oder neu erstellt, wenn sich die Callback-URL geändert hat.
• Befehls-Callbacks werden anhand der befehlsspezifischen Token validiert, die Mattermost zurückgibt, wenn OpenClaw oc_* Befehle registriert.
• OpenClaw aktualisiert die aktuelle Mattermost-Befehlsregistrierung, bevor jeder Callback akzeptiert wird. Dadurch werden veraltete Token gelöschter oder neu generierter Slash-Befehle ohne Neustart des Gateways nicht mehr akzeptiert.
• Die Callback-Validierung schlägt sicher 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 der Start neuer Abfragen wird pro Befehl ratenbegrenzt, um die Belastung durch Wiederholungsangriffe zu begrenzen.
• Slash-Callbacks schlagen sicher 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 für einen anderen Befehl nicht erreichen).
• Akzeptierte Callbacks werden mit einer flüchtigen Antwort „Verarbeitung läuft …“ bestätigt; die eigentliche Antwort trifft als normale Nachricht ein.

Der Callback-Endpunkt muss vom Mattermost-Server aus 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 per Reverse-Proxy an OpenClaw weiter.
• Eine schnelle Prüfung ist curl https://<gateway-host>/api/channels/mattermost/command; eine GET-Anfrage sollte 405 Method Not Allowed von OpenClaw zurückgeben, nicht 404.

Wenn Ihre Callback-Ziele private, Tailnet- oder interne Adressen sind, setzen Sie Mattermost ServiceSettings.AllowedUntrustedInternalConnections so, 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 Vorschauentwurf, der mit zunehmendem Antwortumfang bearbeitet und anschließend mit der vollständigen Antwort finalisiert wird.
• block wechselt die Vorschau zwischen abgeschlossenen Text- und Tool-Aktivitätsblöcken, sodass jeder Block als eigener Beitrag sichtbar bleibt, statt an Ort und Stelle überschrieben zu werden. Parallele und aufeinanderfolgende Tool-Aktualisierungen verwenden gemeinsam den aktuellen Tool-Aktivitätsbeitrag.
• progress zeigt während der Generierung eine Statusvorschau und veröffentlicht die endgültige Antwort erst nach Abschluss.
• off deaktiviert das Vorschau-Streaming. Mit streaming.block.enabled: true werden abgeschlossene Assistentenblöcke weiterhin als normale Blockantworten (separate Beiträge) statt als einzelner zusammengeführter endgültiger Beitrag zugestellt.

• Wenn der Stream nicht an Ort und Stelle finalisiert werden kann (beispielsweise weil der Beitrag während des Streamings gelöscht wurde), sendet OpenClaw ersatzweise einen neuen endgültigen Beitrag, damit die Antwort niemals verloren geht.
• Nutzdaten, die ausschließlich Gedankengänge enthalten, werden in Kanalbeiträgen unterdrückt, einschließlich Text, der als > Thinking-Blockzitat eingeht. Setzen Sie /reasoning on, um Gedankengänge auf anderen Oberflächen anzuzeigen; der endgültige Mattermost-Beitrag enthält nur die Antwort.
• Die Kanalzuordnungsmatrix 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 (Mattermost-Routing-Beschränkung).
• Klicks, deren action_id mit keiner Aktion des ursprünglichen Beitrags übereinstimmt, werden mit 403 („Unbekannte Aktion“) abgelehnt.

• channels.mattermost.capabilities: Array von Funktionszeichenfolgen. Fügen Sie "inlineButtons" hinzu, um die Beschreibung des Schaltflächen-Tools 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 dessen Bind-Host nicht direkt erreichen kann.
• Bei Konfigurationen mit mehreren Konten können Sie dasselbe Feld auch unter channels.mattermost.accounts.<id>.interactions.callbackBaseUrl festlegen.
• Wenn interactions.callbackBaseUrl weggelassen wird, leitet OpenClaw die Callback-URL aus gateway.customBindHost + gateway.port (Standard 18789) ab und greift anschließend auf http://localhost:<port> zurück. 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/im selben Netzwerk-Namespace ausgeführt werden.
• channels.mattermost.interactions.allowedSourceIps: Quell-IP-Zulassungsliste für Schaltflächen-Callbacks. Ohne diese werden nur Loopback-Quellen (127.0.0.1, ::1) akzeptiert. Daher muss ein entfernter Mattermost-Server hier in die Zulassungsliste aufgenommen 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 ermittelt wird.
• Wenn Ihr Callback-Ziel privat/im Tailnet/intern ist, fügen Sie dessen Host/Domain zu Mattermost ServiceSettings.AllowedUntrustedInternalConnections hinzu.

• Pythons json.dumps fügt standardmäßig Leerzeichen hinzu ({"key": "val"}). Verwenden Sie separators=(",", ":"), damit die Ausgabe dem kompakten Format von JavaScript entspricht ({"key":"val"}).
• Signieren Sie stets alle Kontextfelder (mit Ausnahme von _token). Der Gateway entfernt _token und signiert anschließend alle verbleibenden Felder. Das Signieren einer Teilmenge führt zu einem stillen Verifizierungsfehler.
• 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 aus dem Bot-Token ab (deterministisch), nicht aus zufälligen Bytes. Das Geheimnis muss in dem Prozess, der die Schaltflächen erstellt, und im Gateway, der sie verifiziert, 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/LAN-Mattermost-Hosts 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 bzw. das falsche Konto.
  • Mattermost verfügt noch über alte Befehle, die auf ein vorheriges Callback-Ziel verweisen.
  • Der Gateway wurde neu gestartet, ohne die Slash-Befehle erneut zu aktivieren.
• Wenn native Slash-Befehle nicht mehr funktionieren, prüfen Sie die Protokolle auf mattermost: failed to register slash commands oder mattermost: native slash commands enabled but no commands could be registered.
• Wenn callbackUrl weggelassen wird und die Protokolle davor warnen, dass der Callback zu einer Loopback-URL wie http://localhost:18789/... aufgelöst wurde, ist diese URL wahrscheinlich nur erreichbar, wenn Mattermost im selben Host-/Netzwerk-Namespace wie OpenClaw ausgeführt wird. Legen Sie stattdessen explizit eine extern erreichbare commands.callbackUrl fest.

• Schaltflächen erscheinen als weiße Kästchen oder überhaupt nicht: Die Schaltflächendaten sind fehlerhaft. Jede Präsentationsschaltfläche benötigt label und value (Schaltflächen, bei denen eines davon fehlt, werden verworfen).
• Schaltflächen werden dargestellt, aber Klicks haben keine Wirkung: Stellen Sie sicher, dass der Gateway vom Mattermost-Server aus erreichbar ist, die IP-Adresse des Mattermost-Servers in channels.mattermost.interactions.allowedSourceIps enthalten ist (ohne diese Angabe wird nur Loopback akzeptiert) und ServiceSettings.AllowedUntrustedInternalConnections bei privaten Zielen den Callback-Host enthält.
• Schaltflächen geben beim Klicken 404 zurück: Die id der Schaltfläche enthält wahrscheinlich Bindestriche oder Unterstriche. Der Aktionsrouter von Mattermost funktioniert nicht mit nicht alphanumerischen IDs. Verwenden Sie ausschließlich [a-zA-Z0-9].
• Der Gateway protokolliert rejected callback source: Der Klick kam von einer IP-Adresse außerhalb von interactions.allowedSourceIps. Nehmen Sie den Mattermost-Server oder Ihren Ingress in die Positivliste auf und setzen Sie gateway.trustedProxies, wenn Sie einen Reverse-Proxy verwenden.
• Der Gateway protokolliert invalid _token: HMAC stimmt nicht überein. Prüfen Sie, ob Sie alle Kontextfelder (nicht nur eine Teilmenge) signieren, sortierte Schlüssel und kompaktes JSON (ohne Leerzeichen) verwenden. Weitere Informationen finden Sie im HMAC-Abschnitt oben.
• 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 id-Aktion des Beitrags überein. Setzen Sie beide auf denselben bereinigten Wert.
• Der Agent bietet keine Schaltflächen an: Fügen Sie capabilities: ["inlineButtons"] zur Mattermost-Kanalkonfiguration hinzu.