Mattermost

• native en nativeSkills zijn standaard ingesteld op "auto", wat voor Mattermost wordt geïnterpreteerd als uitgeschakeld. Stel ze expliciet in op true.
• callbackPath is standaard ingesteld op /api/channels/mattermost/command.
• Als callbackUrl is weggelaten, leidt OpenClaw http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath> af. Bindhosts met jokertekens (0.0.0.0, ::) vallen terug op localhost.
• Voor configuraties met meerdere accounts kan commands op het hoogste niveau of onder channels.mattermost.accounts.<id>.commands worden ingesteld (accountwaarden overschrijven velden op het hoogste niveau).
• Bestaande slash-opdrachten met dezelfde trigger die door andere integraties zijn gemaakt, blijven ongewijzigd (de registratie slaat ze over); opdrachten die door de bot zijn gemaakt, worden bijgewerkt of opnieuw gemaakt wanneer de callback-URL afwijkt.
• Callbacks van opdrachten worden gevalideerd met de tokens per opdracht die Mattermost retourneert wanneer OpenClaw oc_* opdrachten registreert.
• OpenClaw vernieuwt de huidige registratie van Mattermost-opdrachten voordat elke callback wordt geaccepteerd, zodat verouderde tokens van verwijderde of opnieuw gegenereerde slash-opdrachten niet meer worden geaccepteerd zonder de Gateway opnieuw te starten.
• Callbackvalidatie mislukt gesloten als de Mattermost-API niet kan bevestigen dat de opdracht nog actueel is; mislukte validaties worden kort in de cache bewaard, gelijktijdige zoekacties worden samengevoegd en nieuwe zoekacties worden per opdracht in frequentie beperkt om de druk van replay-aanvallen te begrenzen.
• Slash-callbacks mislukken gesloten wanneer de registratie is mislukt, het opstarten gedeeltelijk was of het callbacktoken niet overeenkomt met het geregistreerde token van de gevonden opdracht (een token dat geldig is voor één opdracht kan de bovenliggende validatie voor een andere opdracht niet bereiken).
• Geaccepteerde callbacks worden bevestigd met een tijdelijk antwoord "Bezig met verwerken..."; het werkelijke antwoord volgt als een normaal bericht.

Het callback-eindpunt moet bereikbaar zijn vanaf de Mattermost-server.

• Stel callbackUrl niet in op localhost, tenzij Mattermost op dezelfde host of in dezelfde netwerknaamruimte als OpenClaw draait.
• Stel callbackUrl niet in op de basis-URL van Mattermost, tenzij die URL /api/channels/mattermost/command via een reverse proxy naar OpenClaw doorstuurt.
• Een snelle controle is curl https://<gateway-host>/api/channels/mattermost/command; een GET-verzoek moet 405 Method Not Allowed van OpenClaw retourneren, niet 404.

Als je callback is gericht op privé-, tailnet- of interne adressen, stel je ServiceSettings.AllowedUntrustedInternalConnections van Mattermost zo in dat de callbackhost of het callbackdomein wordt opgenomen.

Gebruik host- of domeinvermeldingen, geen volledige URL's.

• Goed: gateway.tailnet-name.ts.net
• Fout: https://gateway.tailnet-name.ts.net

• partial (standaard): één previewbericht dat wordt bewerkt terwijl het antwoord groeit en daarna wordt afgerond met het volledige antwoord.
• block wisselt de preview tussen voltooide tekst- en toolactiviteitsblokken, zodat elk blok als afzonderlijk bericht zichtbaar blijft in plaats van ter plaatse te worden overschreven. Parallelle en opeenvolgende toolupdates delen het huidige toolactiviteitsbericht.
• progress toont tijdens het genereren een statuspreview en plaatst het definitieve antwoord pas na voltooiing.
• off schakelt previewstreaming uit. Met streaming.block.enabled: true worden voltooide assistentblokken nog steeds als normale blokantwoorden (afzonderlijke berichten) bezorgd, in plaats van als één samengevoegd definitief bericht.

• Als de stream niet ter plaatse kan worden afgerond (bijvoorbeeld omdat het bericht tijdens het streamen is verwijderd), valt OpenClaw terug op het verzenden van een nieuw definitief bericht, zodat het antwoord nooit verloren gaat.
• Payloads met alleen denkwerk worden onderdrukt in kanaalberichten, inclusief tekst die als een > Thinking-blokcitaat binnenkomt. Stel /reasoning on in om denkwerk op andere oppervlakken te zien; het definitieve Mattermost-bericht bevat alleen het antwoord.
• Zie Streaming voor de kanaaltoewijzingsmatrix.

• Knopcallbacks gebruiken HMAC-SHA256-verificatie (automatisch, geen configuratie nodig).
• Bij een klik wordt het volledige bijlageblok vervangen, zodat alle knoppen tegelijk worden verwijderd - gedeeltelijke verwijdering is niet mogelijk.
• Actie-ID's met koppeltekens of onderstrepingstekens worden automatisch opgeschoond (beperking van Mattermost-routering).
• Klikken waarvan action_id niet overeenkomt met een actie in het oorspronkelijke bericht, worden geweigerd met 403 ("Onbekende actie").

