Mattermost

• native: "auto" ist für Mattermost standardmäßig deaktiviert. Setzen Sie native: true, um es zu aktivieren.
• Wenn callbackUrl weggelassen wird, leitet OpenClaw eine URL aus Gateway-Host/Port + callbackPath ab.
• Bei Setups mit mehreren Konten kann commands auf oberster Ebene oder unter channels.mattermost.accounts.<id>.commands festgelegt werden (Kontowerte überschreiben Felder der obersten Ebene).
• Befehls-Callbacks werden mit den pro Befehl geltenden Tokens validiert, die Mattermost zurückgibt, wenn OpenClaw oc_*-Befehle registriert.
• OpenClaw aktualisiert die aktuelle Mattermost-Befehlsregistrierung, bevor jeder Callback akzeptiert wird, sodass veraltete Tokens aus gelöschten oder neu generierten Slash-Befehlen nicht ohne Gateway-Neustart weiter akzeptiert werden.
• Die Callback-Validierung schlägt geschlossen fehl, wenn die Mattermost-API nicht bestätigen kann, dass der Befehl noch aktuell ist; fehlgeschlagene Validierungen werden kurz zwischengespeichert, gleichzeitige Lookups werden zusammengeführt, und neue Lookup-Starts werden pro Befehl rate-limitiert, um Replay-Druck zu begrenzen.
• Slash-Callbacks schlagen geschlossen fehl, wenn die Registrierung fehlgeschlagen ist, der Start nur teilweise abgeschlossen wurde oder der Callback-Token nicht mit dem registrierten Token des aufgelösten Befehls übereinstimmt (ein Token, der für einen Befehl gültig ist, kann keine Upstream-Validierung für einen anderen Befehl erreichen).

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

• Setzen Sie callbackUrl nicht auf localhost, es sei denn, Mattermost läuft auf demselben Host/in demselben Netzwerk-Namespace wie OpenClaw.
• 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; ein GET sollte von OpenClaw 405 Method Not Allowed zurückgeben, nicht 404.

Wenn Ihr Callback auf private/tailnet/interne Adressen zielt, setzen Sie Mattermost ServiceSettings.AllowedUntrustedInternalConnections so, dass der Callback-Host/die Callback-Domain enthalten ist.

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

• Gut: gateway.tailnet-name.ts.net
• Schlecht: https://gateway.tailnet-name.ts.net

• partial ist die übliche Wahl: ein Vorschau-Post, der bearbeitet wird, während die Antwort wächst, und anschließend mit der vollständigen Antwort finalisiert wird.
• block verwendet Entwurfs-Chunks im Append-Stil innerhalb des Vorschau-Posts.
• progress zeigt während der Generierung eine Statusvorschau und postet die endgültige Antwort erst nach Abschluss.
• off deaktiviert Preview-Streaming.

• Wenn der Stream nicht direkt finalisiert werden kann (zum Beispiel, weil der Post mitten im Stream gelöscht wurde), fällt OpenClaw darauf zurück, einen neuen finalen Post zu senden, damit die Antwort nie verloren geht.
• Reine Reasoning-Payloads werden aus Kanal-Posts unterdrückt, einschließlich Text, der als > Reasoning:-Blockzitat eintrifft. Setzen Sie /reasoning on, um Denken in anderen Oberflächen zu sehen; der finale Mattermost-Post enthält nur die Antwort.
• Siehe Streaming für die Channel-Mapping-Matrix.

• Button-Callbacks verwenden HMAC-SHA256-Verifizierung (automatisch, keine Konfiguration erforderlich).
• Mattermost entfernt Callback-Daten aus seinen API-Antworten (Sicherheitsfunktion), daher werden beim Klicken alle Buttons entfernt - partielles Entfernen ist nicht möglich.
• Aktions-IDs mit Bindestrichen oder Unterstrichen werden automatisch bereinigt (Mattermost-Routing-Einschränkung).