• channels.mattermost.capabilities: reeks met mogelijkheden. Voeg "inlineButtons" toe om de beschrijving van de knoptool in de systeemprompt van de agent in te schakelen.
• channels.mattermost.interactions.callbackBaseUrl: optionele externe basis-URL voor knopcallbacks (bijvoorbeeld https://gateway.example.com). Gebruik dit wanneer Mattermost de Gateway niet rechtstreeks via de bindhost kan bereiken.
• Bij configuraties met meerdere accounts kun je hetzelfde veld ook instellen onder channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Als interactions.callbackBaseUrl wordt weggelaten, leidt OpenClaw de callback-URL af van gateway.customBindHost + gateway.port (standaard 18789) en valt daarna terug op http://localhost:<port>. Het callbackpad is /mattermost/interactions/<accountId>.
• Bereikbaarheidsregel: de URL voor de knopcallback moet bereikbaar zijn vanaf de Mattermost-server. localhost werkt alleen wanneer Mattermost en OpenClaw op dezelfde host/netwerknaamruimte draaien.
• channels.mattermost.interactions.allowedSourceIps: toelatingslijst met bron-IP-adressen voor knopcallbacks. Zonder deze lijst worden alleen loopbackbronnen (127.0.0.1, ::1) geaccepteerd. Een externe Mattermost-server moet hier dus aan de toelatingslijst worden toegevoegd, anders worden de klikken geweigerd met 403. Stel achter een reverse proxy ook gateway.trustedProxies in, zodat het werkelijke client-IP-adres uit doorgestuurde headers wordt afgeleid.
• Als je callbackdoel privé/op een tailnet/intern is, voeg je de host/het domein ervan toe aan ServiceSettings.AllowedUntrustedInternalConnections van Mattermost.

• Python's json.dumps voegt standaard spaties toe ({"key": "val"}). Gebruik separators=(",", ":") zodat dit overeenkomt met de compacte uitvoer van JavaScript ({"key":"val"}).
• Onderteken altijd alle contextvelden (behalve _token). De Gateway verwijdert _token en ondertekent vervolgens alles wat overblijft. Het ondertekenen van een subset veroorzaakt een stille verificatiefout.
• Gebruik sort_keys=True: de Gateway sorteert sleutels vóór ondertekening en Mattermost kan contextvelden opnieuw ordenen wanneer de payload wordt opgeslagen.
• Leid het geheim af van het bottoken (deterministisch), niet van willekeurige bytes. Het geheim moet hetzelfde zijn in het proces dat knoppen maakt en de Gateway die ze verifieert.

Zorg dat de bot zich in het kanaal bevindt en vermeld deze (oncall), gebruik een triggerprefix (onchar) of stel chatmode: "onmessage" in.

• Controleer het bottoken, de basis-URL en of het account is ingeschakeld.
• Problemen met meerdere accounts: omgevingsvariabelen zijn alleen van toepassing op het default-account.
• Privé-/LAN-hosts van Mattermost vereisen network.dangerouslyAllowPrivateNetwork: true (de SSRF-beveiliging blokkeert standaard privé-IP-adressen).

• Unauthorized: invalid command token.: OpenClaw heeft het callbacktoken niet geaccepteerd. Gebruikelijke oorzaken:
  • de registratie van de slash-opdracht is mislukt of bij het opstarten slechts gedeeltelijk voltooid
  • de callback bereikt de verkeerde Gateway of het verkeerde account
  • Mattermost heeft nog oude opdrachten die naar een eerder callbackdoel verwijzen
  • de Gateway is opnieuw gestart zonder de slash-opdrachten opnieuw te activeren
• Als native slash-opdrachten niet meer werken, controleer dan de logboeken op mattermost: failed to register slash commands of mattermost: native slash commands enabled but no commands could be registered.
• Als callbackUrl is weggelaten en de logboeken waarschuwen dat de callback is omgezet naar een loopback-URL zoals http://localhost:18789/..., is die URL waarschijnlijk alleen bereikbaar wanneer Mattermost op dezelfde host/netwerknaamruimte als OpenClaw draait. Stel in plaats daarvan een expliciete, extern bereikbare commands.callbackUrl in.

• Knoppen worden als witte vakken of helemaal niet weergegeven: de knopgegevens zijn ongeldig. Elke presentatieknop heeft een label en een value nodig (knoppen waarbij een van beide ontbreekt, worden verwijderd).
• Knoppen worden weergegeven, maar klikken doet niets: controleer of de Gateway bereikbaar is vanaf de Mattermost-server, of het IP-adres van de Mattermost-server is opgenomen in channels.mattermost.interactions.allowedSourceIps (zonder deze instelling wordt alleen loopback geaccepteerd) en of ServiceSettings.AllowedUntrustedInternalConnections de callbackhost voor privédoelen bevat.
• Knoppen retourneren 404 wanneer erop wordt geklikt: de id van de knop bevat waarschijnlijk koppeltekens of underscores. De actierouter van Mattermost werkt niet met niet-alfanumerieke ID's. Gebruik alleen [a-zA-Z0-9].
• De Gateway logt rejected callback source: de klik kwam van een IP-adres buiten interactions.allowedSourceIps. Voeg de Mattermost-server of je ingress toe aan de toelatingslijst en stel gateway.trustedProxies in achter een reverse proxy.
• De Gateway logt invalid _token: HMAC komt niet overeen. Controleer of je alle contextvelden ondertekent (niet slechts een subset), gesorteerde sleutels gebruikt en compacte JSON gebruikt (zonder spaties). Zie het gedeelte over HMAC hierboven.
• De Gateway logt missing _token in context: het veld _token bevindt zich niet in de context van de knop. Zorg dat dit veld wordt opgenomen bij het opbouwen van de integratiepayload.
• De Gateway weigert de klik met Unknown action: context.action_id komt niet overeen met een id van een actie in het bericht. Stel beide in op dezelfde opgeschoonde waarde.
• De agent biedt geen knoppen aan: voeg capabilities: ["inlineButtons"] toe aan de Mattermost-kanaalconfiguratie.