• channels.mattermost.capabilities: Array von Capability-Strings. Fügen Sie "inlineButtons" hinzu, um die Beschreibung des Button-Tools im System-Prompt des Agenten zu aktivieren.
• channels.mattermost.interactions.callbackBaseUrl: optionale externe Basis-URL für Button-Callbacks (zum Beispiel https://gateway.example.com). Verwenden Sie dies, wenn Mattermost den Gateway unter seinem Bind-Host nicht direkt erreichen kann.
• In Multi-Account-Setups können Sie dasselbe Feld auch unter channels.mattermost.accounts.<id>.interactions.callbackBaseUrl setzen.
• Wenn interactions.callbackBaseUrl weggelassen wird, leitet OpenClaw die Callback-URL aus gateway.customBindHost + gateway.port ab und fällt dann auf http://localhost:<port> zurück.
• Erreichbarkeitsregel: Die Button-Callback-URL muss vom Mattermost-Server erreichbar sein. localhost funktioniert nur, wenn Mattermost und OpenClaw auf demselben Host/Netzwerk-Namespace ausgeführt werden.
• Wenn Ihr Callback-Ziel privat/tailnet/intern ist, fügen Sie seinen Host/seine Domain zu Mattermost ServiceSettings.AllowedUntrustedInternalConnections hinzu.

• Pythons json.dumps fügt standardmäßig Leerzeichen hinzu ({"key": "val"}). Verwenden Sie separators=(",", ":"), um zur kompakten Ausgabe von JavaScript zu passen ({"key":"val"}).
• Signieren Sie immer alle Context-Felder (abzüglich _token). Der Gateway entfernt _token und signiert dann alles Verbleibende. Das Signieren einer Teilmenge führt zu einem stillschweigenden Verifizierungsfehler.
• Verwenden Sie sort_keys=True - der Gateway sortiert Schlüssel vor dem Signieren, und Mattermost kann Context-Felder beim Speichern der Payload neu anordnen.
• Leiten Sie das Secret aus dem Bot-Token ab (deterministisch), nicht aus zufälligen Bytes. Das Secret muss in dem Prozess, der Buttons erstellt, und im Gateway, der verifiziert, identisch sein.

Stellen Sie sicher, dass der Bot im Kanal ist, und erwähnen Sie ihn (oncall), verwenden Sie ein Trigger-Präfix (onchar), oder setzen Sie chatmode: "onmessage".

• Prüfen Sie das Bot-Token, die Basis-URL und ob der Account aktiviert ist.
• Multi-Account-Probleme: Env-Vars gelten nur für den default-Account.

• Unauthorized: invalid command token.: OpenClaw hat das Callback-Token nicht akzeptiert. Typische Ursachen:
  • Registrierung des Slash-Befehls ist beim Start fehlgeschlagen oder nur teilweise abgeschlossen
  • der Callback trifft den falschen Gateway/Account
  • Mattermost hat noch alte Befehle, die auf ein früheres Callback-Ziel zeigen
  • der Gateway wurde neu gestartet, ohne Slash-Befehle erneut zu aktivieren
• Wenn native Slash-Befehle nicht mehr funktionieren, prüfen Sie die Logs auf mattermost: failed to register slash commands oder mattermost: native slash commands enabled but no commands could be registered.
• Wenn callbackUrl weggelassen wird und Logs warnen, dass der Callback zu http://127.0.0.1:18789/... aufgelöst wurde, ist diese URL wahrscheinlich nur erreichbar, wenn Mattermost auf demselben Host/Netzwerk-Namespace wie OpenClaw ausgeführt wird. Setzen Sie stattdessen eine explizite, extern erreichbare commands.callbackUrl.

• Buttons erscheinen als weiße Kästen: Der Agent sendet möglicherweise fehlerhafte Button-Daten. Prüfen Sie, dass jeder Button sowohl text- als auch callback_data-Felder hat.
• Buttons werden gerendert, aber Klicks bewirken nichts: Verifizieren Sie, dass AllowedUntrustedInternalConnections in der Mattermost-Serverkonfiguration 127.0.0.1 localhost enthält und dass EnablePostActionIntegration in ServiceSettings true ist.
• Buttons geben beim Klicken 404 zurück: Die Button-id enthält wahrscheinlich Bindestriche oder Unterstriche. Der Aktionsrouter von Mattermost bricht bei nicht alphanumerischen IDs. Verwenden Sie nur [a-zA-Z0-9].
• Gateway-Logs zeigen invalid _token: HMAC stimmt nicht überein. Prüfen Sie, dass Sie alle Context-Felder signieren (nicht eine Teilmenge), sortierte Schlüssel verwenden und kompaktes JSON nutzen (keine Leerzeichen). Siehe den HMAC-Abschnitt oben.
• Gateway-Logs zeigen missing _token in context: Das Feld _token befindet sich nicht im Context des Buttons. Stellen Sie sicher, dass es beim Erstellen der Integrations-Payload enthalten ist.
• Bestätigung zeigt Raw-ID statt Button-Namen: context.action_id stimmt nicht mit der id des Buttons überein. Setzen Sie beide auf denselben bereinigten Wert.
• Agent kennt Buttons nicht: Fügen Sie capabilities: ["inlineButtons"] zur Mattermost-Kanalkonfiguration hinzu.